Menu
AI agent development standards including frontmatter structure, naming conventions, tool access patterns, model selection, and reference documentation structure
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Comprehensive project planning standards for plans/ directory including folder structure (ideas/, backlog/, in-progress/, done/), stage-aware naming convention (done uses YYYY-MM-DD__identifier/; backlog and in-progress use identifier/ with no date prefix), five-document file organization (README.md, brd.md, prd.md, tech-docs.md, delivery.md for multi-file default; single README.md for trivially-small single-file exception), BRD/PRD content-placement rules, Gherkin acceptance criteria, and the mandatory structured multiple-choice grilling gates (pre-write and post-write) for resolving design decisions with the user. Essential for creating structured, executable project plans.
Trunk Based Development workflow - all development on main branch with small frequent commits, minimal branching, and continuous integration. Covers when branches are justified (exceptional cases only), commit patterns, feature flag usage for incomplete work, environment branch rules (deployment only), and AI agent default behavior (the repo-wide default delivery mode is `worktree-to-pr` -- a short-lived plan branch in a disposable worktree pushed to a draft PR; direct push to main remains available as an explicit selection). Essential for understanding repository git workflow and keeping branches short-lived
Workflow pattern standards for creating multi-agent orchestrations including YAML frontmatter (name, description, tags, status, agents, parameters), execution phases (sequential/parallel/conditional), agent coordination patterns, and Gherkin success criteria. Essential for defining reusable, validated workflow processes.
Common software development workflow patterns shared across all language developer agents
Three-stage content quality workflow pattern (Maker creates, Checker validates, Fixer remediates) with detailed execution workflows. Use when working with content quality workflows, validation processes, audit reports, or implementing maker/checker/fixer agent roles.
Universal methodology for verifying factual correctness in documentation using WebSearch and WebFetch tools. Covers command syntax verification, version checking, code example validation, API correctness, confidence classification system ([Verified], [Error], [Outdated], [Unverified]), source prioritization, and update frequency rules. Essential for maintaining factual accuracy in technical documentation and educational content
| name | agent-developing-agents |
| description | AI agent development standards including frontmatter structure, naming conventions, tool access patterns, model selection, and reference documentation structure |
Comprehensive guidance for creating AI agents following repository conventions.
Use the normal Write / Edit tools to create and modify files under .claude/ and .opencode/. Both paths are pre-authorized in .claude/settings.json (Write(.claude/**), Edit(.claude/**), Write(.opencode/**), Edit(.opencode/**)), so no approval prompts fire. Bash heredoc and sed remain appropriate for bulk mechanical substitutions across many files, but there is no restriction on direct edits.
This applies to:
.claude/agents/*.md — agent definitions.claude/skills/*/SKILL.md — skill files.claude/skills/*/reference/*.md — skill reference modules.opencode/agents/*.md — OpenCode agent mirrors.opencode/skills/*/SKILL.md — Nx/OpenCode-native skill files (not mirrored from .claude/skills/; OpenCode reads .claude/skills/ natively)After editing .claude/ sources, run npm run generate:bindings so the .opencode/ mirrors stay aligned. The pre-commit hook validates both formats.
Those regenerated mirrors are part of your change: they belong on your touched-file ledger and MUST land in the same commit as the .claude/ source that produced them, never a follow-up sync commit. Verify with npm run validate:sync; never hand-edit a mirror. See File-Touch Discipline.
Agents should document which tools they use and why, helping users understand capabilities and maintainers understand dependencies.
Add "Tools Usage" section (optional but recommended) listing each tool with its purpose:
## Tools Usage
- **Read**: Read files to validate/create/fix
- **Glob**: Find files by pattern in directories
- **Grep**: Extract content patterns (code blocks, commands, etc.)
- **Write**: Create/update files and reports
- **Bash**: Generate UUIDs, timestamps, file operations
- **Edit**: Apply fixes to existing files
- **WebFetch**: Access official documentation URLs
- **WebSearch**: Find authoritative sources, verify claims
Recommended for:
Optional for:
Checker Agents (Read, Glob, Grep, Write, Bash, WebFetch, WebSearch):
## Tools Usage
- **Read**: Read documentation files to validate
- **Glob**: Find markdown files in directories
- **Grep**: Extract code blocks, commands, version numbers
- **Write**: Generate audit reports to generated-reports/
- **Bash**: Generate UUIDs, timestamps for reports
- **WebFetch**: Access official documentation URLs
- **WebSearch**: Find versions, verify tools, fallback for 403s
Fixer Agents (Read, Edit, Bash, Write):
## Tools Usage
- **Read**: Read audit reports and files to fix
- **Edit**: Apply fixes to docs/, repo-governance/, `.claude/`, and `.opencode/` files
- **Bash**: Run shell commands, bulk sed substitutions across many files, timestamp/UUID generation
- **Write**: Generate fix reports to generated-reports/
Maker Agents (Read, Write, Glob, Grep, Bash):
## Tools Usage
- **Read**: Read existing files for context
- **Write**: Create new documentation, agent, and skill files (including under `.claude/` and `.opencode/`)
- **Glob**: Find related files for cross-references
- **Grep**: Extract patterns for consistency
- **Bash**: Run shell commands, bulk text substitutions, directory creation
Add "Tools Usage" section:
Agents should include guidance on when to use them vs other agents, improving discoverability and preventing misuse.
Add "When to Use This Agent" section with two subsections:
## When to Use This Agent
**Use when**:
- [Primary use case 1]
- [Primary use case 2]
- [Primary use case 3]
- [Specific scenario that fits]
**Do NOT use for**:
- [Anti-pattern 1] (use [other-agent] instead)
- [Anti-pattern 2] (use [alternative-tool/approach])
- [Edge case that doesn't fit]
- [Common misuse scenario]
Highly Recommended for:
Examples by Agent Type:
Checker Agents:
## When to Use This Agent
**Use when**:
- Validating [domain] content before release
- Checking [domain] after updates
- Reviewing community contributions
- Auditing [domain] for compliance
**Do NOT use for**:
- Link checking (use [link-checker] instead)
- File naming/structure (use [rules-checker])
- Creating new content (use [maker-agent])
- Fixing issues (use [fixer-agent] after review)
Fixer Agents:
## When to Use This Agent
**Use when**:
- After running [checker-agent] - You have an audit report
- Issues found and reviewed - You've reviewed checker's findings
- Automated fixing needed - You want validated issues fixed
- Safety is critical - You need re-validation before changes
**Do NOT use for**:
- Initial validation (use [checker-agent])
- Content creation (use [maker-agent])
- Manual fixes (use Edit tool directly)
- When no audit report exists
Maker Agents:
## When to Use This Agent
**Use when**:
- Creating new [domain] content
- Need standardized structure/format
- Following [domain] conventions
- Building content from templates
**Do NOT use for**:
- Validating existing content (use [checker-agent])
- Fixing issues (use [fixer-agent])
- Bulk updates (use Edit tool for simple changes)
- Content outside [domain] scope
Add "When to Use This Agent" section:
✅ Improves agent discoverability ✅ Prevents misuse and confusion ✅ Clarifies agent boundaries ✅ Guides users to appropriate alternatives ✅ Reduces trial-and-error
AI Agents Convention - Complete specification Agent Documenting References Skill Agent Selecting Models Skill
Standard structure for "Reference Documentation" sections in agent files to ensure consistent navigation and discoverability.
This Skill auto-loads when implementing agents or updating agent documentation sections.
All agents SHOULD include a "Reference Documentation" section near the end (before any appendices) with standardized subsections.
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance for OpenCode
- [Agent-specific convention](path/to/convention.md) - Domain-specific standards
**Related Agents**:
- `maker-agent` - Creates content for this domain
- `checker-agent` - Validates content (upstream dependency)
- `fixer-agent` - Fixes issues found by checker
- `related-domain-agent` - Related functionality
**Related Conventions**:
- [Primary Convention](path/to/convention.md) - Main standards this agent implements
- [Secondary Convention](path/to/convention.md) - Additional relevant standards
**Skills**:
- `primary-skill` - Main Skill for domain knowledge
- `wow-assessing-criticality-confidence` - Criticality assessment (if applicable)
- `wow-generating-validation-reports` - Report generation (if applicable)
Purpose: Link to primary project instructions and domain-specific conventions.
Always Include:
Conditionally Include:
Pattern:
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [Specific Convention](path/to/convention.md) - Domain standards
Purpose: Help users understand agent ecosystem and workflow relationships.
Include:
Organize by Relationship:
**Related Agents**:
- `upstream-agent` - Description of relationship
- `downstream-agent` - Description of relationship
- `parallel-agent` - Description of functionality
Examples by Agent Type:
Maker Agents:
- `checker-agent` - Validates content created by this maker
- `related-maker` - Creates content in related domain
Checker Agents:
- `maker-agent` - Creates content this checker validates
- `fixer-agent` - Fixes issues found by this checker
- `related-checker` - Validates related aspects
Fixer Agents:
- `checker-agent` - Generates audit reports this fixer processes
- `maker-agent` - Updates content after fixes applied
Purpose: Link to conventions and development practices the agent implements.
Include:
Pattern:
**Related Conventions**:
- [Primary Convention](path/to/convention.md) - Main standards
- [Secondary Convention](path/to/convention.md) - Additional standards
- [Development Practice](path/to/practice.md) - Implementation guidance
Checkers Should List:
Makers Should List:
Purpose: Reference Skills the agent uses for domain knowledge and patterns.
Include:
skills: frontmatter fieldPattern:
**Skills**:
- `domain-skill` - Domain-specific knowledge
- `wow-skill` - Cross-cutting pattern or workflow
- `agent-skill` - Agent development guidance
Note: Skills section duplicates frontmatter skills: field for documentation visibility.
Recommended Location: Near end of agent file, before any appendices or examples.
Typical Structure:
# Agent Name
## Agent Metadata
- **Role**: [Maker (blue) / Checker (green) / Fixer (yellow) / Implementor (purple)]
[Agent description]
## Core Responsibility
[What agent does]
## Main Content Sections
[Detailed agent instructions]
## Reference Documentation
[Reference sections using template above]
## Appendices (Optional)
[Additional examples, edge cases, etc.]
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [Content Quality Principles](../../../repo-governance/conventions/writing/quality.md)
- [Diátaxis Framework](../../../repo-governance/conventions/structure/diataxis-framework.md)
**Related Agents**:
- `docs-maker` - Creates documentation
- `docs-checker` - Validates documentation
- `docs-fixer` - Fixes documentation issues
- `docs-tutorial-checker` - Specialized tutorial validation
**Related Conventions**:
- [Content Quality Principles](../../../repo-governance/conventions/writing/quality.md)
- [Factual Validation Convention](../../../repo-governance/conventions/writing/factual-validation.md)
- [Linking Convention](../../../repo-governance/conventions/formatting/linking.md)
**Skills**:
- `docs-applying-content-quality` - Content quality standards
- `docs-validating-factual-accuracy` - Fact-checking methodology
- `wow-assessing-criticality-confidence` - Criticality assessment
- `wow-generating-validation-reports` - Report generation
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [README Quality Convention](../../../repo-governance/conventions/writing/readme-quality.md)
**Related Agents**:
- `readme-maker` - Creates README content
- `readme-checker` - Validates README quality
- `readme-fixer` - Fixes README issues
- `docs-checker` - Validates other documentation
**Related Conventions**:
- [README Quality Convention](../../../repo-governance/conventions/writing/readme-quality.md)
- [Content Quality Principles](../../../repo-governance/conventions/writing/quality.md)
**Skills**:
- `readme-writing-readme-files` - README-specific standards
- `wow-assessing-criticality-confidence` - Criticality assessment
- `wow-generating-validation-reports` - Report generation
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [Plans Organization Convention](../../../repo-governance/conventions/structure/plans.md)
**Related Agents**:
- `plan-maker` - Creates project plans
- `plan-checker` - Validates plan quality
- [plan-execution workflow](../../../repo-governance/workflows/plan/plan-execution.md) - Execute plans (calling context orchestrates; no dedicated subagent)
- `plan-execution-checker` - Validates completed work
- `plan-fixer` - Fixes plan issues
**Related Conventions**:
- [Plans Organization Convention](../../../repo-governance/conventions/structure/plans.md)
- [Gherkin Acceptance Criteria](../../../repo-governance/development/infra/acceptance-criteria.md)
**Skills**:
- `plan-creating-project-plans` - Plan structure and organization
- `plan-writing-gherkin-criteria` - Acceptance criteria patterns
- `wow-assessing-criticality-confidence` - Criticality assessment
✅ Improved Discoverability: Users can quickly find related agents and conventions
✅ Consistent Navigation: Same structure across all agents
✅ Clear Relationships: Understand agent dependencies and workflows
✅ Better Maintainability: Easy to update references across agents
✅ Enhanced Documentation: Skills and conventions properly referenced
skills: fieldskills: fieldThis standardization improves agent documentation consistency and helps users navigate the agent ecosystem effectively.
Guidelines for choosing between sonnet and haiku models based on agent capabilities and task requirements.
This Skill auto-loads when implementing agents or documenting model selection rationale.
Characteristics:
Use for: Complex, reasoning-intensive tasks
Characteristics:
Use for: Simple, well-defined tasks
✅ Advanced Reasoning
✅ Complex Pattern Recognition
✅ Sophisticated Analysis
✅ Multi-Step Orchestration
✅ Deep Web Research
✅ Pattern Matching
✅ Sequential Execution
✅ Straightforward Validation
.md)✅ No Complex Reasoning
✅ High-Volume Processing
| Task Type | Complexity | Reasoning Required | Recommended Model |
|---|---|---|---|
| Content creation | High | Yes (narrative, structure) | Sonnet |
| Factual validation | High | Yes (source evaluation) | Sonnet |
| Quality assessment | High | Yes (subjective judgment) | Sonnet |
| Fix application | Medium-High | Yes (confidence assessment) | Sonnet |
| Link checking | Low | No (exists/accessible) | Haiku |
| File operations | Low | No (read/write/move) | Haiku |
| Pattern extraction | Low | No (regex matching) | Haiku |
| Cache management | Low | No (read/write/compare) | Haiku |
docs-checker (Complex validation):
model: sonnet
Reasoning:
docs-fixer (Sophisticated analysis):
model: sonnet
Reasoning:
docs-tutorial-checker (Pedagogical analysis):
model: sonnet
Reasoning:
docs-link-checker (Straightforward validation):
model: haiku
Reasoning:
docs-file-manager (File operations):
model: haiku
Reasoning:
Include in agent documentation to explain model choice:
For Sonnet Agents:
**Model Selection Justification**: This agent uses `model: sonnet` because it requires:
- [Reasoning capability 1 - e.g., "Advanced reasoning to analyze technical claims"]
- [Reasoning capability 2 - e.g., "Deep web research to verify facts"]
- [Reasoning capability 3 - e.g., "Pattern recognition across multiple files"]
- [Decision-making type - e.g., "Complex decision-making for criticality levels"]
- [Orchestration need - e.g., "Multi-step validation workflow orchestration"]
For Haiku Agents:
**Model Selection Justification**: This agent uses `model: haiku` because it performs straightforward tasks:
- [Simple task 1 - e.g., "Pattern matching to extract URLs"]
- [Simple task 2 - e.g., "Sequential URL validation via web requests"]
- [Simple task 3 - e.g., "File existence checks"]
- [Simple task 4 - e.g., "Cache management (read/write/compare)"]
- [Simple task 5 - e.g., "Simple status reporting"]
- No complex reasoning or content generation required
Add justification near the top of agent file, after agent description:
---
name: example-agent
description: Agent description here
model: sonnet
---
# Agent Name
## Agent Metadata
- **Role**: [Role description]
**Model Selection Justification**: [justification here]
[Rest of agent documentation]
Costs:
Benefits:
Use when: Quality and accuracy more important than cost/speed
Benefits:
Limitations:
Use when: Cost and speed more important than complex reasoning
Before selecting a model, ask:
Does the task require judgment calls?
Are there multiple valid interpretations?
Does it need deep analysis of context?
Will it make complex decisions?
Is it high-volume, low-complexity?
Does cost matter more than quality?
❌ Using Sonnet for Simple Tasks:
# Overkill - use haiku
model: sonnet # Just checking if files exist
❌ Using Haiku for Complex Analysis:
# Insufficient - use sonnet
model: haiku # Analyzing code quality and architecture
✅ Match Model to Task Complexity:
# Simple pattern matching
model: haiku
# Complex reasoning
model: sonnet
Proper model selection ensures optimal performance, cost-effectiveness, and task completion quality.