Create Subagent

If a subagent already exists with that name:

1. Inform the user: "A subagent named {requested-name} already exists."
2. Suggest using /agent-customizer:improve-subagent to evaluate and optimize it instead.
3. STOP — do not proceed. The user should either choose a different name or use the improve skill.

If no subagent exists with that name: Proceed to Phase 1 below.

Phase 1: Codebase Analysis

Delegate to the artifact-analyzer agent with this task:

Analyze the project to understand existing subagents. Focus on: agent names and roles in .claude/agents/ and plugins/*/agents/, tool restrictions in use, model choices, maxTurns values, which skills delegate to which agents, and naming conventions. Flag any agents similar in purpose to {requested-name}. Also identify the project layout: whether this is a monorepo (multiple plugin directories, workspace files like pnpm-workspace.yaml) or a single-package project.

The agent runs on Sonnet with read-only tools (Read, Grep, Glob, Bash) in an isolated context. Wait for it to complete and parse its structured output.

Phase 2: Generate Subagent

Before generating, read these reference documents:

• ${CLAUDE_SKILL_DIR}/references/subagent-authoring-guide.md — when to use subagents, system prompt structure, model selection heuristics, tool restriction patterns, anti-patterns
• ${CLAUDE_SKILL_DIR}/references/subagent-config-reference.md — YAML frontmatter fields, valid model IDs, tool allowlist/denylist, orchestration patterns, plugin restrictions
• ${CLAUDE_SKILL_DIR}/references/prompt-engineering-strategies.md — subagent-specific prompting (role prompting, structured output, confidence filtering)

Read ${CLAUDE_SKILL_DIR}/assets/templates/subagent-definition.md and fill its placeholders using:

• User requirements for the new subagent (role, purpose, tools needed)
• Phase 1 analysis output (existing agents, naming conventions, delegation patterns)
• Evidence from the reference files above

Apply model selection heuristic:

• haiku — fast read-only exploration agents (simple lookups, no reasoning required)
• sonnet — standard analysis and review agents (default for most subagents)
• opus — complex multi-step reasoning only (requires explicit justification)

Determine target location:

• .claude/agents/{name}.md — project-level agent (accessible everywhere)
• plugins/{plugin}/agents/{name}.md — plugin-scoped agent (restricted to plugin context)

Phase 3: Self-Validation

Read ${CLAUDE_SKILL_DIR}/references/subagent-validation-criteria.md and execute its Validation Loop Instructions against the generated subagent definition.

The loop evaluates all hard limits and quality checks, fixes any failures, and re-evaluates — maximum 3 iterations. Do not proceed to Phase 4 until ALL criteria pass.

Phase 4: Present and Write

1. Show the user the complete generated subagent definition
2. Cite the evidence from reference files that informed key decisions:
   • Why this model was chosen (heuristic applied)
   • Why these tools are included/excluded (principle of least privilege)
   • What the output format enforces and why
3. If the user requested plugin-restricted fields (hooks, mcpServers, permissionMode), warn that these fields are ignored in plugin context
4. Ask for confirmation before writing any files
5. On approval, write the subagent definition to the target location