create-subagent

name	create-subagent
description	Generates single-purpose Claude Code sub-agents for use via the Task tool. Use when creating dedicated sub-agents, scaffolding agent definitions, or generating agents with diagnostics and permissions setup.
user-invocable	true
argument-hint	<description-or-name> [--doc <requirements-path>]
skills	["subagent-prompting","anthropic-validator"]
allowed-tools	["AskUserQuestion","Bash","Read","Skill","Task","Write"]
version	1.0.0
author	Ashay Kubal @ Qball Inc.

Create Sub-Agent

Generates a complete single-purpose Claude Code sub-agent from a description or requirements document. Conducts an adaptive interview to understand the agent's identity and mission, determines tool permissions and supporting configuration, spawns a Sonnet sub-agent to generate the agent file, validates with anthropic-validator, and presents the scaffold with architectural decisions.

Sub-agents are invoked via Task(subagent_type=...) and run in a forked context. They perform a single focused task and return results. They cannot spawn other sub-agents — pipeline orchestration belongs in skills, not agents.

---

When to Use This Skill

Load this skill when the user request matches ANY of these patterns:

Trigger Pattern	Example User Request
Sub-agent creation	"Create a sub-agent for X", "Make an agent for X"
Agent scaffolding	"Scaffold an agent", "Set up a new agent"
Agent generation	"Generate an agent that does X"
Dedicated worker	"Create a dedicated agent for this sub-agent role"
Task tool agent	"I need an agent I can invoke via Task tool"

DO NOT use for:

• Creating pipeline orchestration (use create-skill — it generates the orchestrating skill + sub-agent files)
• Creating Agent Teams leads (use create-skill with the research template)
• Creating skills (use create-skill)
• Editing existing agents (edit directly)
• Debugging agent issues (use issue-debugging)
• Validating existing agents (use anthropic-validator)

---

Dependencies

Category	Files	Requirement	When to Load
Decision framework	references/decision-framework.md	REQUIRED	Load at Stage 0 for interview + classification
Agent conventions	references/agent-conventions.md	REQUIRED	Include in Stage 2 generator prompt
Content guidance	references/content-guidance.md	REQUIRED	Include in Stage 2 generator prompt
Agent template	references/template-single-agent.md	REQUIRED	Load at Stage 2
Diagnostic template	templates/diagnostic-output.yaml	REQUIRED	Use at Stage 6
Subagent prompting	subagent-prompting skill	REQUIRED	Load at Stage 0 for 4-part prompt template

Fallback behavior:

• If content-guidance is missing: Proceed without it, note in diagnostics (output quality will be lower)

---

Usage

/create-subagent <description-or-name>
/create-subagent --doc <requirements-document>

Arguments:

• <description-or-name> — Free-text description of the desired agent, or an agent name to start from
• --doc <path> — Path to a requirements document. Extracts interview answers from it instead of asking fresh.

Examples:

• /create-subagent a code security reviewer that checks for OWASP vulnerabilities — Start from description
• /create-subagent --doc plans/task-briefs/P4.4-implementer.md — Start from requirements doc
• /create-subagent market-analyst — Start from a name

---

Mandatory Execution Checklist (BINDING)

Every item below is mandatory. No deviations. No substitutions. No skipping.

This skill uses a 6-stage pipeline. You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.

• Stage 0 — Pre-Flight: Arguments parsed (description, name, or --doc)
• Stage 0 — Pre-Flight: Decision framework, agent conventions, and content guidance loaded
• Stage 0 — Pre-Flight: Adaptive interview conducted (1-2 rounds via AskUserQuestion)
• Stage 0 — Pre-Flight: Routing check completed (pipeline/teams → redirect to create-skill and STOP, OR single → proceed)
• Stage 1 — Classify: Two decisions made (tool permissions, supporting configuration)
• Stage 1 — Classify: Classification presented to user and confirmed via AskUserQuestion
• Stage 2 — Generate: Sonnet sub-agent spawned via Task tool (you do NOT generate the file yourself)
• Stage 2 — Generate: Generated agent file verified to exist in working directory
• Stage 2 — Generate: Agent uses system-prompt register (identity statement, not task steps)
• Stage 3 — Validate: /anthropic-validator invoked via Skill tool (manual review is NOT a substitute)
• Stage 3 — Validate: Validator output read and findings counted
• Stage 3 — Validate: Manual checks completed (single-line description, system-prompt register, permissions section)
• Stage 4 — Refine: If validation found critical/high issues, Sonnet sub-agent spawned to fix (max 2 retries)
• Stage 5 — Deploy: Agent file deployed from working directory to .claude/agents/
• Stage 5 — Deploy: Working directory cleaned up
• Stage 5 — Present: Post-generation summary presented with architectural decisions
• Stage 5 — Present: Permissions setup steps communicated
• Stage 5 — Present: Next steps communicated (this is a scaffold, not production-ready output)
• Stage 6 — Diagnostics: Diagnostic YAML written to $PROJECT_DIR/logs/diagnostics/

