Add agent authoring guide
Create docs/writing-agents.md with comprehensive documentation for writing new agents: - File structure and naming conventions (agents/<name>/AGENT.md) - How agents combine multiple skills into focused personas - Use cases: parallel processing, context isolation, complex workflows, autonomous exploration - When to use agents vs direct skill invocation with decision matrix - Annotated walkthrough of product-manager agent - Best practices for skill selection, boundaries, and guardrails Closes #4 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
512
docs/writing-agents.md
Normal file
512
docs/writing-agents.md
Normal file
@@ -0,0 +1,512 @@
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
# 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.
|
||||
|
||||
```markdown
|
||||
## 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)
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```markdown
|
||||
## 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 |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Choose Skills Deliberately
|
||||
|
||||
Include only skills the agent needs. More skills = more context = potential confusion.
|
||||
|
||||
**Too many skills:**
|
||||
```markdown
|
||||
## Skills
|
||||
- forgejo
|
||||
- issue-writing
|
||||
- backlog-grooming
|
||||
- roadmap-planning
|
||||
- code-review
|
||||
- testing
|
||||
- documentation
|
||||
- deployment
|
||||
```
|
||||
|
||||
**Right-sized:**
|
||||
```markdown
|
||||
## Skills
|
||||
- forgejo
|
||||
- issue-writing
|
||||
- backlog-grooming
|
||||
- roadmap-planning
|
||||
```
|
||||
|
||||
### 2. Define Clear Boundaries
|
||||
|
||||
Agents should know what they can and cannot do.
|
||||
|
||||
**Vague:**
|
||||
```markdown
|
||||
## Capabilities
|
||||
This agent can help with project management.
|
||||
```
|
||||
|
||||
**Clear:**
|
||||
```markdown
|
||||
## 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:**
|
||||
```markdown
|
||||
# Security Agent
|
||||
|
||||
## Skills
|
||||
- issue-writing
|
||||
- documentation
|
||||
```
|
||||
|
||||
**Aligned:**
|
||||
```markdown
|
||||
# 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:**
|
||||
```markdown
|
||||
# Everything Agent
|
||||
Handles issues, code review, deployment, and customer support.
|
||||
```
|
||||
|
||||
**Focused:**
|
||||
```markdown
|
||||
# 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](../ARCHITECTURE.md): How agents fit into the overall system
|
||||
- [writing-skills.md](writing-skills.md): Creating the skills that agents use
|
||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
||||
Reference in New Issue
Block a user