Agent Documenting References

majiayu000/claude-skill-registry-agent-documenting-references

Standardized reference documentation section structure for agents - project guidance, conventions, related agents, and Skills. Use when implementing or updating agent documentation.

3k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

532

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/majiayu000/claude-skill-registry --skill agent-documenting-references

What comes with it

848 bytes besides the instruction

metadata.json

The instruction itself

17 sections, as written by the author

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

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

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

Keep Links Current: Update when conventions move or rename
Be Selective: Only include truly relevant references
Describe Relationships: Explain how related agents connect
Match Frontmatter: Ensure Skills section matches skills: field
Use Relative Paths: Make links work from agent file location
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.

How to use it

Copy the folder

Take majiayu000/claude-skill-registry-agent-documenting-references from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.