Agent Creator

Creates spec-compliant agent .md files following Anthropic's current documented subagent frontmatter contract. Supports both creation of new agents and validation of existing ones.

Overview

Agent Creator fills the gap between ad-hoc agent files and production-grade agents that pass marketplace validation. It distinguishes the 16 fields in Anthropic's public frontmatter table from runtime-recognized experimental options, then layers the stricter Intent Solutions required set on top. It prevents common mistakes (using allowed-tools instead of disallowedTools, adding invalid fields like capabilities or expertise_level), and produces agents with substantive body content that actually guides Claude's behavior.

Key difference from skill-creator: agents support both tools (allowlist) AND disallowedTools (denylist). Skills use allowed-tools (allowlist) and, since schema 3.7.0, an optional kebab-case disallowed-tools denylist — a parallel field, not a unification. Agents also support effort, maxTurns, skills, memory, isolation, permissionMode, background, color, and initialPrompt — fields that don't exist for skills. Claude Code also recognizes a separately labeled runtime experimental object; do not present it as part of the public 16-field table. The agent body becomes the system prompt that drives the subagent — it does NOT receive the full Claude Code system prompt.

Field-naming warning: Agents use camelCase disallowedTools: (canonical sub-agents spec); skills use kebab-case disallowed-tools: (schema 3.7.0+). The validator rejects either mismatch — never copy-paste between agent and skill frontmatter without renaming.

Prerequisites

• Claude Code CLI with agent support
• Target directory writable (agents/ within a plugin or ~/.claude/agents/ for standalone)
• Familiarity with what the agent should specialize in

Instructions

Mode Detection

Determine user intent from their prompt:

• Create mode: "create an agent", "build a subagent", "new agent" -> Step 1
• Validate mode: "validate agent", "check agent", "grade agent" -> Validation Workflow

Step 1: Understand Requirements

Ask the user with AskUserQuestion:

Agent Identity:

• Name (kebab-case, 1-64 chars, e.g., risk-assessor, clause-analyzer)
• Specialty description (20-1536 chars under the IS contract; keep it concise for the selection UI)

Execution Context:

