architecture/docs/writing-agents.md

Writing Agents

A guide to creating specialized subagents that combine multiple skills for complex, context-isolated tasks.

What is an Agent?

Agents are specialized subprocesses that combine multiple skills into focused personas. Unlike commands (which define workflows) or skills (which encode knowledge), agents are autonomous workers that can handle complex tasks independently.

Think of agents as specialists you can delegate work to. They have their own context, their own expertise (via skills), and they report back when finished.

File Structure

Agents live in the agents/ directory, each in its own folder:

agents/
└── product-manager/
    └── AGENT.md

Why AGENT.md?

The uppercase AGENT.md filename:

• Makes the agent file immediately visible in directory listings
• Follows a consistent convention across all agents
• Clearly identifies the primary file in an agent folder

Supporting Files (Optional)

An agent folder can contain additional files if needed:

agents/
└── code-reviewer/
    ├── AGENT.md           # Main agent document (required)
    └── checklists/        # Supporting materials
        └── security.md

However, prefer keeping everything in AGENT.md when possible—agent definitions should be concise.

Agent Document Structure

A well-structured AGENT.md follows this pattern:

# Agent Name

Brief description of what this agent does.

## Skills
List of skills this agent has access to.

## Capabilities
What the agent can do—its areas of competence.

## When to Use
Guidance on when to spawn this agent.

## Behavior
How the agent should operate—rules and constraints.

All sections are important:

• Skills: Defines what knowledge the agent has
• Capabilities: Tells spawners what to expect
• When to Use: Prevents misuse and guides selection
• Behavior: Sets expectations for operation

YAML Frontmatter

Agent files support YAML frontmatter for configuration. While the body content defines the agent's personality and instructions, frontmatter controls its technical behavior.

Required Fields

Field	Description
name	Agent identifier (lowercase, hyphens). Should match directory name.
description	What the agent does. Used for matching when spawning agents.

Optional Fields

Field	Description
model	Model to use: haiku, sonnet, opus, or inherit (default).
skills	Comma-separated list of skills the agent can access.
disallowedTools	Explicitly block specific tools from this agent.
permissionMode	Permission behavior: default, bypassPermissions, or custom.
hooks	Define PreToolUse, PostToolUse, or Stop hooks scoped to this agent.

Example Frontmatter

Basic agent:

---
name: code-reviewer
description: Review code for quality, bugs, and style issues.
model: sonnet
skills: gitea, code-review
---

Agent with tool restrictions:

---
name: read-only-analyst
description: Analyze code without making changes.
model: haiku
skills: code-review
disallowedTools:
  - Edit
  - Write
  - Bash
---

Agent with hooks:

---
name: database-admin
description: Manage database operations safely.
model: opus
hooks:
  - type: PreToolUse
    matcher: Bash
    command: echo "Validating database command..."
  - type: Stop
    command: echo "Database operation completed"
---

Permission Modes

The permissionMode field controls how the agent handles tool permissions:

Mode	Behavior
default	Inherits parent's permission settings (standard behavior)
bypassPermissions	Skip permission prompts (use for trusted, well-tested agents)

Use bypassPermissions sparingly—only for agents that are thoroughly tested and operate within safe boundaries.

Built-in Agents

Claude Code provides built-in agents that you can leverage instead of creating custom ones:

Agent	Purpose	When to Use
Explore	Codebase exploration and search	Finding files, understanding structure, searching code. Powered by Haiku for efficiency.
Plan	Implementation planning	Designing approaches, breaking down tasks, architectural decisions.

Consider using built-in agents before creating custom ones—they're optimized for common tasks.

How Agents Combine Skills

Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.

Skill Composition

┌────────────────────────────────────────────────┐
│           Product Manager Agent                │
│                                                │
│  ┌──────────┐  ┌──────────────┐                │
│  │ gitea  │  │issue-writing │                │
│  │          │  │              │                │
│  │ CLI      │  │ Structure    │                │
│  │ commands │  │ patterns     │                │
│  └──────────┘  └──────────────┘                │
│                                                │
│  ┌──────────────────┐  ┌─────────────────┐     │
│  │backlog-grooming  │  │roadmap-planning │     │
│  │                  │  │                 │     │
│  │ Review           │  │ Feature         │     │
│  │ checklists       │  │ breakdown       │     │
│  └──────────────────┘  └─────────────────┘     │
│                                                │
└────────────────────────────────────────────────┘

