tomevault-io 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 suggesthaikufor 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: Alwaysinheritunless user confirms otherwisetools: 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.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.