Create a New Agent

Define a Claude Code subagent persona with a focused purpose, curated tools, assigned skills, and complete documentation following the agent template and registry conventions.

When to Use

• Adding a new specialist agent to the library for a domain not yet covered
• Converting a recurring workflow or prompt pattern into a reusable agent persona
• Creating a domain-specific assistant with curated skills and constrained tools
• Splitting an overly broad agent into focused, single-responsibility agents
• Designing a new team member before composing a multi-agent team

Inputs

• Required: Agent name (lowercase kebab-case, e.g., data-engineer)
• Required: One-line description of the agent's primary purpose
• Required: Purpose statement explaining the problem the agent solves
• Optional: Model choice (default: sonnet; alternatives: opus, haiku)
• Optional: Priority level (default: normal; alternatives: high, low)
• Optional: List of skills from skills/_registry.yml to assign
• Optional: MCP servers the agent requires (e.g., r-mcptools, hf-mcp-server)

Procedure

Step 1: Design the Agent Persona

Choose a clear, focused identity for the agent:

• Name: lowercase kebab-case, descriptive of the role. Start with a noun or domain qualifier: security-analyst, r-developer, tour-planner. Avoid generic names like helper or assistant.
• Purpose: one paragraph explaining the specific problem this agent solves. Ask: "What does this agent do that no existing agent covers?"
• Communication style: consider the domain. Technical agents should be precise and citation-heavy. Creative agents can be more exploratory. Compliance agents should be formal and audit-oriented.

Before proceeding, check for overlap with the existing agents (agents/_registry.yml is the authoritative roster):

grep -i "description:" agents/_registry.yml | grep -i "<your-domain-keywords>"

Expected: No existing agent covers the same niche. If an existing agent partially overlaps, consider extending it instead of creating a new one.

On failure: If an agent with significant overlap exists, either extend that agent's skills list or narrow your new agent's scope to complement rather than duplicate it.

Step 2: Select Tools

Choose the minimal set of tools the agent needs. Principle of least privilege applies:

Tool Set	When to Use	Example Agents
[Read, Grep, Glob]	Read-only analysis, review, auditing	code-reviewer, security-analyst, auditor
[Read, Grep, Glob, WebFetch]	Analysis plus external lookups	senior-researcher
[Read, Write, Edit, Bash, Grep, Glob]	Full development — creating/modifying code	r-developer, web-developer, devops-engineer
[Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch]	Development plus external research	polymath, shapeshifter

Do not include Bash for agents that only analyze code. Do not include WebFetch or WebSearch unless the agent genuinely needs to look up external resources.

Expected: Tool list contains only tools the agent will actually use in its primary workflows.

On failure: Review the agent's capabilities list — if a capability does not require a tool, remove the tool.

Step 3: Choose Model

Select the model based on task complexity:

• sonnet (default): Most agents. Good balance of reasoning and speed. Use for development, review, analysis, and standard workflows.
• opus: Complex reasoning, multi-step planning, nuanced judgment. Use for senior-level agents, architectural decisions, or tasks requiring deep domain expertise.
• haiku: Simple, fast responses. Use for agents doing straightforward lookups, formatting, or template-filling.

Expected: Model matches the cognitive demands of the agent's primary use cases.

On failure: When in doubt, use sonnet. Upgrade to opus only if testing reveals insufficient reasoning quality.

Step 4: Assign Skills

Browse the skills registry and select skills relevant to the agent's domain:

# List all skills in a domain
grep -A3 "domain-name:" skills/_registry.yml

# Search for skills by keyword
grep -i "keyword" skills/_registry.yml

Build the skills list for the frontmatter:

skills:
  - skill-id-one
  - skill-id-two
  - skill-id-three

Important: All agents automatically inherit the default skills (meditate, heal) from the registry-level default_skills field. Do NOT list these in the agent's frontmatter unless they are core to the agent's methodology (e.g., the mystic agent lists meditate because meditation facilitation is its primary purpose).

