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 4.8. Same patterns work for Sonnet 5 and Haiku 4.5 at lower effort.

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 4.8 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/.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) > /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 :.
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). Subagents cannot spawn other subagents (the Agent tool is unavailable in subagent contexts).
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/.md` (commit to share with team)
├── Personal cross-project → `~/.claude/agents/.md`
├── Plugin-distributed → `/agents/.md` (auto-namespaced `:`)
├── 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.

| Field | Required? | When to set | |-------|-----------|-------------| | name | yes | always; lowercase letters and hyphens, unique within scope | | description | yes | always; this is the trigger surface the orchestrator reads to decide delegation | | tools | optional | the agent should use only a specific subset of tools (allowlist). Omit to inherit every tool. Comma-separated string or YAML list. | | disallowedTools | optional | the agent should inherit most tools but be denied a few (denylist). Applied first, then tools filters the remainder. | | model | optional | the agent needs a specific model (sonnet/opus/haiku, full ID like claude-opus-4-8, or inherit). Default: inherit. | | effort | optional | the agent needs a different reasoning budget than the session (low/medium/high/xhigh/max). | | permissionMode | optional, NON-PLUGIN ONLY | the agent should run with a specific permission mode (default/acceptEdits/auto/dontAsk/bypassPermissions/plan). Ignored in plugin agents. | | maxTurns | optional | the agent should stop after N agentic turns. Positive integer. | | skills | optional | named skills to preload into the agent's context at startup (full content injected, not just made available). | | mcpServers | optional, NON-PLUGIN ONLY | MCP servers scoped to this agent. Inline definitions or names of already-configured servers. Ignored in plugin agents. | | hooks | optional, NON-PLUGIN ONLY | lifecycle hooks scoped to the agent. Same shape as project hooks. Ignored in plugin agents. | | memory | optional | persistent memory scope (user/project/local). Creates a directory the agent reads and updates across runs. Auto-injects Read/Write/Edit tools. | | background | optional | true to always spawn this agent in the background by default. | | isolation | optional | worktree to spawn the agent in a temporary git worktree, isolated from the main checkout. | | color | optional | display color in the task list (red/blue/green/yellow/purple/orange/pink/cyan). | | initialPrompt | optional, MAIN-AGENT MODE | first user turn auto-prepended when this agent runs as the main session via --agent. | | requiredMcpServers | optional | array of MCP server name patterns that must be configured for the agent to appear in the listing. Per loadAgentsDir.ts:233-242, agents missing required servers are filtered out (case-insensitive substring match). |

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. Subagents cannot spawn other subagents (the Agent tool is unavailable in subagent contexts), so this matters only for agents that run as the main thread via claude --agent :

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-4-8, inherit
effort: high       # or low, medium, xhigh, max

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

Picking:

• Haiku: fast, cheap, low-effort. Right for read-only search agents, classification, lookup. Built-in Explore uses Haiku (external builds).
• 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.

| Mode | Behavior | |------|----------| | default | Standard prompts for new permissions | | acceptEdits | Auto-accept file edits and common filesystem commands in working dirs | | auto | Background classifier reviews each command | | dontAsk | Auto-deny new prompts; only pre-approved tools work | | bypassPermissions | Skip prompts entirely; CC still protects .git, .claude, .vscode, .idea, .husky | | plan | Read-only exploration mode |

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//
• project -> .claude/agent-memory// (commit to share)
• local -> .claude/agent-memory-local// (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: ." The agent self-checks against these before returning.

## Constraints

H

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [anilcancakir](https://github.com/anilcancakir)
- **Source:** [anilcancakir/claude-code](https://github.com/anilcancakir/claude-code)
- **License:** MIT

Install and usage instructions live in the source repository linked above.