Agent Documenting References Skill for Claude

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.

Other skills for the same job

different authors, same section of the catalogue

Plugin Settings

by anthropics

vendor ×2

This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.

-Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes.

Standardize how an AI-collaboration project turns work into reusable knowledge. Use when initializing or retrofitting Project Cairn in a project, recording progress after meaningful work, maintaining AGENTS/CLAUDE/cairn docs, auditing project knowledge for drift or missing records, pulling and citing external knowledge, or graduating validated project experience into a reusable knowledge base.

Persistent memory and context management for AI agents using OpenContext. Keep context across sessions/repos/dates, store conclusions, and provide document search workflows.

> PARA method knowledge management for Obsidian vaults. Use this skill whenever the user wants to organize notes using PARA (Projects, Areas, Resources, Archive), classify a note into a PARA category, route a note to the right vault folder, normalize frontmatter fields, run a PARA hygiene review, suggest archiving, audit vault structure, or process new knowledge inputs into an existing PARA-based vault. Also trigger when the user mentions inbox processing, vault cleanup, note classification, PARA review, or asks "where does this note belong?". Works with existing Obsidian skills (obsidian-markdown, obsidian-cli) — never replaces them.

17k tokens

N8n:spec Driven Development

by n8n-io

vendor

Keeps implementation and specs in sync. Use when working on a feature that has a spec in .agents/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use when the user asks to verify implementation against a spec or update a spec after changes.

807 tokens

Knowledge Agent

by thedotmack

Build and query AI-powered knowledge bases from claude-mem observations. Use when users want to create focused "brains" from their observation history, ask questions about past work patterns, or compile expertise on specific topics.

622 tokens

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.