diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-documenting-references
agent-documenting-references
VerifiedStandardized reference documentation section structure for agents - project guidance, conventions, related agents, and Skills. Use when implementing or updating agent documentation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.1 KB |
| metadata.json | config | 1.5 KB |
SKILL.md
View on GitHub---
name: agent-documenting-references
description: Standardized reference documentation section structure for agents - project guidance, conventions, related agents, and Skills. Use when implementing or updating agent documentation.
---
# Documenting Agent References
Standard structure for "Reference Documentation" sections in agent files to ensure consistent navigation and discoverability.
## When This Skill Loads
This Skill auto-loads when implementing agents or updating agent documentation sections.
## Reference Documentation Section
All agents SHOULD include a "Reference Documentation" section near the end (before any appendices) with standardized subsections.
### Section Template
```markdown
## 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)
```
### Subsection Details
#### Project Guidance
**Purpose**: Link to primary project instructions and domain-specific conventions.
**Always Include**:
- AGENTS.md.\*primary guidance for all agents)
**Conditionally Include**:
- Domain-specific conventions (e.g., README Quality Convention for readme-agents)
- Framework-specific guidance (e.g., Hextra guide for ayokoding-web-agents)
- Special standards relevant to agent's scope
**Pattern**:
```markdown
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [Specific Convention](path/to/convention.md) - Domain standards
```
#### Related Agents
**Purpose**: Help users understand agent ecosystem and workflow relationships.
**Include**:
- **Upstream agents**: Agents this agent depends on (e.g., checker for fixer)
- **Downstream agents**: Agents that depend on this one (e.g., fixer for checker)
- **Parallel agents**: Agents in same family/domain (e.g., other checkers)
- **Complementary agents**: Agents with related functionality
**Organize by Relationship**:
```markdown
**Related Agents**:
- `upstream-agent` - Description of relationship
- `downstream-agent` - Description of relationship
- `parallel-agent` - Description of functionality
```
**Examples by Agent Type**:
**Maker Agents**:
```markdown
- `checker-agent` - Validates content created by this maker
- `related-maker` - Creates content in related domain
```
**Checker Agents**:
```markdown
- `maker-agent` - Creates content this checker validates
- `fixer-agent` - Fixes issues found by this checker
- `related-checker` - Validates related aspects
```
**Fixer Agents**:
```markdown
- `checker-agent` - Generates audit reports this fixer processes
- `maker-agent` - Updates content after fixes applied
```
#### Related Conventions
**Purpose**: Link to conventions and development practices the agent implements.
**Include**:
- Primary convention agent implements
- Secondary conventions relevant to agent's scope
- Development practices agent follows (e.g., AI Agents Convention)
- Standards agent enforces (for checkers)
**Pattern**:
```markdown
**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**:
- Conventions they validate against
- Quality standards they enforce
**Makers Should List**:
- Conventions they follow when creating content
- Formatting standards they apply
#### Skills
**Purpose**: Reference Skills the agent uses for domain knowledge and patterns.
**Include**:
- All Skills listed in agent's `skills:` frontmatter field
- Skills should be listed without path (just skill name)
- Brief description of what each Skill provides
**Pattern**:
```markdown
**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.
## Placement in Agent Files
**Recommended Location**: Near end of agent file, before any appendices or examples.
**Typical Structure**:
```markdown
# Agent Name
[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.]
```
## Examples by Agent Family
### docs-family Agents
```markdown
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [Content Quality Principles](../../../governance/conventions/content/quality.md)
- [Diátaxis Framework](../../../governance/conventions/meta/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](../../../governance/conventions/content/quality.md)
- [Factual Validation Convention](../../../governance/conventions/content/factual-validation.md)
- [Linking Convention](../../../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
```
### readme-family Agents
```markdown
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [README Quality Convention](../../../governance/conventions/content/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](../../../governance/conventions/content/readme-quality.md)
- [Content Quality Principles](../../../governance/conventions/content/quality.md)
**Skills**:
- `readme-writing-readme-files` - README-specific standards
- `wow-assessing-criticality-confidence` - Criticality assessment
- `wow-generating-validation-reports` - Report generation
```
### plan-family Agents
```markdown
## Reference Documentation
**Project Guidance**:
- [AGENTS.md](../../../CLAUDE.md) - Primary guidance
- [Plans Organization Convention](../../../governance/conventions/project/plans-organization.md)
**Related Agents**:
- `plan-maker` - Creates project plans
- `plan-checker` - Validates plan quality
- `plan-executor` - Executes plans
- `plan-execution-checker` - Validates completed work
- `plan-fixer` - Fixes plan issues
**Related Conventions**:
- [Plans Organization Convention](../../../governance/conventions/project/plans-organization.md)
- [Gherkin Acceptance Criteria](../../../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
```
## Benefits of Standardization
✅ **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
## Best Practices
1. **Keep Links Current**: Update when conventions move or rename
2. **Be Selective**: Only include truly relevant references
3. **Describe Relationships**: Explain how related agents connect
4. **Match Frontmatter**: Ensure Skills section matches `skills:` field
5. **Use Relative Paths**: Make links work from agent file location
6. **Group Logically**: Keep subsections organized and scannable
## Key Takeaways
- **Standard structure**: Use consistent subsections across all agents
- **Four subsections**: Project Guidance, Related Agents, Related Conventions, Skills
- **Clear relationships**: Help users understand agent ecosystem
- **Proper placement**: Near end of agent file before appendices
- **Keep current**: Update references when files move or change
- **Match frontmatter**: Skills section mirrors `skills:` field
This standardization improves agent documentation consistency and helps users navigate the agent ecosystem effectively.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |