agent-creator

Files (3)

• .skillfish.json
• SKILL.md
• anthropic-agent-spec.md · references/

SKILL.md (first lines)

# 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
- **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-200 chars — shown in agent selection UI)

**Execution Context:**

- Plugin agent (`plugins/*/agents/`) or standalone (`~/.claude/agents/`)?
- Will it be spawned by an orchestrator skill via `Task` tool?
- Does it need to preload specific skills? (`skills: [skill-name]`)

**Behavioral Controls:**

- Model override? (`sonnet` for speed, `opus` for quality, `inherit` for default)
- 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`.

**Frontmatter Rules (Anthropic 16-field schema):**

See [Anthropic Agent Spec](references/anthropic-agent-spec.md) for the full official reference.

Required fields:

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

```yaml
tools: "Read, Glob, Grep"  # Allowlist — inherits all tools if omitted

From equwal/ai-config, MIT.

More from equwal/ai-config