| name | ad-subagent |
| description | Draft a new Claude Code subagent at .claude/agents/<name>.md, using the official subagents format. Use when the user wants to create, write, draft, or scaffold a custom Claude Code subagent for delegated work (fresh-context reviewer, codebase researcher, docs researcher, test designer, bug reproducer, bounded implementation worker). Asks one question per missing field; never invents roles or tool sets. |
| summary | Draft a host-specific custom subagent for bounded delegated work — Claude Code `.claude/agents/<name>.md`, Codex `.codex/agents/<name>.toml`. |
| allowed-tools | Read, Write, Glob, Bash |
/ad-subagent
Drafts .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (personal). Spec: code.claude.com/docs/en/sub-agents.
The body becomes the subagent's role prompt. A named subagent starts with fresh conversation context and its own tools/model settings; do not rely on parent-session memory. Restate task-specific constraints and cite any project files it must follow.
Step 1 — Confirm target
Ask the user:
- Name — kebab-case, lowercase. Becomes the file name and the routing handle (
subagent_type: '<name>').
- Personal or project —
~/.claude/agents/<name>.md (personal) vs .claude/agents/<name>.md (project, committed). Default: project.
Step 2 — Pick a pattern (or build custom)
Common pre-baked shapes:
| Pattern | Tools | Model | Notes |
|---|
| Fresh-context reviewer | Read, Glob, Grep, Bash | sonnet | Matches WORKFLOW §10. No write tools. |
| Codebase researcher | use built-in Explore | inherit | Don't build custom unless you need different tools. |
| Diff-only auditor | Read, Bash | sonnet | Pair with permissionMode: dontAsk for read-only runs. |
| Docs researcher | Read, WebFetch or docs MCP | inherit | Confirms versioned APIs; returns citations only. |
| Test designer | Read, Glob, Grep | inherit | Proposes public-interface tests from spec/task; no production edits. |
| Bug reproducer | Read, Bash, Write | inherit | Builds the smallest failing loop, then stops before broad fixes. |
| Bounded worker | scoped write tools | inherit | Owns a disjoint file/module set; returns changed paths + verification. |
Built-in subagents (Explore, Plan, general-purpose) cover most cases. Build custom only when you need a specific role, scoped tools, persistent memory, or a different model.
Delegation-fit gate: build a custom subagent only when the role repeats, the work is self-contained, the output can be summarized or bounded to a disjoint patch, or the role needs tool/model/sandbox restrictions. Keep frequent back-and-forth, tightly coupled implementation, and the immediate blocking step in the main conversation.
Step 3 — Interview to fill
Ask one question per missing field, in this order:
- Role — one sentence: "You are a that when ."
- Description — the routing signal. Specific, includes the task framings the parent agent would recognize. Claude reads this to decide whether to delegate.
- Tools — comma-separated list. Limit deliberately. A reviewer with
Write access stops being a reviewer. Omit to inherit all parent tools.
- Model —
sonnet | opus | haiku | inherit. Default: inherit.
- Output contract — what the subagent returns to the caller. Be explicit about format.
- Stop criterion — when the subagent should stop and return control.
Do not invent values. When the user does not know something, ask. Do not invent frontmatter fields not in the spec.
Step 4 — Write the file
Path: .claude/agents/<name>.md (project, committed) or ~/.claude/agents/<name>.md (personal). Frontmatter uses the Claude Code subagents shape (see code.claude.com/docs/en/sub-agents) — declare only the fields the subagent actually uses.
Body = the role prompt. Every line costs tokens on every subagent turn. Be terse. State role, scope, output format, stop criterion, and what NOT to do. Restate task-specific constraints and point to project files for load-bearing conventions.
Edits to subagent files on disk require a session restart to take effect; agents created via Claude Code's /agents UI take effect immediately.
Step 5 — Stop after writing
Do not dispatch to the new subagent, do not test it. The user will exercise it themselves.
Output contract
A single new file at .claude/agents/<name>.md (or ~/.claude/agents/<name>.md). Frontmatter declares only the fields actually used. Body is the system prompt: terse, imperative, with explicit stop criterion. No external file dependencies the user did not ask for.
Next
- Test the new subagent by exercising the workflow it serves — invoke via the
Task tool with subagent_type: '<name>'.
- Document the subagent in
AGENTS.md (or the project's operational guide) if it is project-wide rather than personal.
- If the subagent ships alongside a skill (manifest-listed), update the skill's
manifest.json to declare the file.
