# Agent Validation Checklist

Based on official Claude Code documentation: https://code.claude.com/docs/en/sub-agents

## Required

- [ ] Agent file is a `.md` file with YAML frontmatter
- [ ] Frontmatter contains `name` (unique identifier)
- [ ] Frontmatter contains `description` (when Claude should delegate to this agent)

## Recommended

- [ ] `description` is clear enough for Claude to decide when to delegate
- [ ] `model` specified appropriately:
  - `haiku` for fast, read-only tasks
  - `sonnet` for balanced tasks
  - `opus` for complex reasoning
  - `inherit` to use parent's model
- [ ] `tools` explicitly lists needed tools (principle of least privilege)
- [ ] `permissionMode` set appropriately for the agent's task

## Structure

- [ ] File located in correct directory:
  - `.claude/agents/` for project-level
  - `~/.claude/agents/` for user-level
  - `.claude/agents/{category}/` for categorized agents
- [ ] Content includes clear system prompt
- [ ] Content describes workflow/steps
- [ ] Content defines execution rules
- [ ] Content specifies output format

## Tool Access

- [ ] `tools` field only includes necessary tools
- [ ] `disallowedTools` used to explicitly block dangerous tools if needed
- [ ] MCP tools referenced correctly (mcp__{server}__{tool})

## Permission Modes

| Mode | Use Case | Risk |
|------|----------|------|
| `default` | Standard interactive work | Low |
| `acceptEdits` | Automated file modifications | Medium |
| `dontAsk` | Background tasks that should not prompt | Medium |
| `bypassPermissions` | Full automation (trusted agents only) | HIGH |
| `plan` | Read-only exploration and research | None |

## Skills Preloading

- [ ] `skills` field references existing skill names
- [ ] Referenced skills are relevant to agent's purpose
- [ ] Not overloading agent with too many preloaded skills

## Hooks (if applicable)

- [ ] Hook events are valid lifecycle events
- [ ] Hook matchers use valid regex
- [ ] Hook commands reference existing scripts
- [ ] Hooks are scoped to agent's responsibilities

## Content Quality

- [ ] System prompt is actionable (not vague)
- [ ] Workflow has numbered steps
- [ ] Execution rules define clear constraints
- [ ] Output format is specified
- [ ] Agent doesn't duplicate functionality of built-in agents

## Built-in Agents (do not recreate)

| Agent | Purpose | Model |
|-------|---------|-------|
| Explore | Fast codebase search, read-only | haiku |
| Plan | Research and design, read-only | inherit |
| general-purpose | Complex multi-step tasks | inherit |
| Bash | Command execution in separate context | inherit |

## Frontmatter Fields Reference

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | YES | - | Unique agent identifier |
| `description` | string | YES | - | When to delegate to this agent |
| `tools` | string | no | all | CSV of available tools |
| `disallowedTools` | string | no | - | CSV of blocked tools |
| `model` | string | no | inherit | haiku/sonnet/opus/inherit |
| `permissionMode` | string | no | default | Permission handling mode |
| `skills` | list | no | - | Skills to preload |
| `hooks` | object | no | - | Agent-scoped lifecycle hooks |
| `color` | string | no | - | Visual indicator color |