The agent can:

• Use gitea to interact with issues and PRs
• Apply issue-writing patterns when creating content
• Follow backlog-grooming checklists when reviewing
• Use roadmap-planning strategies when breaking down features

Emergent Capabilities

When skills combine, new capabilities emerge:

Skills Combined	Emergent Capability
gitea + issue-writing	Create well-structured issues programmatically
backlog-grooming + issue-writing	Improve existing issues systematically
roadmap-planning + gitea	Plan and create linked issue hierarchies
All four skills	Full backlog management lifecycle

Use Cases for Agents

1. Parallel Processing

Agents work independently with their own context. Spawn multiple agents to work on separate tasks simultaneously.

Command: /groom (batch mode)
         │
         ├─── Spawn Agent: Review issues #1-5
         │
         ├─── Spawn Agent: Review issues #6-10
         │
         └─── Spawn Agent: Review issues #11-15

         ↓ (agents work in parallel)

Results aggregated by command

Use when:

• Tasks are independent and don't need to share state
• Workload can be divided into discrete chunks
• Speed matters more than sequential consistency

2. Context Isolation

Each agent maintains separate conversation state. This prevents context pollution when handling complex, unrelated subtasks.

Main Context                    Agent Context
┌─────────────────┐            ┌─────────────────┐
│ User working on │            │ Isolated work   │
│ feature X       │   spawn    │ on backlog      │
│                 │ ─────────► │ review          │
│ (preserves      │            │                 │
│  feature X      │   return   │ (doesn't know   │
│  context)       │ ◄───────── │  about X)       │
└─────────────────┘            └─────────────────┘

Use when:

• Subtask requires deep exploration that would pollute main context
• Work involves many files or concepts unrelated to main task
• You want clean separation between different concerns

3. Complex Workflows

Some workflows are better handled by a specialized agent than by inline execution. Agents can make decisions, iterate, and adapt.

Command: /plan-issues "add user authentication"
         │
         └─── Spawn product-manager agent
                   │
                   ├── Explore codebase to understand structure
                   ├── Research authentication patterns
                   ├── Design issue breakdown
                   ├── Create issues in dependency order
                   └── Return summary to command

Use when:

• Task requires iterative decision-making
• Workflow has many steps that depend on intermediate results
• Specialist expertise (via combined skills) adds value

4. Autonomous Exploration

Agents can explore codebases independently, building understanding without polluting the main conversation.

Use when:

• You need to understand a new part of the codebase
• Exploration might involve many file reads and searches
• Results should be summarized, not shown in full

5. Background Execution

Agents can run in the background while you continue working. Background agents execute asynchronously and notify the main thread when complete.

User working                    Background Agent
┌─────────────────┐            ┌─────────────────┐
│ Continue coding │            │ Running tests   │
│ on feature      │            │ in background   │
│                 │            │                 │
│ (not blocked)   │   notify   │ (async work)    │
│                 │ ◄───────── │                 │
└─────────────────┘            └─────────────────┘

Use when:

• Task is long-running (test suites, large codebase analysis)
• You want to continue working while the agent operates
• Results are needed later, not immediately

Background agents can send messages to wake up the main agent when they have results or need attention.

When to Use an Agent vs Direct Skill Invocation

Use Direct Skill Invocation When:

• Simple, single-skill task: Writing one issue doesn't need an agent
• Main context is relevant: The current conversation context helps
• Quick reference needed: Just need to check a pattern or command
• Sequential workflow: Command can orchestrate step-by-step

Example: Creating a single issue with /create-issue

Command reads issue-writing skill directly
         │
         └── Creates one issue following patterns

Use an Agent When:

• Multiple skills needed together: Complex tasks benefit from composition
• Context isolation required: Don't want to pollute main conversation
• Parallel execution possible: Can divide and conquer
• Autonomous exploration needed: Agent can figure things out independently
• Specialist persona helps: "Product manager" framing improves outputs

Example: Grooming entire backlog with /groom

Command spawns product-manager agent
         │
         └── Agent iterates through all issues
             using multiple skills

Decision Matrix

Scenario	Agent?	Reason
Create one issue	No	Single skill, simple task
Review 20 issues	Yes	Batch processing, isolation
Quick CLI lookup	No	Just need gitea reference
Plan new feature	Yes	Multiple skills, exploration
Fix issue title	No	Trivial edit
Reorganize backlog	Yes	Complex, multi-skill workflow

