Agent creator

Agent Creator

<!-- canonical:writing-rules:start -->

Important — Writing rules

These rules govern every prose artifact this skill emits — READMEs, CHANGELOGs, commit messages, PR bodies, release notes, doc paragraphs, non-trivial comments. Apply them at draft time, verify before output.

• Match the surrounding style — punctuation, capitalization, backtick conventions, em-dash vs parens, bullet style.
• Every sentence changes the reader's understanding. Cut it otherwise.
• Front-load the verb — "Creates", not "This helps you create".
• Concrete over abstract. Lists for ≥3 enumerable items.
• Assert positively. Reserve negation for real constraints (NEVER commit secrets).
• No marketing words: powerful, robust, seamlessly, leverage, unlock, comprehensive, delightful.
• No AI tells: delve, tapestry, intricate, pivotal, testament, underscore, crucial, garner, showcase, additionally, moreover, furthermore, indeed.
• After drafting English prose, invoke /humanize-en if installed.

<!-- canonical:writing-rules:end -->

Subagents are specialized Claude instances that run in isolated contexts with focused roles and limited tool access. This skill covers how to create effective subagents, write strong system prompts, configure tool access, and orchestrate multi-agent workflows.

Subagents enable delegation of complex tasks to specialized agents that operate autonomously without user interaction, returning their final output to the main conversation.

Capture Intent

Before drafting an agent, surface the four contract questions. If the user's spec is vague, ask these via AskUserQuestion rather than fabricating answers:

1. What should this agent do? — the specific task and role (e.g., "review TypeScript PRs for security regressions"), not a generic description.
2. When should it be invoked? — trigger conditions, keywords, file patterns. Goes into the description field for routing.
3. Which tools does it need? — least-privilege allowlist. Read-only analysis vs write-capable.
4. What's the expected output format? — structured report, file edits, list of findings, etc.

The description field carries triggers; the system prompt body carries workflow + output format. Both are derived from these answers.

Quick Start

1. Run /agents command
2. Select "Create New Agent"
3. Choose project-level (.claude/agents/) or user-level (~/.claude/agents/)
4. Define the agent:
   • name: lowercase-with-hyphens
   • description: When should this agent be used?
   • tools: Optional comma-separated list (inherits all if omitted)
   • model: Optional (sonnet, opus, haiku, full model ID, or inherit)
