Meta:agent Creator

Agent Creator

Quick Start

Step 1: Create the agent

# .claude/agents/my-reviewer.md

---

name: my-reviewer
description: Review code for specific patterns. Use proactively after implementing features.
tools: Read, Grep, Glob
model: haiku

---

# My Reviewer

You are a code reviewer. Check for:

- Pattern 1
- Pattern 2

## Output Format

\`\`\`markdown

## Summary

[Assessment]

## Issues

1. [Issue]: [File:line] - [Description]

## Verdict

[APPROVE / REQUEST CHANGES]
\`\`\`

Step 2: Validate (required)

Always run validation after creating or modifying an agent:

uv run .claude/skills/meta-agent-creator/scripts/validate-agent.py .claude/agents/my-reviewer.md

Fix any errors before committing.

Agent Locations

When names conflict, higher priority wins.

Managing Agents

Use /agents command for interactive agent management (view, create, edit, delete).

Built-in Agents

Explore Thoroughness Levels

Specify: quick (fast lookups), medium (balanced), or very thorough (comprehensive).

YAML Frontmatter

Required Fields

---
name: agent-name # Lowercase, hyphens
description: What this agent does. Use proactively when [triggers].
---

Optional Fields

---
name: agent-name
description: Description with triggers
tools: Read, Grep, Glob, Bash # Omit to inherit all tools
model: inherit # Use parent's model
permissionMode: default
skills: auth, database # Must explicitly list - no inheritance
---

Important: Subagents do NOT inherit skills from the parent conversation. You must explicitly list skills in the skills field.

Permission Modes

CLI-based Agents

Define agents dynamically with --agents flag:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Useful for quick testing, session-specific agents, or automation scripts.

Resumable Agents

Agents can be resumed to continue previous conversations:

> Use code-analyzer to review the auth module
[Agent completes, returns agentId: "abc123"]

> Resume agent abc123 and also check the authorization logic
[Agent continues with full previous context]

• Each execution gets a unique agentId
• Transcripts stored in agent-{agentId}.jsonl
• Use resume parameter with the agent ID to continue

Disabling Agents

Disable specific agents using permission rules:

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

Or via CLI:

claude --disallowedTools "Task(Explore)"

Model Selection Guide

Decision Tree

Is this a simple checklist task?
  → Yes: haiku
  → No: Does it require deep reasoning or security analysis?
    → Yes: sonnet
    → No: Does it involve architecture or cross-system decisions?
      → Yes: opus
      → No: sonnet

Tool Selection Guide

Common Tool Combinations

# Read-only reviewer
tools: Read, Grep, Glob

# Investigator with diagnostics
tools: Read, Grep, Glob, Bash

# Agent that can fix issues
tools: Read, Grep, Glob, Edit

# Research agent
tools: Read, Grep, Glob, WebFetch, WebSearch

Agent Templates

See reference.md for complete templates:

• Review Agent - Code review with checklist and structured output
• Investigation Agent - Debugging with systematic process
• Exploration Agent - Codebase discovery and documentation
• Security Audit Agent - Vulnerability assessment

Best Practices

1. Start with Claude-generated agents: Use /agents to generate initial agent, then customize
2. Design focused agents: One clear responsibility per agent
3. Write detailed prompts: Include instructions, examples, and constraints
4. Limit tool access: Only grant necessary tools for security and focus
5. Version control: Check project agents into git for team sharing
6. Use proactive triggers: Include "use PROACTIVELY" or "MUST BE USED" in descriptions

Common Mistakes

Validation

Run the validator to check agent structure:

uv run .claude/skills/meta-agent-creator/scripts/validate-agent.py .claude/agents/my-agent.md

Checklist

• File location: .claude/agents/<name>.md
• YAML has name, description, tools, model
• Description includes trigger phrases
• Model appropriate for task complexity
• Tools list matches actual usage
• Role description is project-specific
• Output format template included
• All code blocks have language specifiers

Delegation

• After creating/modifying agents: Run uv run .claude/skills/meta-agent-creator/scripts/validate-agent.py <agent.md>
• Pattern discovery: For existing agent patterns, use Explore agent

References

• Official Subagents Docs: code.claude.com/docs/en/sub-agents
• Existing agents: .claude/agents/code-reviewer.md, debugger.md, security-auditor.md
• Best Practices: anthropic.com/engineering/claude-code-best-practices