Annotated Example: Product Manager Agent

Let's examine the product-manager agent in detail:

# Product Manager Agent

Specialized agent for backlog management and roadmap planning.

The opening identifies the agent's role clearly. "Product Manager" is a recognizable persona that sets expectations.

## Skills

- gitea
- issue-writing
- backlog-grooming
- roadmap-planning

Skills section lists all knowledge the agent has access to. These skills are loaded into the agent's context when spawned. The combination enables:

• Reading/writing issues (gitea)
• Creating quality content (issue-writing)
• Evaluating existing issues (backlog-grooming)
• Planning work strategically (roadmap-planning)

## Capabilities

This agent can:
- Review and improve existing issues
- Create new well-structured issues
- Analyze the backlog for gaps and priorities
- Plan feature breakdowns
- Maintain roadmap clarity

Capabilities section tells spawners what to expect. Each capability maps to skill combinations:

• "Review and improve" = backlog-grooming + issue-writing
• "Create new issues" = gitea + issue-writing
• "Analyze backlog" = backlog-grooming + roadmap-planning
• "Plan breakdowns" = roadmap-planning + issue-writing

## When to Use

Spawn this agent for:
- Batch operations on multiple issues
- Comprehensive backlog reviews
- Feature planning that requires codebase exploration
- Complex issue creation with dependencies

When to Use section guides appropriate usage. Note the criteria:

• "Batch operations" → Parallel/isolation benefit
• "Comprehensive reviews" → Complex workflow benefit
• "Requires exploration" → Context isolation benefit
• "Complex with dependencies" → Multi-skill benefit

## Behavior

- Always fetches current issue state before making changes
- Asks for approval before creating or modifying issues
- Provides clear summaries of actions taken
- Uses the tea CLI for all Forgejo operations

Behavior section sets operational rules. These ensure:

• Accuracy: Fetches current state, doesn't assume
• Safety: Asks before acting
• Transparency: Summarizes what happened
• Consistency: Uses standard tooling

Naming Conventions

Agent Folder Names

• Use kebab-case: product-manager, code-reviewer
• Name by role or persona: what the agent "is"
• Keep recognizable: familiar roles are easier to understand

Good names:

• product-manager - Recognizable role
• code-reviewer - Clear function
• security-auditor - Specific expertise
• documentation-writer - Focused purpose

Avoid:

• helper - Too vague
• do-stuff - Not a role
• issue-thing - Not recognizable

Agent Titles

The H1 title in AGENT.md should be the role name in Title Case:

Folder	Title
product-manager	Product Manager Agent
code-reviewer	Code Reviewer Agent
security-auditor	Security Auditor Agent

Model Selection

Agents can specify which Claude model to use via the model field in YAML frontmatter. Choosing the right model balances capability, speed, and cost.

Available Models

Model	Characteristics	Best For
haiku	Fastest, most cost-effective	Simple structured tasks, formatting, basic transformations
sonnet	Balanced speed and capability	Most agent tasks, code review, issue management
opus	Most capable, best reasoning	Complex analysis, architectural decisions, nuanced judgment
inherit	Uses parent context's model	When agent should match caller's capability level

Decision Matrix

Agent Task Type	Recommended Model	Reasoning
Structured output formatting	haiku	Pattern-following, no complex reasoning
Code review (style/conventions)	sonnet	Needs code understanding, not deep analysis
Security vulnerability analysis	opus	Requires nuanced judgment, high stakes
Issue triage and labeling	haiku or sonnet	Mostly classification tasks
Feature planning and breakdown	sonnet or opus	Needs strategic thinking
Batch processing (many items)	haiku or sonnet	Speed and cost matter at scale
Architectural exploration	opus	Complex reasoning about tradeoffs

Examples

These examples show recommended model configurations for different agent types:

Code Reviewer Agent - Use sonnet:

---
name: code-reviewer
model: sonnet
skills: gitea, code-review
---

Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.

Security Auditor Agent (hypothetical) - Use opus:

---
name: security-auditor
model: opus
skills: code-review  # would add security-specific skills
---

Security analysis requires careful, nuanced judgment where missing issues have real consequences. Worth the extra capability.

