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

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                │
│                                                │
│  ┌──────────┐  ┌──────────────┐                │
│  │ forgejo  │  │issue-writing │                │
│  │          │  │              │                │
│  │ CLI      │  │ Structure    │                │
│  │ commands │  │ patterns     │                │
│  └──────────┘  └──────────────┘                │
│                                                │
│  ┌──────────────────┐  ┌─────────────────┐     │
│  │backlog-grooming  │  │roadmap-planning │     │
│  │                  │  │                 │     │
│  │ Review           │  │ Feature         │     │
│  │ checklists       │  │ breakdown       │     │
│  └──────────────────┘  └─────────────────┘     │
│                                                │
└────────────────────────────────────────────────┘

The agent can:

• Use forgejo 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
forgejo + issue-writing	Create well-structured issues programmatically
backlog-grooming + issue-writing	Improve existing issues systematically
roadmap-planning + forgejo	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

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 forgejo 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

- forgejo
- 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 (forgejo)
• 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" = forgejo + 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 fj 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: forgejo, 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
- forgejo
- issue-writing
- backlog-grooming
- roadmap-planning
- code-review
- testing
- documentation
- deployment

Right-sized:

## Skills
- forgejo
- 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

• File is at agents/<name>/AGENT.md
• Name follows kebab-case convention
• Agent has a clear, recognizable role
• Skills list is deliberate (not too many, not too few)
• Capabilities are specific and achievable
• "When to Use" guidance is clear
• Behavioral rules prevent problems
• 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