agent-authoring

Reference Files

Advanced agent authoring guidance:

• design-patterns.md - Proven agent patterns with examples
• examples.md - Complete agent examples with analysis
• agent-decision-guide.md - Deciding when to use agents vs skills vs commands
• comparison-with-official.md - Comparison with Anthropic's official agents

---

About Agents

Agents are specialized AI assistants that run in separate subprocesses with focused expertise. They have:

• Specific focus areas - Clearly defined areas of expertise
• Model choice - Sonnet, Opus, or Haiku depending on complexity
• Tool restrictions - Limited to only the tools they need
• Permission modes - Control over how they interact with the system
• Isolated context - Run separately from the main conversation

When to use agents:

• Task requires specialized expertise
• Need different model than main conversation
• Want to restrict tools for security/focus
• Task benefits from isolated context
• Can be invoked automatically or manually

Core Principles

1. Clear Focus Areas

Focus areas define what the agent is expert in. They should be:

Specific, not generic:

• ❌ "Python programming"
• ✅ "FastAPI REST APIs with SQLAlchemy ORM and pytest testing"

Concrete, with examples:

• ❌ "Best practices"
• ✅ "Defensive programming with strict error handling"

5-15 focus areas that cover the agent's expertise comprehensively.

Example from evaluator agent:

## Focus Areas

- YAML Frontmatter Validation
- Markdown Structure
- Tool Permissions
- Description Quality
- File Organization
- Progressive Disclosure
- Integration Patterns

2. Model Selection (Keep It Simple)

Sonnet (default choice for most agents):

• Balanced cost and capability
• Handles most programming tasks
• Good for analysis and code generation
• Use unless you have a specific reason not to

Haiku (for simple, fast tasks):

• Fast and cheap
• Good for read-only analysis
• Simple, repetitive tasks
• When speed matters more than complexity

Opus (for complex reasoning):

• Most capable model
• Complex architectural decisions
• Requires deep reasoning
• Higher cost - use sparingly

Decision guide:

1. Start with Sonnet
2. Switch to Haiku if agent is simple read-only analyzer
3. Only use Opus if task genuinely requires highest capability

3. Tool Restrictions

Why restrict tools:

• Security - Prevent unwanted file modifications
• Focus - Agent only needs specific capabilities
• Predictability - Clear what agent can/cannot do

Common tool patterns:

Read-only analyzer:

allowed_tools:
  - Read
  - Glob
  - Grep
  - Bash

Examples: evaluator, audit-skill

Code generator/modifier:

allowed_tools:
  - Read
  - Edit
  - Write
  - Grep
  - Glob
  - Bash

Examples: test-runner

Minimal/focused:

allowed_tools:
  - Read
  - AskUserQuestion

Example: When agent only needs to read and ask questions

If unspecified: Agent inherits all tools from parent (usually not desired)

4. Permission Modes (Common Ones)

default (most common):

• Normal permission checking
• User approves tool usage as needed
• Safe default choice

acceptEdits (for editing workflows):

• Auto-approves Read and Edit operations
• Good for refactoring/cleanup agents
• Still asks for Write, Bash, etc.

plan (for planning agents):

• Agent researches and creates plan
• No execution until plan approved
• Good for complex implementation planning

Most agents use default - only use others when you have a specific workflow need.

5. Agent Hooks

Agent hooks are lifecycle hooks defined in YAML frontmatter, scoped to that specific agent.

When to use agent hooks:

• Agent needs specific validation before tool execution
• Auto-format or lint files after agent edits
• Log or notify when agent completes tasks
• Need behavior specific to one agent, not global

When to use settings.json hooks instead:

• Behavior applies to all sessions/agents
• Need events like SessionStart, SubagentStart, UserPromptSubmit
• Global validation or formatting rules

Available events:

Event	Trigger	Use Case
PreToolUse	Before agent uses tool	Validation, blocking, logging
PostToolUse	After tool completes	Formatting, notifications
Stop	Agent finishes	Cleanup, notifications

Configuration syntax:

