agent-authoring

## Reference Files

Advanced agent authoring guidance:

- [design-patterns.md](design-patterns.md) - Proven agent patterns with examples
- [examples.md](examples.md) - Complete agent examples with analysis
- [agent-decision-guide.md](agent-decision-guide.md) - Deciding when to use agents vs skills vs commands
- [comparison-with-official.md](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**:

```markdown
## 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**:

```yaml
allowed_tools:
  - Read
  - Glob
  - Grep
  - Bash
```

Examples: evaluator, audit-skill

**Code generator/modifier**:

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

Examples: test-runner

**Minimal/focused**:

```yaml
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**:

```yaml
---
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](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**:

```text
agents/
├── code-reviewer.md