Create production-grade agent .md files aligned with the Anthropic 2026
SKILL.md
Agent Creator
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 identifier
description: "{specialty}" # When Claude should delegate to this subagent
Optional fields (include only what's needed):
tools: "Read, Glob, Grep" # Allowlist — inherits all tools if omitted
disallowedTools: "Write" # Denylist — removed from inherited/specified list
model: sonnet # sonnet|haiku|opus|inherit|full model ID
effort: medium # low|medium|high|max (max = Opus 4.6 only)
maxTurns: 15 # Max agentic turns before stopping
skills: [skill-name] # Skills to inject at startup (full content loaded)
memory: project # user|project|local — persistent cross-session
background: false # Always run as background task
isolation: worktree # Run in temporary git worktree
color: blue # Display: red|blue|green|yellow|purple|orange|pink|cyan
initialPrompt: "..." # Auto-submitted first turn (--agent mode only)
permissionMode: default # Standalone only, NOT plugin agents
hooks: {} # Standalone only, NOT plugin agents
mcpServers: {} # 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-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
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
