Create production-grade agent .md files aligned with the Anthropic 2026 spec (16-field schema).
Also validates existing agents against the marketplace compliance rules. Use when building custom
subagents, reviewing agent quality, or creating parallel agent architectures for orchestrator skills.
Trigger with "/agent-creator", "create an agent", "build a subagent", or "validate my agent".
Make sure to use this skill whenever creating agents/*.md files for plugins or standalone use.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Create production-grade agent .md files aligned with the Anthropic 2026 spec (16-field schema).
Also validates existing agents against the marketplace compliance rules. Use when building custom
subagents, reviewing agent quality, or creating parallel agent architectures for orchestrator skills.
Trigger with "/agent-creator", "create an agent", "build a subagent", or "validate my agent".
Make sure to use this skill whenever creating agents/*.md files for plugins or standalone use.
Creates spec-compliant agent .md files following the Anthropic 2026 16-field schema. 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 enforces the Anthropic agent schema (14 valid fields), 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. 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
name: {agent-name} # Lowercase letters and hyphens, unique identifierdescription:"{specialty}"# When Claude should delegate to this subagent
Optional fields (include only what's needed):
tools:"Read, Glob, Grep"# Allowlist — inherits all tools if omitteddisallowedTools:"Write"# Denylist — removed from inherited/specified listmodel:sonnet# sonnet|haiku|opus|inherit|full model IDeffort:medium# low|medium|high|max (max = Opus 4.6 only)maxTurns:15# Max agentic turns before stoppingskills: [skill-name] # Skills to inject at startup (full content loaded)memory:project# user|project|local — persistent cross-sessionbackground:false# Always run as background taskisolation:worktree# Run in temporary git worktreecolor:blue# Display: red|blue|green|yellow|purple|orange|pink|cyaninitialPrompt:"..."# Auto-submitted first turn (--agent mode only)permissionMode:default# Standalone only, NOT plugin agentshooks: {} # Standalone only, NOT plugin agentsmcpServers: {} # Standalone only, NOT plugin agents
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
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."
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."
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.
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"
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 Anthropic 16-field schema:
Test the agent by spawning it via the Task tool or the Agent tool:
Write a test prompt that exercises the agent's core capability
Spawn the agent with that prompt
Check: Does the output match the declared Output Format?
Check: Does the agent stay within its declared Role boundaries?
Check: Does it follow the Process steps?
Iterate on the body content if the agent strays
Step 6: Report
Provide a summary:
Agent name and file path
Frontmatter field count (of 14 possible)
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:
Locate the agent .md file
Parse YAML frontmatter
Check against the 16-field Anthropic schema:
name present and valid (1-64 chars, kebab-case)?
description present and valid (20-200 chars)?
Any invalid fields? (capabilities, expertise_level, activation_priority, etc.)
Any skill-only fields? (allowed-tools, kebab-case disallowed-tools)
Plugin restrictions respected?
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)
Report findings with severity (ERROR/WARNING/INFO)
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-assessordescription:"Score contract clauses for legal and financial risk on a 1-10 scale"model:sonneteffort:highmaxTurns: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-reviewerdescription:"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
Error
Cause
Resolution
allowed-tools in agent
Used skill-only field
Replace with tools (allowlist) or disallowedTools (denylist), or remove
disallowed-tools (kebab-case) in agent
Copy-pasted from skill frontmatter
Rename to camelCase disallowedTools — the validator rejects the kebab-case spelling on agents
capabilities field
Common mistake — looks valid but isn't in Anthropic spec
Remove field entirely
expertise_level field
Invented field from community templates
Remove — express expertise in body content
Description > 200 chars
Exceeds Anthropic limit
Shorten to 20-200 char range
Description < 20 chars
Below minimum
Expand to describe agent's specific specialty
permissionMode in plugin agent
Standalone-only field used in plugin context
Remove — only valid in ~/.claude/agents/
hooks in plugin agent
Plugin agents can't have hooks
Move to plugin-level hooks/hooks.json
Body has no Process section
Agent lacks step-by-step methodology
Add numbered steps under ## Process
Body over 300 lines
Too long for agent context
Extract reference material to companion skill
Resources
Anthropic Agent Spec — Official 16-field schema from code.claude.com/docs/en/sub-agents
