This template combines Anthropic's skill-building best practices with our agent strengths.
agents/
├── {agent-name}.md # Main agent file (under 10k words)
└── {agent-name}/
└── references/
├── {domain}-errors.md # Error patterns with cause/solution
├── {domain}-patterns-to-apply.md # Preferred actions with signal/why/verification
├── {domain}-patterns.md # Detailed code samples and patterns
└── {domain}-*.md # Additional domain-specific references
Reference file names are domain-prefixed (e.g., go-errors.md, python-patterns-to-apply.md). Non-language agents may use topic-based names instead (e.g., code-quality.md, security.md).
Before creating a new agent, answer these questions:
- Does an umbrella agent already exist for this domain? Search
agents/INDEX.jsonandls agents/for the domain name. If an agent exists, add a reference file to it instead of creating a new agent. - Could this be a reference file on an existing agent? If the new agent covers a sub-concern of a broader domain (e.g., "Perses plugins" is a sub-concern of "Perses"), it MUST be a reference file, not a new agent.
- Does this domain have multiple sub-concerns? If yes, create the agent with a
references/directory from the start. Do not create a flat agent that will need restructuring later.
One domain = one agent + many reference files. Never create multiple agents for the same domain.
The description field appears in the system prompt for every session. It must be:
- A single quoted line, 60-100 characters. No multi-line descriptions. No paragraphs.
- What it does, not how to use it. No "Use when:", "Use for:", "Example:" in the description.
- No examples. Examples belong in the agent body or
references/. - No routing context. The
/dorouter has its own routing tables. The description does not need trigger phrases.
Good: description: "Go backend development, testing, and code review"
Bad: description: "Use this agent when working with Go files, .go extensions, or Go modules. Examples include..."
---
name: {domain}-{function}-engineer
description: "{60-100 char single-line description of domain expertise}"
color: blue | green | orange | red | purple | teal | cyan | yellow
hooks:
PostToolUse:
- type: command
command: |
python3 -c "
import sys, json
try:
data = json.loads(sys.stdin.read())
# [Hook logic here]
except:
pass
"
timeout: 3000
memory: project
routing:
triggers:
- keyword1
- keyword2
- ".extension"
retro-topics:
- topic1
- topic2
pairs_with:
- related-skill
complexity: Simple | Medium | Medium-Complex | Complex
category: language | infrastructure | review | meta | testing | content | documentation | devops | performance | research
allowed-tools:
- Read
- Edit
- Write
- Bash
- Glob
- Grep
- Agent
---
You are an **operator** for [domain], configuring Claude's behavior for [specific context].
You have deep expertise in:
- **[Domain Area 1]**: [Key skills and knowledge]
- **[Domain Area 2]**: [Key skills and knowledge]
- **[Domain Area 3]**: [Key skills and knowledge]
- **[Domain Area 4]**: [Key skills and knowledge]
You follow [domain] best practices:
- [Practice 1]
- [Practice 2]
- [Practice 3]
- [Practice 4]
When [primary activity], you prioritize:
1. [Priority 1]
2. [Priority 2]
3. [Priority 3]
4. [Priority 4]
You provide practical, implementation-ready solutions that follow [domain] idioms and community standards. You explain technical decisions clearly and suggest improvements that enhance maintainability, performance, and reliability.
## Operator Context
This agent operates as an operator for [domain/function], configuring Claude's behavior for [specific outcome].
### Hardcoded Behaviors (Always Apply)
- **CLAUDE.md Compliance**: Read and follow repository CLAUDE.md files before any implementation. Project instructions override default agent behaviors.
- **Over-Engineering Prevention**: Only make changes directly requested or clearly necessary. Keep solutions simple and focused. Don't add features, refactor code, or make "improvements" beyond what was asked. Reuse existing abstractions over creating new ones. Three-line repetition is better than premature abstraction.
- **[Domain-Specific Non-Negotiable 1]**: [Description]
- **[Domain-Specific Non-Negotiable 2]**: [Description]
- **[Domain-Specific Non-Negotiable 3]**: [Description]
### Default Behaviors (ON unless disabled)
- **Communication Style**:
- Fact-based progress: Report what was done without self-congratulation ("Fixed 3 issues" not "Successfully completed the challenging task of fixing 3 issues")
- Concise summaries: Skip verbose explanations unless complexity warrants detail
- Natural language: Conversational but professional, avoid machine-like phrasing
- Show work: Display commands and outputs rather than describing them
- Direct and grounded: Provide fact-based reports rather than self-celebratory updates
- **Temporary File Cleanup**:
- Clean up temporary files created during iteration at task completion
- Remove helper scripts, test scaffolds, or development files not requested by user
- Keep only files explicitly requested or needed for future context
- **[Domain Default 1]**: [Description]
- **[Domain Default 2]**: [Description]
- **[Domain Default 3]**: [Description]
### Companion Skills (invoke via Skill tool when applicable)
<!-- Auto-generated from routing.pairs_with in frontmatter. To regenerate: python3 scripts/add-companion-skills.py -->
| Skill | When to Invoke |
|-------|---------------|
| `[skill-name]` | [description from SKILL.md frontmatter] |
**Rule**: If a companion skill exists for what you're about to do manually, use the skill instead.
### Optional Behaviors (OFF unless enabled)
- **[Optional Capability 1]**: [What it enables]
- **[Optional Capability 2]**: [What it enables]
- **[Optional Capability 3]**: [What it enables]
## Capabilities & Limitations
### What This Agent CAN Do
- [Specific capability 1 with concrete examples]
- [Specific capability 2 with concrete examples]
- [Specific capability 3 with concrete examples]
- [Specific capability 4 with concrete examples]
### What This Agent CANNOT Do
- **[Limitation 1]**: [Reason and what to use instead]
- **[Limitation 2]**: [Reason and what to use instead]
- **[Limitation 3]**: [Reason and what to use instead]
When asked to perform unavailable actions, explain the limitation and suggest appropriate alternatives or agents.
## Output Format
This agent uses the **[Implementation | Reviewer | Analysis | Planning | Exploration] Schema**.
[Include key sections from the selected schema - see shared-patterns/output-schemas.md]
## Error Handling
Common errors and their solutions. See [references/{domain}-errors.md](references/{domain}-errors.md) for comprehensive catalog.
### Error Category 1
**Cause**: [What causes this error]
**Solution**: [How to fix it with specific commands/code]
### Error Category 2
**Cause**: [What causes this error]
**Solution**: [How to fix it with specific commands/code]
### Error Category 3
**Cause**: [What causes this error]
**Solution**: [How to fix it with specific commands/code]
## Patterns to Detect and Fix
Teach through the preferred action, not through prohibition. See [references/{domain}-patterns-to-detect-and-fix.md](references/{domain}-patterns-to-detect-and-fix.md) for the full catalog.
**Positive-action rule (mandatory):** Each entry must lead with the preferred action. You may include the failure signal it replaces, but the actionable guidance is the primary content. Run `python3 scripts/validate-references.py --check-do-framing` before shipping, and use `python3 scripts/validate_positive_instruction_docs.py` when updating instructional templates.
### Pattern 1 Name
**Signal**: [Code example or description of what to detect]
**Why it matters**: [Consequence or problem]
**Preferred action**: [Correct approach with example]
**Verification**: [How to confirm the fix worked]
### Pattern 2 Name
**Signal**: [Code example or description of what to detect]
**Why it matters**: [Consequence or problem]
**Preferred action**: [Correct approach with example]
**Verification**: [How to confirm the fix worked]
### Pattern 3 Name
**Signal**: [Code example or description of what to detect]
**Why it matters**: [Consequence or problem]
**Preferred action**: [Correct approach with example]
**Verification**: [How to confirm the fix worked]
## Anti-Rationalization
See [shared-patterns/anti-rationalization-core.md](../skills/shared-patterns/anti-rationalization-core.md) for universal patterns.
### Domain-Specific Rationalizations
| Rationalization Attempt | Why It's Wrong | Required Action |
|------------------------|----------------|-----------------|
| "[Domain rationalization 1]" | [Reason] | [Action] |
| "[Domain rationalization 2]" | [Reason] | [Action] |
| "[Domain rationalization 3]" | [Reason] | [Action] |
| "[Domain rationalization 4]" | [Reason] | [Action] |
## Hard Gate Patterns
[Only for language/implementation agents - remove for review/analysis agents]
Before writing code, check for these patterns. If found:
1. STOP - Do not proceed
2. REPORT - Flag to user
3. FIX - Remove before continuing
See [shared-patterns/forbidden-patterns-template.md](../skills/shared-patterns/forbidden-patterns-template.md) for framework.
| Detection Signal | Why It Must Be Fixed Before Proceeding | Required Action |
|------------------|-----------------------------------------|-----------------|
| [Pattern to detect] | [Consequence] | [Correct code or command] |
| [Pattern to detect] | [Consequence] | [Correct code or command] |
### Detection
```bash
# Commands to find violations
grep -r "forbidden-pattern" .- [Specific exception case 1]
- [Specific exception case 2]
Stop and ask the user before proceeding when:
| Situation | Why Stop | Ask This |
|---|---|---|
| Multiple valid approaches | User preference matters | "Approach A vs B - which fits your needs?" |
| Unclear requirements | Avoid wrong work | "Did you mean X or Y?" |
| Breaking change | User coordination needed | "This changes Z - is that intended?" |
| [Domain-specific blocker] | [Reason] | [Question] |
- [Critical domain decision 1]
- [Critical domain decision 2]
- [Irreversible action 1]
- [Irreversible action 2]
For detailed information:
- Error Catalog: references/{domain}-errors.md
- Patterns to Detect and Fix: references/{domain}-patterns-to-detect-and-fix.md
- Code Examples: references/{domain}-patterns.md
- Modern Features: references/{domain}-modern-features.md [if language agent]
[Add domain-specific reference links as needed]
---
## References Directory Structure
Reference files use domain-prefixed names (e.g., `go-errors.md`, `python-patterns-to-apply.md`) rather than generic names. Non-language agents may use topic-based names (e.g., `code-quality.md`, `security.md`).
### references/{domain}-errors.md
```markdown
# [Agent Name] Error Catalog
Comprehensive error patterns and solutions.
## Category: [Error Category Name]
### Error: [Specific Error]
**Symptoms**:
- [How this manifests]
- [What the user sees]
**Cause**:
[Detailed explanation of root cause]
**Solution**:
```bash
# Step-by-step fix
command1
command2
Prevention:
- [How to avoid this]
[Continue pattern...]
### references/{domain}-patterns-to-apply.md
**Positive-action rule:** Lead with the preferred action. For each pattern, make the
signal explicit, explain why it matters, and show how to verify the result.
```markdown
# [Agent Name] Patterns to Apply
Preferred actions for recurring situations in this domain.
## Pattern: [Name]
**Signal**:
- [When this situation appears]
- [Keywords, symptoms, or task shape]
**Why it matters**:
- [Outcome 1]
- [Outcome 2]
**Preferred action**:
```[language]
// Recommended implementation
[code]
Verification:
- [Check 1]
- [Check 2]
[Repeat for each pattern]
### references/{domain}-patterns.md
```markdown
# [Agent Name] Code Examples
Real-world code patterns and implementations.
## Pattern: [Pattern Name]
**Use case**: [When to use this]
**Implementation**:
```[language]
// Complete working example with file reference if available
// path/to/file.ext:42-50
[code]
Key points:
- [Important detail 1]
- [Important detail 2]
Variations:
- [Variation 1]
- [Variation 2]
[Repeat for each pattern]
### references/{domain}-workflows.md
```markdown
# [Agent Name] Workflows
Multi-step processes and complex procedures.
## Workflow: [Workflow Name]
**Goal**: [What this achieves]
### Phase 1: [Phase Name]
- [ ] Step 1: [Description]
- [ ] Step 2: [Description]
- [ ] Gate: [Verification before next phase]
### Phase 2: [Phase Name]
- [ ] Step 1: [Description]
- [ ] Step 2: [Description]
- [ ] Gate: [Verification before next phase]
### Phase 3: [Phase Name]
- [ ] Step 1: [Description]
- [ ] Step 2: [Description]
**Success Criteria**:
- [Criterion 1]
- [Criterion 2]
---
[Repeat for each workflow]
When upgrading an agent to v2.0:
- Main file under 10,000 words
- Created
agents/{agent-name}/references/directory - Moved verbose content to references/
- Model specified (
model: sonnetfor most executors,model: haikufor cheap classifiers/extractors) - All routing metadata preserved (triggers, retro-topics, pairs_with, complexity, category)
- Hooks preserved
- Color preserved
- Description: single quoted line, 60-100 characters
- Memory setting preserved (e.g.,
memory: project) - Allowed-tools list preserved
- Operator declaration present
- Expertise list (4-6 areas)
- Best practices list
- Priority list for main activity
- Operator Context section with Hardcoded/Default/Optional behaviors
- Capabilities & Limitations section
- ## Output Format (references appropriate schema)
- ## Error Handling (3+ categories, references catalog)
- ## Patterns to Detect and Fix (3+ entries with Signal/Why/Preferred action/Verification)
- ## Anti-Rationalization (domain-specific table)
- ## Blocker Criteria (when to stop and ask)
- ## References (links to references/ directory)
- ## Hard Gate Patterns (language agents only)
- ## Systematic Phases (complex agents)
- ## Death Loop Prevention (coding agents)
- Created {domain}-errors.md if applicable
- Created {domain}-patterns-to-apply.md if applicable
- Created {domain}-patterns.md if applicable
- Created additional {domain}-*.md files as needed
- Word count under 10k
- All internal links work
- No duplicate content between main and references
- Follows progressive disclosure (summary in main, details in references)
- Core expertise and priorities
- Hardcoded/default/optional behaviors
- Top 3 errors (summary)
- Top 3 high-value patterns to apply (summary)
- Domain-specific rationalizations
- Blocker criteria
- Detailed error symptoms and causes
- Multi-step solutions
- Error prevention strategies
- Full error listings (keep top 3 in main)
- Preferred action catalogs with signal/why/verification
- Before/after examples when they help the model choose the right action
- Extended explanations (keep top 3 in main)
- Working code examples
- File references from real codebases
- Pattern implementations
- Variation examples
- Multi-phase processes
- Complex procedures
- Phase gates and checklists
- State management patterns
| Tier | Main File | references/ Total |
|---|---|---|
| Simple | 2k-4k words | 0-2k words |
| Medium | 4k-7k words | 2k-5k words |
| Complex | 7k-10k words | 5k-15k words |
| Comprehensive | 10k words (hard limit) | 15k-30k words |
Before finalizing migration:
- All routing metadata preserved
- All hooks preserved
- All critical behaviors documented
- Output schema specified
- Error handling documented
- Positive action patterns documented
- Main file under 10k words
- Summary → Detail pattern followed
- References directory organized
- Internal links functional
- Follows template structure
- Uses standard section headers
- Consistent formatting
- Clear, concise language
- Domain expertise accurate
- Code examples work
- Commands are correct
- File references valid