Agent Creator

Agent Creator

You are about to write or edit a Claude Code custom subagent another Claude will delegate to. An agent is a markdown file that becomes a named worker the orchestrator can spawn with the Agent tool: the parent fills in subagent_type, prompt, and optional description, name, run_in_background, isolation; Claude Code spawns a fresh isolated context, injects the agent's body as the system prompt, and runs the agent until completion. The agent returns its final message to the parent as the tool result.

This skill is the playbook for designing tool restrictions, choosing model and effort, picking permissionMode, adding memory, preloading skills, structuring the system-prompt body, and routing the storage choice. Target is Opus 5. Same patterns work for Sonnet 5 at lower cost and for Haiku 4.5, which supports no effort parameter.

Three jobs, not one

Writing a custom subagent splits into three tasks. Conflating them is the most common authoring mistake.

1. Surrounding skill shape. File location, scope, naming, frontmatter parsing. Same rules as any markdown config. Route through ac:skill-creator for the broader file-shape decisions (scope, name validation, char budget).
2. Agent-specific shape. Tool allowlist/denylist, model and effort, permissionMode, memory, skills: preload, isolation, background. This file teaches that.
3. System-prompt body content. The markdown the orchestrator injects as the agent's system. This is a prompt. Route through ac:prompt-writer (architecture, snippets, anti-patterns, Opus 5 tuning) for the body, and apply the five-section pattern from ${CLAUDE_SKILL_DIR}/references/system-prompt-structure.md for the shape.

A great agent body inside the wrong shape (wrong tools, wrong model, wrong permission mode) returns useless work. A modest body inside the right shape returns sharp results every time.

What an agent actually is, mechanically

Source of truth: tools/AgentTool/loadAgentsDir.ts, tools/AgentTool/builtInAgents.ts, tools/AgentTool/built-in/<name>.ts, utils/plugins/loadPluginAgents.ts, tools/AgentTool/prompt.ts in the CC source.

The lifecycle:

1. Discovery. At session start, the loader walks managed > --agents CLI flag > .claude/agents/ (project, walks up from cwd) > ~/.claude/agents/ (user) > <plugin>/agents/ > built-in. Higher-priority definitions override lower ones with the same name (tools/AgentTool/loadAgentsDir.ts:200-220, agents in later groups overwrite earlier in the map). Directories added with --add-dir are NOT scanned for agents; only file access is granted there. To share an agent across projects, use ~/.claude/agents/ or ship it via a plugin. SDK callers can disable all built-ins by setting CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 in non-interactive mode.
2. Parsing. Each file's YAML frontmatter is parsed; the markdown body becomes the agent's system prompt. Plugin agents auto-namespace as <plugin>:<agent-name>.
3. Listing. Built-in plus active custom agents are summarized in the orchestrator's Agent tool description: - {agentType}: {whenToUse} (Tools: {toolsDescription}). The orchestrator decides delegation based on these lines.
4. Spawn. Orchestrator calls Agent({subagent_type, prompt, ...}). Claude Code creates a fresh isolated context, applies the agent's tool restrictions, model, effort, permission mode, hooks, and any preloaded skills.
5. Substitution (plugin agents only). ${CLAUDE_PLUGIN_ROOT} and ${user_config.X} are substituted in the system prompt for plugin agents. Non-plugin agents get no substitution; the body is injected verbatim.
6. Execution. The agent runs as its own LLM loop. It receives the agent's body as system, the parent's prompt as the first user turn. CLAUDE.md is auto-loaded into its context unless the agent definition sets the internal omitClaudeMd flag (built-in only; saves token cost on read-only built-ins like Explore and Plan that do not need commit/PR/lint guidelines; kill-switch GrowthBook flag tengu_slim_subagent_claudemd). A subagent CAN spawn other subagents when Agent is in its tool set, which it is whenever the definition uses a disallowedTools denylist rather than a tools: allowlist. Decide that per agent; references/tool-restrictions.md carries the measurement and the two ways to deny it.
7. Return. The agent's final assistant message returns to the parent as the Agent tool result. Intermediate tool calls and reasoning stay in the agent's context, not the parent's.

