Agent Creator

This skill creates Claude Code subagent definitions — the YAML+Markdown files that live in .claude/agents/ (project scope) or ~/.claude/agents/ (user scope), and that Claude Code's main thread delegates tasks to based on their descriptions.

A good subagent is deceptively hard to write. Most of the quality comes down to two things:

1. The description field. This is the only signal the main Claude thread uses to decide whether to delegate. If it's vague, the agent either never triggers or triggers on the wrong things.
2. The system prompt body. It has to give the subagent a clear role, workflow, and output format without turning into a wall of MUSTs.

Your job is to interview the user enough to understand what the agent should do, make opinionated choices for them where you can, write a definition that actually triggers when it should, and save it to the right place on disk.

When to use this skill

Any request that implies creating, editing, or understanding a subagent definition. For example:

• "Create a subagent that runs my test suite and reports failures"
• "I want an agent to review my migrations before I apply them"
• "Turn the code-review workflow we've been doing into an agent"
• "Make a read-only explorer for the frontend codebase"
• "What should I put in the description of this agent?" — offer to review.

If the user is asking about Claude Code subagents conceptually (how they work, when to use them, what they're for) rather than asking to build one, just answer the question — you don't need to produce a file.

The shape of a subagent file

---
name: <kebab-case-identifier>        # required
description: <when to delegate>      # required — the triggering signal
tools: <comma-separated list>        # optional — inherits all if omitted
model: <sonnet|haiku|opus|inherit>   # optional — defaults to inherit
---

<System prompt in Markdown.>
<Describes the subagent's role, workflow, and output format.>

Only name and description are required. Every other field has a sensible default. Don't add a field unless it's pulling its weight — don't set model: inherit explicitly, don't list every tool if inheriting is fine, don't set permissionMode: default.

The full field reference lives in references/frontmatter-reference.md. Read it when you need a field not covered in this file (hooks, memory, isolation, worktrees, permission modes, MCP scoping, skills preloading).

Five complete example agents (researcher, reviewer, debugger, DB query validator with hooks, specialist with preloaded skills) live in references/examples.md. Consult when you want a concrete reference for a shape you're drafting.

The workflow

1. Understand what the agent should do

The user usually tells you in one line: "an agent that does X". That's a starting point, not a spec. Before writing anything, you want clear answers to these, inferred from context or asked:

• What task does it handle? One concrete job, stated as a verb phrase. "Reviews PRs for security issues" — good. "Helps with code" — not.
• When should Claude delegate to it? What phrases from the user, or what conditions, should trigger it? This is raw material for the description field.
• Read-only or can it modify things? Drives tool selection.
• Should delegation be proactive or only when asked? Affects the description wording.
• Project or user scope? Where on disk it goes, and whether it's committed to version control.

If the user gave enough detail upfront, skip straight to drafting. If they gave a one-liner, ask 2–3 targeted questions — don't interrogate. Good question shapes: "Should this be able to edit files, or read-only?", "Do you want it to run automatically after code changes, or only when you explicitly @-mention it?", "Project-scoped (checked into this repo) or available across all your projects?".

If the skill was invoked because the user said "turn this into an agent" about a workflow already in the conversation, mine the conversation for answers before asking anything — what tools got used, what output shape the user expected, what corrections they made along the way. Confirm your inferences briefly, then draft.

2. Choose the scope

• Project — .claude/agents/<name>.md. The agent is specific to this codebase. Check it into version control so the team gets it too. This is the right default when the user is working in a specific repo.
• User — ~/.claude/agents/<name>.md. Personal, cross-project. Good for things like "explain this stack trace" or "draft a commit message" that aren't tied to one codebase.

Default to project unless the user said something that implies user scope ("I want this available everywhere", "add this to my personal agents", or the task is obviously generic).

3. Write the name

Lowercase, hyphenated, 2–4 words. It should be a thing, not a sentence: pr-reviewer, test-runner, migration-guardian. Avoid generic suffixes like -agent or -bot — the whole file is an agent, the suffix is noise. Make it specific enough that a teammate seeing it in .claude/agents/ can guess what it does.

4. Write the description — this is the most important field

Claude Code's main thread reads the description to decide whether to delegate. If the description doesn't clearly say when to use this agent, auto-delegation won't happen. Include three things:

1. What the agent does, in action-oriented language.
2. When to use it — the specific situations that should trigger it.
3. Whether delegation should be proactive. If you want Claude to delegate automatically without being asked, include the phrase "use proactively" or equivalent. If the agent should only run when explicitly invoked, leave that out.

Good descriptions — narrow, action-oriented, specific:

Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.

Runs the test suite and reports only failing tests with their error messages. Use after implementing a feature, after refactoring, or whenever the user asks whether anything broke.

Database migration reviewer. Reads proposed SQL migrations, checks for unsafe operations (table locks, missing indexes, destructive changes without backups), and blocks risky migrations. Use proactively before applying any migration.

Bad descriptions:

• "Helps with testing." — vague, no trigger conditions.
• "A code reviewer agent." — just restates the name.
• "Does code review and also runs tests and can deploy to staging." — too many jobs, unclear when to use.

If the user hasn't told you whether delegation should be proactive, infer from the task. Safety-critical things (migration review, test runs before deploys, security scans) usually want "use proactively". Flow-interrupting things (style nitpicks, refactoring suggestions) usually don't. When uncertain, ask.

5. Choose tools

Omit tools entirely to inherit everything from the main conversation. Specify tools only when you want to restrict. Two common patterns:

• Read-only researcher — tools: Read, Grep, Glob, Bash (add WebFetch, WebSearch if it needs external docs)
• Read + edit worker — tools: Read, Edit, Write, Bash, Grep, Glob

If the agent needs MCP tools, inheriting is simplest — the main conversation's MCP servers come along. Use mcpServers only when you want to give the agent access to an MCP server not in the parent session, or scope one exclusively to the subagent. See the reference file for syntax.

disallowedTools is the denylist alternative. Use when you want to inherit everything except a few tools:

disallowedTools: Write, Edit

When in doubt, restrict more rather than less. Tight tool scoping is one of the main reasons to use a subagent in the first place — it makes the agent cheaper to trust and easier to debug.

6. Choose the model

• Omit (defaults to inherit) — the subagent uses the same model as the main conversation. Right for most cases.
• haiku — fast and cheap. Good for read-only exploration, simple transformations, high-volume tasks (grepping many files, summarizing logs).
• sonnet — balanced. Reasonable default if you want to pin a model.
• opus — complex reasoning, architecture decisions, tricky debugging.

Pin a model only when you have a reason. "Inherit" means the user's session choice flows through, which is usually what they want.

7. Write the system prompt body

This is the Markdown under the frontmatter. It's the subagent's entire system prompt — it does NOT inherit Claude Code's default system prompt, just this plus basic environment info (working directory, etc.).

A good system prompt has four parts:

1. Role statement — one or two sentences. Sets identity and standards.

You are a senior code reviewer ensuring high standards of code quality and security.

2. Workflow — numbered list, 3–6 steps. The sequence the subagent follows when invoked. Steps should be concrete actions.

When invoked:
1. Run `git diff` to see recent changes
2. Focus on modified files
3. Begin review immediately

3. Checklist or criteria — bullet list. What to look for, what counts as done. This is where most of the domain knowledge lives.

4. Output format — explicit. How to structure the final response. "Organize feedback by priority: critical / warnings / suggestions" is good. Leaving it implicit tends to produce rambling.

Things to avoid in system prompts:

• Walls of MUSTs and NEVERs. Explain why instead — today's models have good theory of mind and respond better to reasoning than to heavy-handed rules. Reserve all-caps mandates for rare, genuinely critical constraints.
• Restating the description. The description is written for the parent Claude (deciding whether to delegate); the body is written for the subagent itself (doing the work). Don't repeat yourself.
• Over-specifying tone. Unless tone genuinely matters, let the model pick.
• Covering every edge case. Handle the 80% case cleanly and trust the model on the rest. A system prompt that tries to anticipate every situation becomes noisy and easy to ignore.

8. Show the draft to the user

Before writing anything to disk, show the user the complete file — frontmatter and body — and ask if they want to adjust. People often have opinions about description wording or want to tighten the tool list once they see it written out.

9. Save the file

Write to the appropriate path based on scope:

• Project: .claude/agents/<name>.md
• User: ~/.claude/agents/<name>.md (expand ~ to the user's home dir)

Create the directory if it doesn't exist:

mkdir -p .claude/agents

After saving, tell the user:

• The full file path.

• That they need to run /agents in Claude Code (or restart the session) to load the new agent.

• One line showing how to invoke it — a natural-language example and the @-mention form. For example:

  Try it: "Use the pr-reviewer agent on my last commit" — or @-mention @pr-reviewer (agent) in your next message.

Common patterns

A few shapes that come up repeatedly. Use them as starting points, not templates to copy blindly. Five complete worked examples live in references/examples.md.

Read-only researcher

For anything that explores a codebase or external docs without changing anything. Examples: understanding how a feature works, finding all callers of a function, summarizing a large log file.

tools: Read, Grep, Glob, Bash
model: haiku   # optional — speeds up exploration

System prompt: emphasize returning only the summary the main conversation needs, not dumping everything found.

Reviewer (read-only with structured output)

PR reviewers, security scanners, style checkers. Read-only with a specific output format that makes findings actionable.

tools: Read, Grep, Glob, Bash

System prompt: numbered review checklist, output organized by priority (critical / warning / suggestion), with concrete fix suggestions.

Worker (read + edit with verification)

Implementers, refactorers, debuggers — agents that modify code. These should always end with a verification step (run tests, re-read the file, run the linter) so they don't return "done" when they aren't.

tools: Read, Edit, Write, Bash, Grep, Glob

System prompt: diagnose → minimal fix → verify → summarize what changed.

Specialist for an external tool

DB query runners, browser automators, API clients. Usually need a specific MCP server or CLI tool. Restrict tools tightly and, if the tool is destructive (e.g., SQL), consider a PreToolUse hook that validates the action. Hook syntax is in the reference file.

Diagnosing bad drafts

If the draft feels off, common fixes:

• Description feels generic → add specific trigger phrases or situations. "Use when the user asks to deploy, or after merging to main" is far sharper than "Use for deployment tasks."
• System prompt feels long → workflow and criteria are probably tangled together. Separate them: numbered steps for workflow, bullets for criteria.
• Not sure if delegation will fire → read the description out loud from the main Claude's perspective. Does it clearly say when to delegate? If not, rewrite.
• Over-restricting tools → try inheriting (omit tools entirely) and see if the agent still behaves. Many agents don't need tool restrictions at all.
• Agent keeps doing too much → the description is probably listing multiple jobs. Split into two agents, or narrow the description.

Things worth proactively flagging

While drafting, mention these to the user if relevant — they're easy to miss:

• Version control. If saving to .claude/agents/, ask whether they want to commit it. Team-shared agents live in git.
• memory field. If the agent does work that benefits from accumulated learning across sessions (style conventions, codebase patterns, recurring bug types), mention memory: project or memory: user as an option. Don't enable it unprompted, but offer it. Details in the reference file.
• Overlap with existing agents. If .claude/agents/ already has an agent covering similar ground, point it out and ask whether to extend the existing one or add a new one.
• Subagents can't spawn subagents. If the user is describing an agent that needs to delegate further work, surface this limitation — they may need to chain from the main thread instead, or use agent teams / Skills.

Reference files

• references/frontmatter-reference.md — every supported frontmatter field with its semantics and a short example. Read when you need a field not covered here (hooks, memory, isolation/worktrees, permissionMode, mcpServers, skills preloading, effort, color, initialPrompt, background, maxTurns, disallowedTools).
• references/examples.md — five complete, diverse subagent definitions as reference material. Read when you want to see full examples or are unsure of the shape for a particular use case.