Expected: Skills list contains 3-15 skill IDs that exist in skills/_registry.yml.

On failure: Verify each skill ID exists: grep "id: skill-name" skills/_registry.yml. Remove any that do not match.

Step 5: Write the Agent File

Copy the template and fill in the frontmatter:

cp agents/_template.md agents/<agent-name>.md

Fill in the YAML frontmatter:

---
name: agent-name
description: One to two sentences describing primary capability and domain
tools: [Read, Write, Edit, Bash, Grep, Glob]
model: sonnet
version: "1.0.0"
author: Philipp Thoss
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [domain, specialty, relevant-keywords]
priority: normal
max_context_tokens: 200000
skills:
  - assigned-skill-one
  - assigned-skill-two
# Note: All agents inherit default skills (meditate, heal) from the registry.
# Only list them here if they are core to this agent's methodology.
# mcp_servers: []  # Uncomment and populate if MCP servers are needed
---

Expected: YAML frontmatter parses without errors. All required fields (name, description, tools, model, version, author) are present.

On failure: Validate YAML syntax. Common issues: missing quotes around version strings, incorrect indentation, unclosed brackets in tool lists.

Step 6: Write Purpose and Capabilities

Replace the template placeholder sections:

Purpose: One paragraph explaining the specific problem this agent solves and the value it provides. Be concrete — name the domain, the workflow, and the outcome.

Capabilities: Bulleted list with bold lead-ins. Group by category if the agent has many capabilities:

## Capabilities

- **Primary Capability**: What the agent does best
- **Secondary Capability**: Additional functionality
- **Tool Integration**: How it leverages its tools

Available Skills: List each assigned skill with a brief description. Use bare skill IDs (the slash-command names):

## Available Skills

- `skill-id` - Brief description of what the skill does

Expected: Purpose is specific (not "helps with development"), capabilities are concrete and verifiable, skills list matches frontmatter.

On failure: If the purpose feels vague, answer: "What specific task would a user ask this agent to do?" Use that answer as the purpose.

Step 7: Write Usage Scenarios and Examples

Provide 2-3 usage scenarios showing how to spawn the agent:

### Scenario 1: Primary Use Case
Brief description of the main scenario.

> "Use the agent-name agent to [specific task]."

### Scenario 2: Alternative Use Case
Description of another common use case.

> "Spawn the agent-name to [different task]."

Add 1-2 concrete examples showing a user request and the expected agent behavior:

### Example 1: Basic Usage
**User**: [Specific request]
**Agent**: [Expected response pattern and actions taken]

Expected: Scenarios are realistic, examples show actual value, invocation patterns match Claude Code conventions.

On failure: Test the examples mentally — would the agent actually be able to fulfill the request with its assigned tools and skills?

Step 8: Write Limitations and See Also

Limitations: 3-5 honest constraints. What the agent cannot do, should not be used for, or where it might produce poor results:

## Limitations

- Cannot execute code in language X (no runtime available)
- Not suitable for tasks requiring Y — use Z agent instead
- Requires MCP server ABC to be running for full functionality

See Also: Cross-reference complementary agents, relevant guides, and related teams:

## See Also

- [complementary-agent](complementary-agent.md) - handles the X side of this workflow
- [relevant-guide](../guides/guide-name.md) - background knowledge for this domain
- [relevant-team](../teams/team-name.md) - team that includes this agent

Expected: Limitations are honest and specific. See Also references existing files.

On failure: Check that referenced files exist: ls agents/complementary-agent.md.

Step 9: Add to Registry

Edit agents/_registry.yml and add the new agent entry in alphabetical position:

  - id: agent-name
    path: agents/agent-name.md
    description: Same one-line description from frontmatter
    tags: [domain, specialty]
    priority: normal
    tools: [Read, Write, Edit, Bash, Grep, Glob]
    skills:
      - skill-id-one
      - skill-id-two

