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:

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/ru

...