Agent Creator

Create custom Claude Code subagents: autonomous subprocesses with isolated context, specific tools, independent permissions, and tailored system prompts. [EXPLICIT]

When To Activate

Use this skill when the user asks for a persistent subagent or custom agent definition, for example:

• "create an agent"
• "add a subagent"
• "make a custom agent"
• "define agent definition"
• "build an agent for X"
• "I need something to handle X automatically"

Use agent-constitution-creator instead when the user needs a full governance constitution with identity, authority, memory, handoff, and multi-agent operating rules.

Deterministic Contract

• Use assets/agent-spec-schema.json as the canonical structured input shape.
• Use assets/tool-policy.json to choose least-privilege tools, disallowedTools, Agent, Skill, and MCP access while rejecting wildcard access.
• Use assets/model-selection-policy.json to map complexity to Claude Code model aliases, inherit, or a full Claude model id.
• Use assets/description-trigger-policy.json to keep descriptions focused on WHEN the parent should spawn the agent.
• Use assets/frontmatter-policy.json for supported subagent frontmatter and plugin-agent unsupported fields.
• Use assets/orchestration-selection-policy.json to decide whether the user needs a custom subagent, built-in subagent, agent view session, agent team, workflow, skill, hook, or main-conversation work.
• Use assets/hook-policy.json to separate subagent frontmatter hooks from project-level SubagentStart and SubagentStop hooks.
• Use assets/agent-template.md as the rendering skeleton.
• Run scripts/compile-agent.py before finalizing an agent definition from structured input.
• Run scripts/check.sh to verify positive and negative fixtures offline.
• Do not call external APIs, MCP servers, network resources, or live agent registries from the skill scripts.

Procedure

Step 1: Decide Whether An Agent Is Appropriate

Do not create an agent when a lighter artifact fits better:

Use a custom subagent when the responsibility is repeatable, self-contained, and better handled in an isolated context with an explicit tool or permission contract.

If the request is underspecified, ask only for the missing fields required by assets/agent-spec-schema.json: responsibility, scope, read/write authority, expected output, and complexity.

Step 2: Discover Existing Agents

1. Read project-local agent definitions, usually .claude/agents/*.md.
2. Read global definitions only when the user asks for a global agent.
3. Check for name collisions with built-ins: Explore, Plan, general-purpose.
4. Check for scope overlap. If another agent owns the same responsibility, propose rename, merge, split, or non-goals before writing.

Step 3: Normalize The Spec

Normalize the request into five sections:

• agent: name, display name, role, responsibility, scope, and non-goals.
• routing: trigger phrases, negative triggers, destination scope, model, color, tools, disallowedTools, permission mode, scoped MCP, hooks, skills, memory, background, effort, isolation, turn limits, and initial prompt.
• behavior: task statement, ordered process, output format, constraints, and reasoning tier.
• quality: quality bar, validation checks, escalation triggers, and residual risks.
• evidence: source labels and evidence tags for decisions that came from the user, codebase, or inference.

Step 4: Compile

python3 skills/agent-creator/scripts/compile-agent.py \
  --input skills/agent-creator/scripts/fixtures/agent-spec-input.json

The compiler emits Markdown by default and stable JSON with --format json. It fails if the name is invalid, trigger conditions are missing, model or tools are unsafe, process steps are too thin, output format is absent, constraints lack a negative boundary, or collision rules are violated.

Step 5: Validate

• Run bash skills/agent-creator/scripts/check.sh to verify positive and negative fixtures offline (the only validator shipped with this skill).
• Treat runtime installation into .claude/agents/ or ~/.claude/agents/ as a separate user-approved mutation.

Agent File Anatomy & Frontmatter

The full agent-file skeleton, the frontmatter decision matrix (all fields + plugin-agent restrictions), built-in subagent distinctions, tool-restriction patterns, and the scoped MCP/hooks/memory/isolation rules live in references/frontmatter-and-fields.md. Load it when authoring the actual file. Two rules stay here: description states WHEN to spawn (not WHAT); default tools to read-only and widen only on demonstrated need (least privilege, Constitution Art. 3).

When To Use Subagent, Agent View, Team, Or Workflow

System Prompt Design Principles

Validation Gate & Edge Cases

The full validation checklist and the edge-case playbook (project context, over-spawning, verbose output, overlapping agents, agent-view vs subagent, plugin-agent limits) live in references/validation-and-edge-cases.md. Gate every generated agent through it (the Guardian role / scripts/check.sh enforce the same checks).

Related Assets

• assets/source-map.md
• references/domain-knowledge.md
• assets/frontmatter-policy.json
• assets/orchestration-selection-policy.json
• assets/hook-policy.json
• scripts/compile-agent.py

Contract

• Aceptación: subagente con description WHEN-to-spawn, tools least-priv, prompt autosuficiente, sin colisión con builtins. [EXPLICIT]
• Límites: crea la definición; instalar en .claude/agents/ es una mutación aparte aprobada por el usuario. [EXPLICIT]
• Casos borde: plugin-agents ignoran hooks/mcpServers/permissionMode; sub-spawns solo si Agent está en tools. [EXPLICIT]
• Supuestos: subagentes no-fork arrancan con contexto fresco. [SUPUESTO]
• Trade-off: aislar en subagente cuesta orquestación; usar solo si la responsabilidad es repetible y autocontenida. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · scripts/ automatización local · assets/ recursos estáticos.