# Agent Creator

> Create production-grade agent .md files aligned with the current Anthropic subagent contract. 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.

- Skill: `gabrielmoreira/agent-creator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/agent-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/agent-creator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gabrielmoreira/agent-creator

---

# 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:

| Section | Purpose | Required? |
|---------|---------|-----------|
| `# Title` | Agent name as heading | Yes |
| `## Role` | 2-3 sentence domain description with boundaries | Yes |
| `## Inputs` | Parameters the agent receives when spawned | Yes (if spawned by orchestrator) |
| `## Process` | Step-by-step methodology (numbered steps with ### headings) | Yes |
| `## Output Format` | Structured output spec (JSON, markdown, or table) | Yes |
| `## Guidelines` | Do/don't behavioral rules | Yes |
| `## When Activated` | Trigger conditions (when spawned or auto-detected) | Recommended |
| `## Communication Style` | Tone and formatting preferences | Recommended |
| `## Success Criteria` | What good vs poor output looks like | Recommended |
| `## Examples` | Concrete interaction examples | For complex agents |

**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](references/anthropic-agent-spec.md) for the full official reference.

Upstream-required fields:

```yaml
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:

```yaml
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:**

| Check | Rule |
|-------|------|
| `name` present | 1-64 chars, kebab-case |
| `description` present | 20-1536 chars under the IS contract; concise and selection-specific |
| No invalid fields | None of: capabilities, expertise_level, activation_priority, type, category |
| No skill-only fields | No `allowed-tools`, no kebab-case `disallowed-tools` (agents use `tools` / camelCase `disallowedTools`) |
| Plugin restrictions | No hooks/mcpServers/permissionMode if plugin agent |
| Body has Role section | Clear domain + boundaries |
| Body has Process section | Numbered steps |
| Body has Output Format | Concrete schema example |
| Body has Guidelines | Do/don't rules |
| Body under 300 lines | Offload to references if longer (prevents context bloat) |

**Automated validation:**

```bash
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:

```yaml
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:

```yaml
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 > 1536 chars | Exceeds the IS disclosure-marker cap | Shorten below 1536 chars and keep it concise |
| 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](references/anthropic-agent-spec.md) — 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