The parent never sees the agent's tool calls or scratch work; only the final summary. This is the central value: context isolation.

Decision flow

Route by the user's request.

Is a custom subagent the right tool at all?
├── Built-in (Explore / Plan / general-purpose) already fits → use it. Not a custom agent.
├── Repeatable workflow, no isolation needed → SKILL (route through `ac:skill-creator`).
├── User-typed `/name [args]` action → COMMAND (route through `ac:command-creator`).
├── Always-on enforcement → HOOK (route through `update-config`).
├── Single fact, not behavior → CLAUDE.md (route through `ac:claude-md-rules-creator`).
└── Recurring task that benefits from isolated context, custom tools, or distinct model → AGENT, continue.

Where does the agent live?
├── Project-scoped → `.claude/agents/<name>.md` (commit to share with team)
├── Personal cross-project → `~/.claude/agents/<name>.md`
├── Plugin-distributed → `<plugin>/agents/<name>.md` (auto-namespaced `<plugin>:<name>`)
├── Org-wide enforced → managed dir
└── One-off (no persistence) → `--agents` JSON flag

Is this an audit or fix of an existing agent?
├── YES → `${CLAUDE_SKILL_DIR}/references/anti-patterns.md` first, then specific reference as needed.
└── NO  → walk the Workflow below.

For everything outside agent-specific concerns (file naming, char budget, generic frontmatter parsing), defer to ac:skill-creator rather than duplicating that material here.

Frontmatter: minimal by default

A working agent needs only name + description. Everything else is opt-in.

Escape convention used in this documentation. This SKILL.md is itself a skill body inside a plugin. The Claude Code loader substitutes the plugin-root token, the skill-directory token, the session-id token, and the full-arguments token on every invocation. To document those tokens without corrupting the docs, this file uses the HTML entity $ standing in for the dollar sign whenever a token name is being NAMED rather than USED. Real path references (the skill-directory token followed by a slash and a relative path) stay literal so the loader resolves them to actual files the model can Read. In your own agent body, agents do NOT support full-arguments substitution or shell injection (only the plugin-context tokens). For plugin agents, write a plain dollar sign for ${CLAUDE_PLUGIN_ROOT} and ${user_config.X}. Non-plugin agents get no substitution at all; every token stays literal.

Anti-pattern: copying every optional field "just in case". Each unused field adds noise. A focused research agent usually needs just name + description + tools + model. A reviewer that updates a knowledge base adds memory:. Reach further only for specific needs.

Plugin-agent security boundary: per utils/plugins/loadPluginAgents.ts:161-168, plugin agents silently ignore permissionMode, hooks, and mcpServers. If your agent needs those, ship it as a user/project agent under .claude/agents/, not via a plugin. Plugins are third-party marketplace code; install-time trust boundaries cover plugin-level hooks/MCP, but per-agent escalation through a buried agent file is not allowed.

Tool access

Three patterns cover almost every case. Detail and copy-paste templates: ${CLAUDE_SKILL_DIR}/references/tool-restrictions.md.

Allowlist (most restrictive, recommended for focused agents)

tools: Read, Grep, Glob, Bash

Agent can only use the listed tools. Default for read-only research agents.

Denylist (start broad, subtract dangerous tools)

disallowedTools: Write, Edit, NotebookEdit

Agent inherits every tool the parent has, minus the denied set. Useful for "do anything except touch files".

Both (rare, when you need allowlist plus exclusions)

When both are set, disallowedTools is applied first to the inherited pool, then tools filters that pool. Tools listed in both are removed.

Restricting subagent spawning

