ad-subagent

# /ad-subagent Drafts `.claude/agents/<name>.md` (project) or `~/.claude/agents/<name>.md` (personal). Spec: [code.claude.com/docs/en/sub-agents](https://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 <role> that <does X> when <triggered by Y>." * **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 If the target file already exists, show it and overwrite it only after the user approves; a personal-scope file lives outside the repository, so git cannot restore it. 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.