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

## 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:

**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:

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

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:

**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:

**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:

# 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

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

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

## 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.