5. Write the system prompt (the agent's instructions)

Example:

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes to review for quality, security, and best practices.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer focused on quality, security, and best practices.

## Focus Areas

- Code quality and maintainability
- Security vulnerabilities
- Performance issues
- Best practices adherence

## Output

Provide specific, actionable feedback with file:line references.

Scope and Priority

Priority	Location	Scope
1 (highest)	Managed settings	Organization-wide
2	--agents CLI flag	Current session
3	.claude/agents/	Current project (git-shared)
4	~/.claude/agents/	All your projects
5 (lowest)	Plugin's agents/ dir	Where plugin is enabled

When names conflict, higher priority wins. Project agents override user-level agents.

Configuration

All supported YAML frontmatter fields. Only name and description are required.

Field	Required	Description
name	Yes	Unique identifier, lowercase letters and hyphens
description	Yes	When Claude should delegate to this agent. Write clear trigger conditions
tools	No	Comma-separated allowlist. Inherits all tools if omitted
disallowedTools	No	Comma-separated denylist, removed from inherited tools
model	No	sonnet, opus, haiku, full model ID (e.g. claude-opus-4-8), or inherit. Defaults to inherit
permissionMode	No	default, acceptEdits, auto, dontAsk, bypassPermissions, or plan
maxTurns	No	Maximum agentic turns before auto-stop
skills	No	Skills to load into agent context at startup (full content injected)
mcpServers	No	MCP servers: string references or inline definitions
hooks	No	Lifecycle hooks scoped to this agent
memory	No	Persistent memory scope: user, project, or local
background	No	true to always run as background task. Default: false
effort	No	Effort level override: low, medium, high, max
isolation	No	worktree to run in a temporary git worktree
color	No	Display color: red, blue, green, yellow, purple, orange, pink, cyan
initialPrompt	No	Auto-submitted first user turn when agent runs as main session (via --agent)

Model resolution order: CLAUDE_CODE_SUBAGENT_MODEL env var > per-invocation model > frontmatter model > main conversation model.

Tool restriction patterns:

• tools: Read, Grep, Glob — read-only analysis
• disallowedTools: Write, Edit — inherit all except writes
• tools: Agent(worker, researcher), Read — restrict which subagents can be spawned (main thread only)
• If both set: disallowedTools applied first, then tools resolved against remainder

Plugin agents do not support hooks, mcpServers, or permissionMode (ignored for security).

Execution Model

Subagents are black boxes that cannot interact with users.

• Can use tools: Read, Write, Edit, Bash, Grep, Glob, MCP tools
• Cannot use AskUserQuestion or any interactive tool
• User never sees intermediate steps — only the final output

Subagents cannot spawn other subagents. Don't include Agent in a subagent's tools. This restriction only applies to subagents — main thread agents (via --agent) can spawn subagents.

System Prompt Guidelines

Write the system prompt as the markdown body after frontmatter. The agent receives only this prompt (plus environment details), not the full Claude Code system prompt.

• Be specific: Define exactly what the agent does. "You are a React performance optimizer specializing in hooks and memoization" not "You are a helpful coding assistant".
• Include a workflow: Step-by-step process for consistency.
• Set constraints: Use NEVER/MUST/ALWAYS for critical boundaries.
• Define output format: Specify expected deliverable structure.
• Structure is flexible: Use markdown headings, XML tags, or a combination — whatever is clearest. The official docs show agents with standard markdown headings.

Background Execution

Agents can run in the background using the run_in_background parameter on the Agent tool, enabling parallel execution while the main conversation continues.

Launching: Set run_in_background: true on the Agent tool call. Returns an agent_id.

Retrieving results: The main conversation is automatically notified when background agents complete.

Parallel pattern: Launch multiple independent agents in a single message, then collect results:

Agent 1: code-reviewer (background)
Agent 2: security-scanner (background)
Agent 3: test-analyzer (background)
-> All run in parallel
-> Results collected when each completes

Resuming: Use SendMessage with the agent's ID to resume with full context preserved.

When to use background:

• Long-running analysis (security audits, full-codebase reviews)
• Multiple independent tasks that can parallelize
• Research tasks that take significant time

When NOT to use:

• Quick operations (< 10 seconds)
• Sequential dependencies between tasks
• Tasks where immediate results are needed for next step

Management

• Recommended: /agents command for interactive management (view, create, edit, delete)
• CLI listing: claude agents to list all configured agents from the command line
• Manual editing: Edit files directly in .claude/agents/ or ~/.claude/agents/
• Session-only: Pass --agents '{...}' JSON for temporary agents that aren't saved to disk

Reference

Core references:

• Agent configuration and usage: references/subagents.md — file format, storage locations, tool security, model selection, orchestration strategies, background execution, complete examples
• Writing effective prompts: references/writing-subagent-prompts.md — specificity, clarity, constraints, description field optimization, anti-patterns, examples

Advanced topics:

• references/orchestration-patterns.md — sequential, parallel, hierarchical, coordinator patterns
• references/evaluation-and-testing.md — evaluation metrics, testing strategies
• references/error-handling-and-recovery.md — failure modes, recovery strategies
• references/context-management.md — memory architecture, context strategies
• references/debugging-agents.md — logging, tracing, diagnostic procedures

Gotchas

1. tools + disallowedTools resolution is counterintuitive when both are set. Per § Configuration, disallowedTools applies first, then tools resolves against the remainder. Setting tools: Read, Write + disallowedTools: Write yields an agent with only Read; Write is denied before the allowlist sees it. Fix: use one mechanism, not both; prefer the allowlist for fine-grained control.
2. Plugin-scoped agents silently ignore hooks, mcpServers, permissionMode. Per § Configuration, these fields are stripped from plugin agents for security; the agent loads without them and emits no warning. Fix: for plugin agents, move hook logic into the system prompt; for full configurability, use project-level .claude/agents/ instead of plugin distribution.
3. Subagents cannot spawn other subagents. Per § Execution Model, including Agent in a subagent's tools is rejected at runtime. Multi-agent fan-out must happen from the main thread (or a --agent-launched main agent), never from inside a subagent. Fix: flatten the workflow so the main thread orchestrates the parallel subagents directly.
4. Model selection precedence surprises across env-var + frontmatter + per-invocation. Per § Configuration, CLAUDE_CODE_SUBAGENT_MODEL env var > per-invocation model > frontmatter model > main conversation model. An ambient CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5-20251001 overrides a model: opus in frontmatter. Fix: explicitly set model in frontmatter to document the contract; verify against echo $CLAUDE_CODE_SUBAGENT_MODEL if behavior surprises.

Success Criteria

A well-configured agent has:

• Valid YAML frontmatter (name matches file, description includes triggers)
• Clear role definition in system prompt
• Appropriate tool restrictions (least privilege)
• Structured prompt with workflow and constraints
• Description field optimized for automatic routing
• Model selection appropriate for task complexity
• Successfully tested on representative tasks

See also

• /claude-md — author and optimize CLAUDE.md / .claude/rules/*.md. Project-wide instructions pair naturally with .claude/agents/*.md definitions; use this skill for the agent specs and /claude-md for the surrounding project memory.