Sub-Agent Creator

Interactive skill for creating Claude Code subagents. Guides the complete process: gathering requirements, designing the agent's purpose and persona, selecting helpful skills and documentation, and writing a properly formatted agent file to .claude/agents/ .

Critical Formatting Rules

Subagents MUST follow strict formatting or they will fail validation and not load:

Rule Requirement Consequence

Single-line description description must be one line, no \n

Validation failure

No literal \n

Use actual newlines in body, not \n escapes Validation failure

Valid colors only If specified: red, blue, green, yellow, purple, orange, pink, cyan Agent won't load

Valid models only sonnet , opus , haiku , or inherit

Validation failure

Name format Lowercase letters, numbers, hyphens only Validation failure

Examples of WRONG vs RIGHT

WRONG - Multi-line YAML syntax

description: | Expert code reviewer. Use after code changes.

WRONG - Actual newlines in value

description: Expert code reviewer. Use after code changes.

RIGHT - ONE continuous line

description: Expert code reviewer. Use proactively after code changes.

WRONG - Literal \n in body

name: test-runner description: Run tests

You are a test runner.\nWhen invoked:\n1. Run tests\n2. Report results

RIGHT - Actual newlines

name: test-runner description: Run tests

You are a test runner. When invoked:

1. Run tests
2. Report results

Workflow

1. Understand Requirements

When this skill triggers, the user has described what kind of agent they want. First, extract:

• Core purpose: What should this agent do?

• Trigger conditions: When should Claude delegate to this agent?

• Key capabilities: What specific tasks will it handle?

• Existing context: Any relevant skills, docs, or project patterns?

2. Use AskUserQuestion for Details

Ask clarifying questions using the AskUserQuestion tool. Confirm:

• Identifier: What should the agent be named? (lowercase-with-hyphens)

• Proactive usage: Should this agent be used proactively or only on explicit request?

• Model: Default to inherit . Only suggest haiku for simple, fast tasks. ALWAYS confirm before using non-inherit models.

• Color: Auto-select from valid options (red, blue, green, yellow, purple, orange, pink, cyan) OR let user choose.

3. Identify Helpful Context

Search the workspace for:

Relevant skills: Check .claude/skills/ and project skills that would help the agent.

ls .claude/skills/

Relevant documentation: Look for references files, CLAUDE.md, API docs, etc.

find . -name "*.md" -type f | head -20

4. Design the System Prompt

Using the agent creation architect framework (see references/agent-creation-prompt.md ):

• Extract Core Intent - Fundamental purpose and success criteria

• Design Expert Persona - Compelling identity with domain knowledge

• Architect Instructions - Behavioral boundaries, methodologies, edge cases

• Optimize for Performance - Decision frameworks, quality control

• Create whenToUse Examples - Concrete examples showing delegation

The system prompt should be in second person ("You are...", "You will...").

5. Write the Agent File

Write the agent file to .claude/agents/<identifier>.md :

name: <identifier> description: <single-line description with when to use> model: inherit

<system prompt in markdown body>

Default settings:

• model : Always inherit unless user confirms otherwise

• tools : Omit to allow all tools (user preference: never restrict)

• skills : Include if specific skills would help the agent

6. Validate Before Completing

Run the validation script:

python .claude/skills/sub-agent-creator/scripts/validate_agent.py .claude/agents/<identifier>.md

Only proceed if validation passes. Fix any errors and re-validate.

Agent File Template

name: agent-identifier description: Brief single-line description starting with what it does. Use proactively when [trigger condition]. model: inherit skills:

• relevant-skill-1
• relevant-skill-2

You are an expert [domain] specialist.

When invoked:

1. [First step]
2. [Second step]
3. [Continue as needed]

Your approach:

• [Guideline 1]
• [Guideline 2]

For each [task], provide:

• [Output format 1]
• [Output format 2]

Focus on [core principle].

Description Best Practices

The description field is Claude's primary signal for when to delegate. Include:

• What the agent does: "Expert code reviewer specializing in..."

• When to use: "Use proactively after writing code" or "Use when analyzing..."

• Triggers: Specific situations that should trigger delegation

Examples:

description: Test execution specialist. Use proactively after writing tests or modifying test files. description: Database query analyst. Use when needing to analyze data or generate reports from BigQuery. description: Code archaeology expert. Use when exploring legacy codebases or understanding unfamiliar code.

Resources

• scripts/validate_agent.py - Validates agent files for formatting errors

• references/sub-agents-docs.md - Complete Claude Code subagents documentation

• references/agent-creation-prompt.md - Agent creation architect system prompt framework

After creating an agent, verify it appears in /agents command output.