---
name: code-reviewer
description: Review code with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
          timeout: 10
---

Key points:

• Matchers filter which tools trigger hooks ("Edit|Write", "Bash", "*")
• Stop event auto-converts to SubagentStop internally
• Hooks run with user credentials (same security model as settings.json)
• Keep hook scripts fast (<30s timeout recommended)

Agent Design Patterns

Three proven patterns for building effective agents. Each pattern includes complete templates you can copy and customize.

📄 See design-patterns.md for detailed templates

Quick overview:

1. Read-Only Analyzer - For auditing, evaluation, reporting (Haiku/Sonnet + read-only tools)
2. Code Generator/Modifier - For creating/editing code (Sonnet + Read/Edit/Write/Bash)
3. Workflow Orchestrator - For multi-step coordination (Sonnet + Task tool)

Resource Organization

File Structure

Per Claude Code specification, agents are single files only:

agents/
├── code-reviewer.md           # Single file agent
├── bash-expert.md             # Single file agent
└── security-auditor.md        # Single file agent

No subdirectories or reference files supported.

Agent vs Skill

Need	Use
Reference files / progressive disclosure	Skill
Single-file focused capability	Agent
Large documentation (>500 lines)	Skill (can split content)

If you need reference files, convert to a skill instead:

skills/evaluator/
├── SKILL.md                   # Main skill file
├── evaluation-criteria.md     # Reference file
└── examples.md                # Reference file

📄 See ~/.claude/docs/agent-vs-skill-structure.md for details

Keeping Agents Focused

Since agents must be single files:

• Keep content under 500 lines
• Focus on core workflow, not extensive examples
• Move reference material to skills if needed
• Use clear, concise sections

Agent Creation Process

Step 1: Define Purpose and Scope

Start by clarifying:

Questions to ask:

• What specific problem does this agent solve?
• What tasks should it handle?
• What tasks should it NOT handle?
• Who will use it and when?
• Does an existing agent already do this?

Use AskUserQuestion to clarify ambiguities before proceeding.

Check for existing agents:

ls -la ~/.claude/agents/

Look for similar agents that might overlap.

Step 2: Choose Model and Tools

Model selection:

1. Default to Sonnet for most agents
2. Use Haiku if it's a simple read-only analyzer
3. Only use Opus if complexity genuinely requires it

Tool selection:

1. List what the agent actually needs to do
2. Map needs to minimal tool set
3. Use restrictive set from design patterns above
4. Don't grant tools "just in case"

Permission mode:

• Default: Use default unless you have specific need
• Only specify permissionMode if you need non-default behavior

Step 3: Write Focus Areas

Guidelines:

• 5-15 specific areas of expertise
• Each should be concrete and specific
• Include technologies, frameworks, patterns
• Avoid vague statements like "best practices"

Good examples (from evaluator):

• "YAML Frontmatter Validation - Required fields, syntax correctness"
• "Tool Permissions - Appropriateness of allowed-tools, security implications"
• "Progressive Disclosure - Context economy, reference file usage"

Bad examples:

• "Writing good code" (too vague)
• "Programming" (too generic)
• "Helping with tasks" (not specific)

Step 4: Define Approach/Methodology

This section explains HOW the agent works:

Include:

• Key principles the agent follows
• Step-by-step methodology
• Decision-making frameworks
• Output format (if applicable)

Example from evaluator:

## Evaluation Framework

### Correctness Criteria

- YAML frontmatter with required fields
- Valid model value
- Name matches filename
  ...

## Evaluation Process

### Step 1: Identify Extension Type

...

### Step 2: Apply Type-Specific Validation

...

Step 5: Write Description

Requirements:

• Explain what the agent does (capabilities)
• Include when to invoke (triggering scenarios)
• Mention key technologies/focus areas
• Target 150-500 characters

Formula: [What it does] for [use cases]. Expert/Use when [triggers]. [Key features]

Good example:

description: Master of defensive Bash scripting for production automation, CI/CD pipelines, and system utilities. Expert in safe, portable, and testable shell scripts.