Formatting Agent (hypothetical) - Use haiku:

---
name: markdown-formatter
model: haiku
skills: documentation
---

Pure formatting tasks follow patterns and don't require complex reasoning. Haiku is fast and sufficient.

Best Practices for Model Selection

1. Start with sonnet - It handles most agent tasks well
2. Use haiku for volume - When processing many items, speed and cost add up
3. Reserve opus for judgment - Use when errors are costly or reasoning is complex
4. Avoid inherit by default - Make a deliberate choice; inherit obscures the decision
5. Consider the stakes - Higher consequence tasks warrant more capable models
6. Test with real tasks - Verify the chosen model performs adequately

When to Use inherit

The inherit option has legitimate uses:

• Utility agents: Small helpers that should match their caller's capability
• Delegation chains: When an agent spawns sub-agents that should stay consistent
• Testing/development: When you want to control model from the top level

However, most production agents should specify an explicit model.

Best Practices

1. Choose Skills Deliberately

Include only skills the agent needs. More skills = more context = potential confusion.

Too many skills:

## Skills
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
- code-review
- testing
- documentation
- deployment

Right-sized:

## Skills
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning

2. Define Clear Boundaries

Agents should know what they can and cannot do.

Vague:

## Capabilities
This agent can help with project management.

Clear:

## Capabilities
This agent can:
- Review and improve existing issues
- Create new well-structured issues
- Analyze the backlog for gaps

This agent cannot:
- Merge pull requests
- Deploy code
- Make architectural decisions

3. Set Behavioral Guardrails

Prevent agents from causing problems by setting explicit rules.

Important behaviors to specify:

• When to ask for approval
• What to do before making changes
• How to report results
• Error handling expectations

4. Match Persona to Purpose

The agent's name and description should align with its skills and capabilities.

Mismatched:

# Security Agent

## Skills
- issue-writing
- documentation

Aligned:

# Security Auditor Agent

## Skills
- security-scanning
- vulnerability-assessment
- code-review

5. Keep Agents Focused

One agent = one role. If an agent does too many unrelated things, split it.

Too broad:

# Everything Agent
Handles issues, code review, deployment, and customer support.

Focused:

# Product Manager Agent
Specialized for backlog management and roadmap planning.

When to Create a New Agent

Create an agent when you need:

1. Role-based expertise: A recognizable persona improves outputs
2. Skill composition: Multiple skills work better together
3. Context isolation: Work shouldn't pollute main conversation
4. Parallel capability: Tasks can run independently
5. Autonomous operation: Agent should figure things out on its own

Signs You Need a New Agent

• Commands repeatedly spawn similar skill combinations
• Tasks require deep exploration that pollutes context
• Work benefits from a specialist "persona"
• Batch processing would help

Signs You Don't Need a New Agent

• Single skill is sufficient
• Task is simple and sequential
• Main context is helpful, not harmful
• No clear persona or role emerges

Agent Lifecycle

1. Design

Define the agent's role:

• What persona makes sense?
• Which skills does it need?
• What can it do (and not do)?
• When should it be spawned?

2. Implement

Create the agent file:

• Clear name and description
• Appropriate skill list
• Specific capabilities
• Usage guidance
• Behavioral rules

3. Integrate

Connect the agent to workflows:

• Update commands that should spawn it
• Document in ARCHITECTURE.md
• Test with real tasks

4. Refine

Improve based on usage:

• Add/remove skills as needed
• Clarify capabilities
• Strengthen behavioral rules
• Update documentation

Checklist: Before Submitting a New Agent

Structure

• File is at agents/<name>/AGENT.md
• Name follows kebab-case convention
• Agent has a clear, recognizable role

Frontmatter

• name and description fields are set
• model selection is deliberate (not just inherit by default)
• skills list is deliberate (not too many, not too few)
• Consider disallowedTools if agent should be restricted
• Consider permissionMode for trusted agents
• Consider hooks for validation or logging

Content

• Capabilities are specific and achievable
• "When to Use" guidance is clear
• Behavioral rules prevent problems

Integration

• Consider if built-in agents (Explore, Plan) could be used instead
• Agent is referenced by at least one command
• ARCHITECTURE.md is updated

See Also

• ARCHITECTURE.md: How agents fit into the overall system
• writing-skills.md: Creating the skills that agents use
• VISION.md: The philosophy behind composable components