The Agent tool is itself a tool, and it reaches subagents too: an agent declaring only a disallowedTools denylist inherits Agent and will spawn children on an Opus-tier model. So this matters for main-thread agents run via claude --agent <name> AND for every subagent you write. See references/tool-restrictions.md for the measurement:

tools: Agent(worker, researcher), Read, Bash

Agent(x, y) is an allowlist: only worker and researcher types can be spawned. To allow any: Agent without parentheses. To block all spawning: omit Agent from tools.

Model and effort

model: sonnet      # or opus, haiku, claude-opus-5, inherit
effort: high       # or low, medium, xhigh, max

Defaults: model: inherit (same as parent), no effort override.

Picking:

• Haiku: fast and cheap. Right for read-only search agents, classification, lookup. Built-in Explore uses Haiku (external builds). Note it supports no effort value, so do not pair model: haiku with effort:.
• Sonnet: balanced. Right for code review, analysis, anything intelligence-sensitive but bounded.
• Opus: deep reasoning. Right for architecture review, multi-file refactors, adversarial review (challenger pattern).
• Inherit: when the agent's quality should track the session's model choice.

Set effort: high only for agents that do deep work in one shot (a plan-deep-review agent, a feasibility analyst). Most agents inherit fine.

Permission mode

Non-plugin agents can set permissionMode. Plugin agents ignore the field.

Parent precedence rule: if the parent session uses bypassPermissions or acceptEdits, that takes precedence and the agent cannot downgrade. If the parent uses auto, the agent's permissionMode is ignored entirely and the classifier evaluates the agent's calls.

For most agents, leave permissionMode unset and rely on tools/disallowedTools to constrain capability. Reach for permission mode only when the agent should run with looser-than-default automation (acceptEdits for an autonomous-edit agent the user trusted at install time, dontAsk for a strict read-only researcher).

Memory, skills preload, isolation

Detail: ${CLAUDE_SKILL_DIR}/references/memory-and-skills.md.

Persistent memory

memory: project    # or user, local

Creates a directory the agent reads at startup and writes to during work:

• user -> ~/.claude/agent-memory/<name>/
• project -> .claude/agent-memory/<name>/ (commit to share)
• local -> .claude/agent-memory-local/<name>/ (gitignored by default)

When memory is enabled:

• Read, Write, Edit are auto-injected into the agent's tool list if those were missing.
• The first 200 lines (or 25KB) of MEMORY.md in the memory directory is added to the agent's system prompt.
• The body should include explicit instructions to update memory ("save what you learned to your memory after the task").

Memory makes the agent stateful across runs. Use for code-reviewers, debuggers, domain analysts that benefit from accumulated knowledge.

Skill preloading

skills:
  - api-conventions
  - error-handling-patterns

The full content of each named skill is injected into the agent's system context at startup. The agent gets the skill's body, not just the option to invoke it. Subagents do NOT inherit skills from the parent conversation; you must list every skill the agent needs.

Cannot preload skills with disable-model-invocation: true (security: those skills opted out of programmatic invocation).

Worktree isolation

isolation: worktree

Agent runs in a temporary git worktree, isolated from the main checkout. The worktree is auto-cleaned if the agent makes no changes; if it changes files, the worktree path and branch are returned in the tool result.

Use for agents that should not touch the main checkout, or for parallel agents that need separate working copies.

System-prompt body

The body is the agent's system prompt. Treat it like any other system prompt and route through ac:prompt-writer for principles.

Skill-creator's standing body conventions all apply: persona at the top, static rules before dynamic, XML tags when needed, no aggressive caps (state the rule plain and explain the why), positive instructions over negative-only.

