---
name: step-03-validate
description: Validate generated agent file and display final summary
---

# Step 3: Validate Agent

## MANDATORY EXECUTION RULES:
- Validate the generated file against official conventions
- Check frontmatter completeness
- Verify tool names are valid
- Display actionable report if issues found

## YOUR TASK:
Validate the generated agent against official Claude Code conventions and display a final summary.

---

## EXECUTION SEQUENCE:

### 1. Read Generated File

```
Read: "{target_path}"
```

### 2. Validate Frontmatter

**Required fields:**
- [ ] `name` exists and is a valid identifier
- [ ] `description` exists, non-empty, actionable for Claude delegation

**Optional field validation:**
- [ ] `model` is valid: haiku, sonnet, opus, inherit (or absent)
- [ ] `tools` references valid tool names (see tools-reference.md)
- [ ] `disallowedTools` references valid tool names
- [ ] `permissionMode` is valid: default, acceptEdits, dontAsk, bypassPermissions, plan
- [ ] `skills` references existing skill names
- [ ] `color` is a valid color name (if present)

**Valid tool names:**
```
Read, Write, Edit, Bash, Glob, Grep, Task, WebFetch, WebSearch,
NotebookEdit, AskUserQuestion, TodoWrite, Skill, ToolSearch,
mcp__* (any MCP tool)
```

### 3. Validate Content

- [ ] Has workflow or instructions section
- [ ] Workflow has numbered steps
- [ ] Has execution rules
- [ ] Has output format specification
- [ ] Content is not empty (> 5 lines of non-frontmatter content)
- [ ] No unreplaced placeholder text

### 4. Check Consistency

- [ ] If `permissionMode: plan` → tools should be read-only (warn if Write/Edit/Bash included)
- [ ] If `model: haiku` → agent should be designed for simple/fast tasks (info)
- [ ] If `skills` field present → referenced skills exist in scope
- [ ] Description matches the agent's actual capabilities (tools + content)

### 5. Check Against Built-in Agents

Verify the agent doesn't duplicate a built-in agent:

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

If the new agent overlaps significantly with a built-in, display a warning:
```
WARN: This agent's purpose overlaps with the built-in '{name}' agent.
Consider using the built-in agent instead, or ensure this agent adds
unique value (specialized prompts, restricted tools, preloaded skills).
```

### 6. Display Validation Report

```
Agent Validation Report:

| Check | Status |
|-------|--------|
| Frontmatter complete | PASS/FAIL |
| Tool names valid | PASS/FAIL |
| Permission mode valid | PASS/FAIL |
| Content quality | PASS/WARN |
| No built-in overlap | PASS/WARN |
| Skills references | PASS/WARN/N/A |

{If any FAIL: show specific issues and recommendations}
```

### 7. Display Final Summary

```
Agent Created Successfully!

| Property | Value |
|----------|-------|
| Name | {agent_name} |
| Location | {target_path} |
| Model | {model} |
| Tools | {tools} |
| Permission mode | {permission_mode} |
| Skills | {preloaded_skills} |

Usage:
  In Task tool: subagent_type="{agent_name}"
  In skill frontmatter: agent: "{agent_name}"
  In agent frontmatter: (reference by name)

Next steps:
- Test the agent via Task tool
- Reference it in a skill with `context: fork` and `agent: {agent_name}`
- Run audit: /cc-audit
```

---

## SUCCESS METRICS:
- All validations pass (or issues clearly reported)
- Final summary displayed with usage instructions
- Agent is ready to use
- No built-in overlap warnings (or acknowledged)
