agent-creator

# Agent Creator $ARGUMENTS 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