Bad example:

description: Helps with bash scripts

Step 6: Create the Agent File

File location: ~/.claude/agents/agent-name.md

Filename should match name in frontmatter.

Basic structure:

---
name: agent-name
description: [comprehensive description with triggers]
model: sonnet
allowed_tools:
  - Read
  - [other tools]
---

## Focus Areas

- [Specific area 1]
- [Specific area 2]
  ...

## Approach

[How the agent works, methodologies, processes]

## [Optional Additional Sections]

[Examples, best practices, output formats, etc.]

Step 7: Test the Agent

Test invocation:

1. Try invoking the agent in a conversation
2. Verify it has access to specified tools
3. Check that focus areas guide its behavior
4. Ensure description triggers correctly

Validate with /audit-agent:

/audit-agent agent-name

This will check:

• Frontmatter correctness
• Description quality
• File structure
• Best practices compliance

Agents vs Skills vs Commands

Choosing the right customization type is critical. Each has distinct characteristics and use cases.

📄 See agent-decision-guide.md for agent-specific decision framework

📄 See when-to-use-what.md for detailed decision guide (shared)

Quick guide:

• Agent - Separate subprocess, custom model, strict tools → Use for isolation and specialized tasks
• Skill - Main conversation, auto-triggers, domain knowledge → Use for extending base capabilities
• Command - User shortcut, delegates to agent/skill → Use for explicit, frequent actions

Common Mistakes to Avoid

1. Vague focus areas - "Python expert" instead of "FastAPI with SQLAlchemy and pytest"
2. Wrong model - Using Opus when Sonnet would work fine
3. Too permissive tools - Granting all tools when only Read/Grep needed
4. Missing approach section - Not explaining HOW the agent works
5. Poor description - Too short or doesn't include trigger scenarios
6. Name mismatch - Frontmatter name doesn't match filename
7. Overlapping agents - Creating agent that duplicates existing one
8. No tool restrictions - Not specifying allowed_tools (inherits all)

Examples from Existing Agents

Real-world examples showing what makes a good agent. Each example is analyzed to explain why it works well.

📄 See examples.md for detailed analysis

Examples covered:

1. evaluator - Read-only evaluator pattern
2. test-runner - Test runner with reporting pattern

Each example includes the full frontmatter, focus areas, and analysis of what makes it effective.

Tips for Success

1. Start with an existing agent as template - Copy structure from similar agent
2. Be specific in focus areas - Concrete details over generic statements
3. Test early - Create minimal agent and test before adding details
4. Use /audit-agent - Catch issues early
5. Check for overlaps - Don't duplicate existing agents
6. Document the approach - Explain HOW the agent works
7. Keep tools minimal - Only grant what's needed
8. Write good description - Include what, when, and key features
9. Iterate based on usage - Refine after real-world testing
10. Follow naming conventions - Use kebab-case, match filename to name

Reference to Standards

For detailed standards and validation:

• Naming conventions - Use kebab-case for agent names
• Frontmatter requirements - name, description, model (optional: allowed_tools, permissionMode)
• File organization - ~/.claude/agents/agent-name.md
• Validation - Use /audit-agent command

See audit-coordinator skill for comprehensive standards.

Related Skills

This skill is part of the authoring skill family:

• author-agent - Guide for creating agents (this skill)
• author-skill - Guide for creating skills
• author-command - Guide for creating commands
• author-output-style - Guide for creating output styles

For validation, use the corresponding audit skills:

• audit-agent - Validate agent configurations
• audit-coordinator - Comprehensive multi-faceted audits

Quick Start Checklist

Creating a new agent:

• Identify unique purpose (not covered by existing agents)
• Choose model (default: Sonnet)
• Determine minimal tool set needed
• Write 5-15 specific focus areas
• Document approach/methodology
• Write comprehensive description (150-500 chars)
• Create file at ~/.claude/agents/agent-name.md
• Test invocation
• Validate with /audit-agent agent-name
• Iterate based on results