---
name: agent-creator
description: "Creates new specialized agents with frontmatter, tools, delegation. Triggers: new agent, create agent, agent scaffold, specialized agent."
effort: high
disable-model-invocation: true
argument-hint: "[agent name or role]"
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# Agent Creator

$ARGUMENTS

<!-- CLAUDE_CODE_ONLY_START -->
Only in Claude Code, apply the `model-routing-patterns` skill when choosing
executors or creating agent definitions. Delegate to `codex:codex-rescue` only
when its plugin is installed, enabled and callable in this session. Otherwise
use the installed native agents and their configured models. A context without
the Agent tool returns the dispatch decision to its supervisor; it does not
invent a tool or bypass the client. Preserve explicit user choices and verify
actual completion before accepting a delegated result.
<!-- CLAUDE_CODE_ONLY_END -->

Create a new specialized agent following ai-toolkit conventions.

## Workflow

1. **Capture role** -- what problem space should the agent own?
2. **Define triggers** -- which keywords or task types should route to this agent?
3. **Choose tools** -- minimal tool set, least privilege first
4. **Choose model** -- preserve the approved tier or inherit the parent selection; verify available models and effort controls in the target client
5. **Map supporting skills** -- which knowledge skills should the agent reference?
6. **Write instructions** -- capabilities, constraints, escalation rules, deliverables
7. **Validate** -- frontmatter, naming, skills references, tool whitelist

## Required Frontmatter

```yaml
---
name: agent-name
description: "When to use this agent. Triggers: keyword1, keyword2."
tools: Read, Write, Edit
model: inherit
skills: skill-one, skill-two
---
```

## Authoring Rules

- **MUST** match filename and `name:` using lowercase-hyphen format — drift breaks routing
- **MUST** include an explicit `Triggers:` list in the description so the router can dispatch deterministically
- **NEVER** reference skills that do not exist — either create the dependency first or drop the reference
- **NEVER** grant write access to `.claude/agents/` — that authority belongs to `meta-architect` alone
- **CRITICAL**: avoid tool bloat. Every extra tool widens blast radius; start from `Read` and justify additions one by one
- Give the agent a clear boundary: what it owns and what it must escalate
- Prefer specialized, narrow responsibility over generic "do everything" agents
- `inherit` and Claude aliases are Claude Code choices, not cross-provider IDs.
  An explicit tier needs a workload reason and an approved budget. Verify the
  provider's current alias resolution instead of assuming a fixed model version.
  Codex and Copilot generators preserve the host's selection unless a native
  configuration explicitly overrides it; do not copy Claude model/effort fields.

## Agent Skeleton

```markdown
---
name: {agent-name}
description: "When to use this agent. Triggers: keyword1, keyword2."
tools: Read, Edit
model: inherit
skills: relevant-skill
---

You are a specialized agent for {domain}.

## Responsibilities
- Responsibility one
- Responsibility two

## Constraints
- Do not edit files outside owned scope unless required
- Escalate security, data-loss, or architecture risks

## Deliverables
- Clear findings
- Specific edits or recommendations
- Validation notes
```

## Validation Checklist

- [ ] Filename matches `name:` in frontmatter
- [ ] Description includes trigger words and use cases
- [ ] Tools are from the approved Claude Code tool set
- [ ] Referenced skills exist
- [ ] Model choice and supported effort match the approved workload and client
- [ ] `scripts/validate.py` passes after adding the agent

## Gotchas

- The `description` is the **only** content the model sees at routing time (progressive disclosure, tier 1). Adding triggers to the body without putting them in `description` means the agent is invisible to the router.
- `tools:` parser acceptance varies between Claude Code, ai-toolkit adapters, and downstream consumers — some accept comma-separated, some space-separated, some YAML lists. Stick to one style consistent with neighbouring agents in the repo and let `scripts/validate.py` catch drift.
- Agent `name` is capped at 64 chars; some consumers silently truncate longer names, which then **fail to match** the filename at load time. Keep names short and unambiguous.
- `skills:` can reference skills inside plugin packs; if the user has not enabled that pack, the agent fails on first invocation with an opaque "skill not found" error. Either reference only in-tree skills, or document the plugin prerequisite in the agent body.

## When NOT to Use

- For a **skill** (slash command or knowledge doc) — use `/skill-creator` instead
- For a **slash command** that is *not* an agent delegate — use `/command-creator`
- For a **plugin pack** bundling multiple agents and skills — use `/plugin-creator`
- To *modify* an existing agent — delegate to the `meta-architect` agent; this skill is create-only
- When the task is really a workflow (orchestrator + N specialists) — reach for `/orchestrate` or `/workflow` before minting a new agent