---

Pipeline

// create-subagent pipeline
PreFlight(args)                              // Stage 0: Orchestrator — parse input, interview, routing check
|> Classify(interview_answers)               // Stage 1: Orchestrator — two independent decisions
|> Generate(classification, template, conventions) // Stage 2: Sonnet sub-agent — produce agent file
|> Validate(generated_output)                // Stage 3: Orchestrator — run anthropic-validator
|> Refine(validator_findings)                // Stage 4: Sonnet sub-agent (conditional, max 2 retries)
|> DeployAndPresent(working_dir, target_dir)  // Stage 5: Orchestrator — deploy to target + post-generation summary
|> Diagnostics()                             // Stage 6: Orchestrator — write YAML

---

Stage Definitions

Stage 0: Pre-Flight (Orchestrator)

Stage 0: Pre-Flight
├── Parse arguments (description, name, or --doc path)
├── Load references/decision-framework.md
├── Load references/agent-conventions.md
├── Load references/content-guidance.md
├── Load subagent-prompting skill
├── If --doc provided:
│   ├── Read the requirements document
│   ├── Extract answers to Q1-Q5 from the document
│   └── Present extracted answers to user for confirmation via AskUserQuestion
├── If no --doc:
│   └── AskUserQuestion: Present all 5 core questions from decision-framework.md
│       ├── Q1: What is this agent's identity and mission? (2-3 invocation examples)
│       ├── Q2: What tools does it need access to?
│       ├── Q3: Single focused task, or multiple stages/operations?
│       ├── Q4: Does it need structured diagnostic output?
│       └── Q5: Restricted permissions or full access?
├── If complexity detected in answers (Q3 = "multiple stages"):
│   └── AskUserQuestion: Follow-up questions per decision-framework.md
│       ├── Q6: Do stages depend on each other's output?
│       ├── Q7: Do workers need direct communication?
│       └── Q8-Q10: Additional context-specific follow-ups
├── ROUTING CHECK (after all interview answers received):
│   ├── If Q3 = "multiple stages" AND (Q6 = "dependent" OR Q7 = "direct comms"):
│   │   └── STOP PIPELINE. Present redirect message to user:
│   │       "This use case requires a pipeline skill that orchestrates multiple sub-agents.
│   │        Sub-agents are single-purpose — they can't spawn other sub-agents.
│   │
│   │        Use /create-skill instead. It will generate:
│   │        - An orchestrating skill (SKILL.md) with pipeline stages
│   │        - Dedicated sub-agent files (.claude/agents/*.md) for each stage
│   │
│   │        The generated sub-agents will have deterministic behavior locked into their
│   │        system prompts, and the orchestrating skill handles sequencing, error handling,
│   │        and synthesis."
│   │       Do NOT proceed to Stage 1. Return to user.
│   └── Otherwise: Continue to Stage 1
├── Determine agent name (from input or derived from description)
│   └── Target: .claude/agents/{agent-name}.md
├── Set working directory: tmp/create-subagent/{agent-name}/
│   └── All generation and refinement happens here to avoid .claude/ edit approval storms
│       Files are deployed to the target directory only after validation passes (Stage 5)
└── Token budget check (warn if >30% consumed)

Interview behavior: Maximum 2 AskUserQuestion rounds. Present Q1-Q5 together in round 1. Follow-ups (if needed) in round 2. Do NOT ask questions one at a time.

Stage 1: Classify (Orchestrator)

Apply the two-decision classification from references/decision-framework.md:

Stage 1: Classify
├── Decision A: Tool Permissions
│   ├── Full access → no tools: list in frontmatter (inherits all)
│   ├── Restricted → tools: [specific list] in frontmatter
│   ├── If Write/Edit needed → include quality gate guidance in protocol
│   └── If Bash needed → include allowed/forbidden command lists in protocol
├── Decision B: Supporting Configuration
│   ├── Always: Permissions Setup section
│   ├── If diagnostics needed (Q4 = yes): diagnostic output section + schema
│   └── If diagnostics needed: subagent-output-templating in skills: dependency
└── Present classification to user via AskUserQuestion:
    ├── "Tool permissions: {full/restricted: [list]} — {reason}"
    ├── "Configuration: {list} — {reason}"
    └── "Proceed with generation? [Yes / Adjust]"

MANDATORY: Wait for user confirmation before proceeding to Stage 2. If user selects "Adjust", re-classify with their feedback.

Stage 2: Generate (Sonnet sub-agent)

Stage 2: Generate
├── Read references/template-single-agent.md
├── Construct prompt using 4-part template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT):
│   ├── GOAL: Generate a complete, structurally correct single-purpose sub-agent
│   │   definition. The agent must use system-prompt register and include all
│   │   required sections (Pre-Flight, Mission, Protocol, Output, Permissions).
│   ├── CONSTRAINTS:
│   │   ├── Write in SYSTEM-PROMPT REGISTER — WHO the agent IS, not WHAT to do
│   │   ├── Open with identity statement: "You are a..."
│   │   ├── Use present tense for behavioral descriptions
│   │   ├── Description MUST be a single line (multi-line breaks discovery)
│   │   ├── Description MUST use role-based trigger framing
│   │   ├── Include Pre-Flight Gate with MUST/MUST NOT (binding language)
│   │   ├── Include DO/DO NOT mission section
│   │   ├── Include Tool Usage Constraints for every tool in frontmatter
│   │   ├── Include Permissions Setup section (tool permissions unsolved per #10093)
│   │   ├── Do NOT add unnecessary files (no README, CHANGELOG, LICENSE)
│   │   ├── Do NOT use emojis in generated content
│   │   └── Keep agent under 250 lines
│   ├── CONTEXT:
│   │   ├── Classification from Stage 1 (both decisions)
│   │   ├── User's interview answers (identity, mission, tools from Q1-Q5)
│   │   ├── Template: references/template-single-agent.md
│   │   ├── Agent conventions: references/agent-conventions.md
│   │   ├── Content guidance: references/content-guidance.md
│   │   ├── Instruction: "Read 1-2 existing agents from the codebase for structural
│   │   │   reference (use Glob to find .claude/agents/*.md)"
│   │   ├── Target output path: .claude/agents/{agent-name}.md (final deployment location)
│   │   └── Working directory: tmp/create-subagent/{agent-name}/
│   └── OUTPUT:
│       ├── Write agent file to {working-directory}/{agent-name}.md
│       └── Return summary: file path with line count
├── Spawn: Task(description="Generate agent file", subagent_type="general-purpose",
│          model="sonnet", prompt=...)
├── Read generator output (file path + summary)
└── Verify file was created (Read {working-directory}/{agent-name}.md)

Stage 3: Validate (Orchestrator)

Stage 3: Validate
├── FIRST: Invoke /anthropic-validator (this is the PRIMARY validation — NOT optional)
│   ├── Use the Skill tool: Skill(skill="anthropic-validator", args="{working-directory}/{agent-name}.md")
│   ├── Do NOT substitute manual review for this step
│   └── Do NOT proceed past this node until the Skill tool has been invoked
├── Read validator output
├── Check for critical/high findings:
│   ├── 0 critical AND 0 high → proceed to Stage 5 (skip Stage 4)
│   └── Any critical or high → proceed to Stage 4 (refine)
├── THEN: Manual checks (these supplement the validator, they do NOT replace it)
│   ├── Check description is single-line (read agent file, verify no multiline description)
│   ├── Check system-prompt register (body opens with identity, not task steps)
│   └── Check Permissions Setup section exists
└── Stage 3 exit gate:
    ├── [ ] /anthropic-validator was invoked via the Skill tool (not manual review)
    ├── [ ] Validator output was read and findings counted
    └── If either is unchecked, Stage 3 is NOT complete — go back and invoke the validator

Stage 4: Refine (Sonnet sub-agent, conditional, max 2 retries)

This stage only runs if Stage 3 found critical or high issues.

Stage 4: Refine (attempt {N} of 2)
├── Construct prompt using 4-part template:
│   ├── GOAL: Fix all critical and high findings from anthropic-validator
│   ├── CONSTRAINTS:
│   │   ├── Only fix the specific issues identified — do not restructure
│   │   ├── Preserve the existing agent content and identity
│   │   ├── Description must remain single-line
│   │   └── Must remain in system-prompt register
│   ├── CONTEXT:
│   │   ├── Validator findings (critical and high items with descriptions)
│   │   ├── Current generated file (read from {working-directory}/{agent-name}.md)
│   │   └── Agent conventions: references/agent-conventions.md
│   └── OUTPUT: Edit file at {working-directory}/{agent-name}.md to fix findings
├── Spawn: Task(description="Fix validator findings", subagent_type="general-purpose",
│          model="sonnet", prompt=...)
├── Re-run Stage 3 (validate)
├── If still failing after 2 retries:
│   └── Proceed to Stage 5 with caveats noted
└── Token budget check

Stage 5: Deploy & Present (Orchestrator)

Stage 5: Deploy & Present
├── Deploy: Move {working-directory}/{agent-name}.md to .claude/agents/{agent-name}.md
│   ├── This is the ONLY point where the file is written to .claude/
│   └── Clean up: Remove {working-directory}/ after successful copy
├── Read generated agent file from .claude/agents/{agent-name}.md for summary
├── Present to user:
│   ├── "Generated agent at: .claude/agents/{agent-name}.md"
│   ├── "Lines: {count}"
│   ├── "Architectural decisions:"
│   │   ├── "Tool permissions: {full/restricted: [list]} — {reason}"
│   │   └── "Configuration: {list} — {reason}"
│   ├── "Validation: {pass/fail with details}"
│   ├── If caveats: "Unresolved issues: {list}"
│   ├── "Permissions to configure:"
│   │   └── {List tool permissions that must be added to settings.json}
│   └── "Next steps:"
│       ├── "1. Review and customize the identity and expertise sections"
│       ├── "2. Adjust tool permissions in .claude/settings.json"
│       ├── "3. Test by invoking via Task tool: Task(subagent_type=\"{name}\", prompt=\"...\")"
│       ├── "4. Add project-specific protocol steps as needed"
│       └── "5. Configure Stop hook if diagnostic output is needed"
└── Note: This is a scaffold, not production-ready output (generate-and-customize contract)

Stage 6: Diagnostics (REQUIRED)

MANDATORY: Write diagnostic output after every invocation. This cannot be skipped.

Stage 6: Diagnostics
├── Write to: $PROJECT_DIR/logs/diagnostics/create-subagent-{YYYYMMDD-HHMMSS}.yaml
│   └── Use templates/diagnostic-output.yaml schema
└── Include:
    ├── Input: description/name/doc path
    ├── Interview: questions asked, rounds completed
    ├── Routing: redirected (true/false), reason if redirected
    ├── Classification: both decisions
    ├── Generation: file created, line count, model used
    ├── Validation: pass/fail, findings count, retry count
    └── Outcome: success/partial/failure/redirected

---

Error Handling

Scenario	Action
Generator sub-agent returns empty output	Re-spawn once with reinforced instructions. If still empty, STOP: "Generation failed. Please try with a more detailed description."
anthropic-validator finds critical issues	Stage 4 retry (max 2). After 2 retries, present with caveats.
anthropic-validator unavailable	Skip validation, note in diagnostics, warn user: "Validation skipped — run /anthropic-validator manually."
Interview answers are ambiguous	Ask 1-2 follow-up questions (max 2 AskUserQuestion rounds total).
Pipeline/teams detected in interview	STOP pipeline. Redirect to /create-skill with guidance message. Write diagnostic with outcome: redirected.
Token budget exceeded	Stop at current stage, present partial output with explanation.
Agent file already exists at target path	AskUserQuestion: "Agent {name} already exists at .claude/agents/{name}.md. Overwrite / Choose different name / Cancel?"
Working directory already exists	Silently remove and recreate tmp/create-subagent/{agent-name}/ (working dirs are ephemeral)
User rejects classification	Re-classify with user's feedback. Max 2 classification rounds.
Generated agent uses task-instruction register	Stage 4 refine with specific instruction to rewrite in system-prompt register.

---

Token Budget Management

Checkpoint	Threshold	Action
After Pre-Flight	>30% consumed	Warn: "Remaining budget may limit validation and refinement."
After Generate	>55% consumed	Warn: "Approaching budget. Validation + refinement may be limited."
After Validate	>65% consumed	Skip refinement if needed, present as-is with caveats.