The single most useful agent-body convention is the five-section format (extracted from the prior ac MVP's 15 agents, applies to almost every focused agent):

## Identity

One or two sentences describing who the agent is and what it returns. Anchors the lens.

## Execution

Numbered steps the agent follows. Reads first, then acts. Sub-numbers for parallel steps.

## Output Format

Exact markdown shape the agent returns. Locked headers, citation format, length cap. The orchestrator parses this; commit to one shape.

## Failure Conditions

What makes the response BAD. "FAILED if: <list of quality-gate violations>." The agent self-checks against these before returning.

## Constraints

Hard rules. Scope limits. Tool restrictions explicit again ("Read-only, no Write or Edit"). Evidence requirements.

Detail and three worked structures (read-only researcher, code reviewer, action-taking debugger): ${CLAUDE_SKILL_DIR}/references/system-prompt-structure.md.

Plugin paths and substitutions

Plugin agents get one substitution pass before the system prompt is injected (utils/plugins/loadPluginAgents.ts:113-123):

• ${CLAUDE_PLUGIN_ROOT} resolves to the plugin's root directory. Use this when a plugin agent needs to reference bundled files: Read ${CLAUDE_PLUGIN_ROOT}/templates/foo.md.
• ${user_config.X} resolves to the value of the X key in the plugin's userConfig (sensitive keys resolve to a placeholder).

Non-plugin agents (.claude/agents/, ~/.claude/agents/) get NO substitution. Tokens stay literal in the system prompt.

Agents do NOT support $ARGUMENTS or ${CLAUDE_SKILL_DIR} (those are skill and command tokens). Agents also do NOT support shell injection (\!`<cmd>`); the agent system prompt is injected verbatim after the plugin substitution pass.

Workflow

Walk these in order. Each step assumes the previous resolved.

1. Capture intent

Always-needed questions:

• What does the agent do, in one sentence?
• Is it read-only or does it modify files?
• What model and effort fit?
• Project, user, or plugin scope?

Conditional questions (ask only when intent surfaces a need):

• Tool restrictions? Ask if the agent should be constrained (read-only researcher, no-network, no-MCP).
• Memory? Ask if the agent benefits from accumulated knowledge across runs.
• Preloaded skills? Ask if there are domain-specific skill bodies the agent should start with.
• Permission mode? Ask only if the parent's default mode is wrong for this agent's role.
• Worktree isolation? Ask if the agent should not touch the main checkout.

Do not pre-ask about every optional field; pull each in only when intent makes it relevant.

2. Pick scope

.claude/agents/ for team-shared agents in a repo. ~/.claude/agents/ for cross-project personal agents. <plugin>/agents/ for distribution. --agents JSON flag for one-off testing.

3. Draft the frontmatter

Minimal:

---
name: <kebab-case-name>
description: <Third-person summary, when to use. Trigger phrases. Concrete contexts.>
---

Add fields only when the conditional questions surfaced a reason. The "Frontmatter: minimal by default" table above lists each field with its trigger condition.

description is the trigger surface; the orchestrator decides whether to delegate based on this line alone. Front-load the verb and noun, use third person, include "use proactively" if you want aggressive delegation. Cover synonyms and adjacent contexts.

4. Write the body

Five-section pattern (above) unless the agent is genuinely trivial. For each section, name the success criterion: how does the agent know it has fulfilled this section? The Output Format section is locked; the orchestrator parses the agent's response and downstream work fails if shape drifts.

Hand off the prompt-writing details to /ac:prompt-writer after picking the shape.

5. Verify

Before shipping:

1. Frontmatter parses. name is lowercase + hyphens, description is a string, tools/disallowedTools use the right format.
2. Triggering reads cleanly. Read description aloud. Would the orchestrator know when to delegate to this agent based on this line?
3. Tool restrictions match the body. If the body says "Read-only research", tools is an allowlist excluding Write/Edit. If the body uses Bash for git status, Bash is in tools.
4. Output Format is parseable. The shape the agent returns is consistent enough that the parent can act on it without follow-up questions.
5. Test invocation. Have the orchestrator delegate to the agent in a fresh session with a typical request. Does the agent return the expected shape?

Worked examples that pass all gates: ${CLAUDE_SKILL_DIR}/references/examples.md.

6. Iterate

Deeper symptom-to-fix mapping: ${CLAUDE_SKILL_DIR}/references/anti-patterns.md.

Sibling skills (route the surrounding shape)

When the user request implies any of the rows above, do both: invoke the matching creator for shape, and keep this skill loaded for what is still agent-shaped.

Built-in agents to know

Read ${CLAUDE_SKILL_DIR}/references/builtin-catalog.md for full details. Quick reference:

• Explore (Haiku, read-only), file search and codebase analysis. Built-in tools-restriction pattern to copy.
• Plan (inherit, read-only), software architect for implementation plans. Plan-mode delegation target.
• general-purpose (inherit, all tools), multi-step research and modification. Default for fork mode.
• claude-code-guide (Haiku, web-fetch + read), answers user questions about CC, Agent SDK, and Claude API.
• statusline-setup (Sonnet), configures status line.
• verification (feature-flagged), runtime observation pattern.

When designing a custom agent, check whether a built-in already fits. If yes, use it.

Quick template

Full annotated blank template: ${CLAUDE_SKILL_DIR}/assets/AGENT.template.md.

Minimal form (covers most agents):

---
name: <kebab-case-name>
description: <Third-person summary, when to use. Include trigger phrases. Use proactively if desired.>
model: <sonnet | haiku | opus | inherit>
---

## Identity
<One or two sentences: who the agent is and what it returns.>

## Execution
1. <Step 1: read first>
2. <Step 2: act precisely>
3. <Step 3: verify>

## Output Format
<Locked markdown shape with citations / verdict / length cap.>

## Failure Conditions
FAILED if: <list of quality-gate violations the agent self-checks against>.

## Constraints
<Hard rules. Scope limits. Evidence requirements.>

Pre-flight checklist

Always check:

• File at the right scope (managed / project / user / plugin).
• Filename = agent name (lowercase, hyphens, max 64 characters, no claude or anthropic).
• Frontmatter has name and description. Other fields only when the agent needs them.
• description is third-person, names trigger conditions, covers synonyms.
• No cargo-culted optional fields (each present field has a specific reason).

Check only the items that apply to the agent's specific shape:

• (If tools: is set) it lists the tools the body actually uses (allowlist).
• (If disallowedTools: is set) it lists the tools the body avoids (denylist).
• (If model: is set) the choice matches the agent's complexity tier.
• (If memory: is set) the body includes instructions to update memory after the task.
• (If skills: is set) all listed skills exist and have disable-model-invocation: false.
• (If permissionMode: is set) the agent is NOT a plugin agent (plugins ignore it).
• (If hooks: or mcpServers: is set) the agent is NOT a plugin agent.
• (If isolation: worktree) the agent's work makes sense in an isolated checkout.
• Body uses the five-section pattern (Identity / Execution / Output Format / Failure Conditions / Constraints).
• Output Format is locked: the orchestrator can parse the agent's return without follow-up questions.
• Body passes the ac:prompt-writer audit: no aggressive caps unless safety-critical, positive instructions, explained why.
• Test invocation in a fresh session: orchestrator delegates correctly, agent returns the right shape.

References

For surrounding skill shape, invoke /ac:skill-creator. For the prompt body itself, invoke /ac:prompt-writer. Sibling-skill files cannot be read by path from here, since the install layout is unknown at author time; invocation is the portable form.

Canonical Anthropic documentation, served as raw markdown by appending .md to the URL:

• Subagents: https://code.claude.com/docs/en/sub-agents.md
• Skills (for the skills: preload field): https://code.claude.com/docs/en/skills.md
• Plugins (for plugin-agent restrictions and the plugin-root substitution): https://code.claude.com/docs/en/plugins.md
• Permission modes: https://code.claude.com/docs/en/permission-modes.md
• Hooks: https://code.claude.com/docs/en/hooks.md

When canonical docs conflict with observed CLI behavior, trust the live binary.