Increment the total_agents count at the top of the file.

Expected: Registry entry matches the agent file frontmatter. total_agents equals the actual number of agent entries.

On failure: Count entries with grep -c "^ - id:" agents/_registry.yml and verify it matches total_agents.

Step 10: Verify Discovery

Claude Code discovers agents from the .claude/agents/ directory. In this repository, that directory is a symlink to agents/:

# Verify the symlink exists and resolves
ls -la .claude/agents/
readlink -f .claude/agents/<agent-name>.md

If the .claude/agents/ symlink is intact, no additional action is needed — the new agent file is automatically discoverable (agents use a single directory symlink per layer, so a new agent needs no per-agent link). To ensure both the project and global (~/.claude/agents) directory symlinks are present, run the discovery sync (it also covers skills):

bash scripts/sync-discovery-symlinks.sh --fix

Run the README automation to update the agents README:

npm run update-readmes

Expected: .claude/agents/<agent-name>.md resolves to the new agent file. agents/README.md includes the new agent.

On failure: If the symlink is broken, recreate it: ln -sf ../agents .claude/agents. If npm run update-readmes fails, check that scripts/generate-readmes.js exists and js-yaml is installed.

Step 11: Scaffold Translations

Required for all agents. This step applies to both human authors and AI agents following this procedure. Do not skip — missing translations accumulate into stale backlog.

Scaffold translation files for all 4 supported locales immediately after committing the new agent:

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- agents <agent-name> "$locale"
done

Then translate the scaffolded prose in each file (code blocks and IDs stay in English). Finally regenerate the status files:

npm run translation:status

Expected: 4 files created at i18n/{de,zh-CN,ja,es}/agents/<agent-name>.md, all with source_commit matching current HEAD. npm run validate:translations shows 0 stale warnings for the new agent.

On failure: If scaffold fails, verify the agent exists in agents/_registry.yml. If status files don't update, run npm run translation:status explicitly — it is not triggered automatically by CI.

Validation

• Agent file exists at agents/<agent-name>.md
• YAML frontmatter parses without errors
• All required fields present: name, description, tools, model, version, author
• name field matches the filename (without .md)
• All sections present: Purpose, Capabilities, Available Skills, Usage Scenarios, Examples, Limitations, See Also
• Skills in frontmatter exist in skills/_registry.yml
• Default skills (meditate, heal) are NOT listed unless core to agent methodology
• Tools list follows least-privilege principle
• Agent is listed in agents/_registry.yml with correct path and matching metadata
• total_agents count in registry is updated
• .claude/agents/ symlink resolves to the new agent file
• No significant overlap with existing agents

Common Pitfalls

• Tool over-provisioning: Including Bash, Write, or WebFetch when the agent only needs to read and analyze. This violates least-privilege and can lead to unintended side effects. Start with the minimal set and add tools only when a capability requires them.
• Missing or wrong skill assignments: Listing skill IDs that do not exist in the registry, or forgetting to assign skills entirely. Always verify each skill ID with grep "id: skill-name" skills/_registry.yml before adding it.
• Listing default skills unnecessarily: Adding meditate or heal to the agent frontmatter when they are already inherited from the registry. Only list them if they are core to the agent's methodology (e.g., mystic, alchemist, gardener, shaman).
• Scope overlap with existing agents: Creating a new agent that duplicates functionality already covered by one of the 72 existing agents. Always search the registry first and consider extending an existing agent's skills instead.
• Vague purpose and capabilities: Writing "helps with development" instead of "scaffolds R packages with complete structure, documentation, and CI/CD configuration." Specificity is what makes an agent useful and discoverable.

Related Skills

• create-skill - the parallel procedure for creating SKILL.md files instead of agent files
• create-team - compose multiple agents into a coordinated team (planned)
• commit-changes - commit the new agent file and registry update