• Plugin agent (plugins/*/agents/) or standalone (~/.claude/agents/)?
• Will it run as the main --agent, or be spawned through the Agent tool?
• May it delegate to nested subagents? If yes, include Agent; if no, omit or deny it.
• Does it need to preload specific skills? (skills: [skill-name])

Behavioral Controls:

• Model override? (sonnet, opus, haiku, fable, inherit, or a full Claude model ID)
• Reasoning effort? (low for simple, medium default, high for complex analysis)
• Max iterations? (maxTurns — how many tool-use loops before stopping)
• Tools to deny? (disallowedTools — denylist approach, opposite of skills)

Plugin Restrictions (if plugin agent):

• hooks — NOT supported in plugin agents (use plugin-level hooks)
• mcpServers — NOT supported in plugin agents
• permissionMode — standalone only, NOT plugin agents

Step 2: Plan the Agent

Before writing, determine:

Agent Role Clarity: The agent body must make three things unambiguous:

1. What it IS responsible for — its specific domain/methodology
2. What it is NOT responsible for — boundaries with other agents
3. How it communicates results — output format and structure

Body Structure Pattern: All production agents should follow this body structure:

Output Structure Decision:

• If the agent feeds into an orchestrator: use JSON output (machine-parseable)
• If the agent is user-facing: use markdown output (human-readable)
• If the agent produces both: JSON primary with markdown summary

Step 3: Write the Agent File

Generate the agent .md using the template from ${CLAUDE_SKILL_DIR}/../skill-creator/templates/agent-template.md. Use Write for a new definition and Edit for a targeted remediation of an existing definition; do not replace unrelated project content.

Frontmatter Rules (documented schema plus runtime extension):

See Anthropic Agent Spec for the full official reference.

Upstream-required fields:

name: {agent-name}         # Lowercase letters and hyphens, unique identifier
description: "{specialty}"  # When Claude should delegate to this subagent

For marketplace output, the IS overlay also emits tools, model, color, version, author, tags, disallowedTools, skills, and background. Standalone agents additionally emit hooks, mcpServers, and permissionMode; omit those three from plugin agents. The remaining tuning fields stay optional until the requested behavior needs them.

Marketplace fields and optional tuning controls:

tools: "Read, Glob, Grep"  # Allowlist — inherits all tools if omitted
disallowedTools: [Write]   # IS denylist form — removed from inherited/specified list
model: sonnet              # sonnet|haiku|opus|fable|inherit|full Claude model ID
color: blue                # Display: red|blue|green|yellow|purple|orange|pink|cyan
version: 1.0.0
author: "Name <email@example.com>"
tags: [specialty, workflow]
effort: medium             # low|medium|high|xhigh|max (availability depends on model)
maxTurns: 15               # Max agentic turns before stopping
skills: [skill-name]       # Skills to preload (unlisted skills remain invocable)
memory: project            # user|project|local — persistent cross-session
background: false          # Always run as background task
isolation: worktree        # Run in temporary git worktree
initialPrompt: "..."       # Auto-submitted first turn (--agent mode only)
permissionMode: default    # Also accepts manual as a default alias; ignored in plugins
hooks: {}                  # Standalone only, NOT plugin agents
mcpServers: []             # Standalone only; names or inline definitions
experimental:              # Claude Code v2.1.248+; optional
  cacheTtl: 5m             # 5m|1h

Tool access:

• tools = allowlist (like skills' allowed-tools)
• disallowedTools = denylist (remove specific tools)
• If both set: disallowed applied first, then tools resolved
• If neither set: inherits all tools from parent conversation
• Naming: always emit camelCase disallowedTools on agents. Skills spell their denylist kebab-case (disallowed-tools, schema 3.7.0+) — the validator rejects camelCase on skills and kebab-case on agents, so never copy-paste between the two without renaming

Invalid fields (ERROR — never use these):

• capabilities — looks valid but flagged by validator
• expertise_level — invented, not in Anthropic spec
• activation_priority — invented, not in Anthropic spec
• activation_triggers, type, category — not in spec
• allowed-tools — that's the skill-only syntax; agents use tools or disallowedTools
• disallowed-tools (kebab-case) — skill-only spelling (schema 3.7.0+); agents use camelCase disallowedTools

Body Content Guidelines:

1. Role section must set boundaries. Don't just say what the agent does — say what it does NOT do. Example: "You analyze contract clauses for risk. You do NOT provide legal advice or make recommendations — that is the recommendations agent's responsibility."

2. Process steps must be concrete. Each step should tell Claude exactly what to do, not vaguely gesture at an activity. Bad: "Analyze the document." Good: "Read the full contract. For each clause, extract: (a) the exact text, (b) the clause category from the taxonomy below, (c) a plain English summary in one sentence."

3. Output format must be machine-parseable if feeding an orchestrator. Use JSON with a concrete schema example. Include field descriptions so Claude knows what each field means.

4. Guidelines should include both DO and DON'T rules. Example:

   • DO: "Be specific — quote exact clause text, don't paraphrase"
   • DON'T: "Don't make legal recommendations — only identify and score risks"

5. Keep under 300 lines (agent body limit — prevents context bloat in subagent window). If the agent needs extensive reference material, create a companion skill with references/ directory and preload it via the skills field.

Step 4: Validate the Agent

Run validation against the documented Anthropic schema and the runtime extension allowlist:

Manual checklist:

Automated validation:

python3 ${CLAUDE_SKILL_DIR}/../skill-creator/scripts/validate-skill.py --agents-only {plugin-dir}/

Step 5: Test the Agent

Test the agent by spawning it via the Agent tool:

1. Write a test prompt that exercises the agent's core capability
2. Spawn the agent with that prompt
3. Check: Does the output match the declared Output Format?
4. Check: Does the agent stay within its declared Role boundaries?
5. Check: Does it follow the Process steps?
6. Iterate on the body content if the agent strays

Step 6: Report

Provide a summary:

• Agent name and file path
• Documented frontmatter fields used, plus any runtime extension and IS overlay fields used
• Body line count
• Sections present
• Validation result (pass/fail with specific issues)
• Test result summary

Validation Workflow

When the user wants to validate an existing agent:

1. Locate the agent .md file
2. Parse YAML frontmatter
3. Check against the documented Anthropic schema and runtime extension allowlist:
   • name present and valid (1-64 chars, kebab-case)?
   • description present and valid (20-1536 chars; concise and selection-specific)?
   • Any invalid fields? (capabilities, expertise_level, activation_priority, etc.)
   • Any skill-only fields? (allowed-tools, kebab-case disallowed-tools)
   • Plugin restrictions respected?
4. Check body content:
   • Has ## Role section?
   • Has ## Process section with numbered steps?
   • Has ## Output Format with concrete example?
   • Has ## Guidelines?
   • Under 300 lines? (agent body limit)
5. Report findings with severity (ERROR/WARNING/INFO)
6. Suggest specific fixes for each issue

Output

• Create mode: A complete agent .md file with valid frontmatter and substantive body, plus a creation report with validation status.
• Validate mode: A compliance report listing errors, warnings, and info items with specific fix recommendations for each.

Examples

Subagent for Orchestrator Skill

Input: "Create a risk assessment agent that scores contract clauses"

Output: agents/risk-assessor.md with frontmatter:

name: risk-assessor
description: "Score contract clauses for legal and financial risk on a 1-10 scale"
model: sonnet
effort: high
maxTurns: 10

Body sections: Role (risk scoring specialist, does NOT make recommendations), Inputs (contract_text, contract_type, output_path), Process (4 steps: read, categorize, score, aggregate), Output Format (JSON with clause scores and risk matrix), Guidelines (be specific, cite clause text, use 4-factor scoring methodology).

Standalone User-Facing Agent

Input: "Create a code review agent"

Output: ~/.claude/agents/code-reviewer.md with frontmatter:

name: code-reviewer
description: "Review code for bugs, performance issues, and security vulnerabilities"
effort: high

Body sections: Role (code quality specialist), Process (read code, check patterns, identify issues, suggest fixes), Output Format (markdown with severity-rated findings), Guidelines (cite line numbers, explain why not just what), Communication Style (direct, educational, actionable).

Error Handling

Resources

• Anthropic Agent Spec — documented 16-field table plus the separately labeled runtime extension
• Agent template — Skeleton with placeholders
• Frontmatter spec — Field reference (internal)
• Source of truth — Canonical spec
• Validation rules — Agent validation section