SKILL: Documentation Best Practices

Purpose: Apply Claude Code documentation standards based on Superpowers reference Target: Anyone creating CLAUDE.md, commands, skills, guides, or agents

Quick Start

When to Use This Skill

• •Creating new documentation (CLAUDE.md, command, skill, agent)
• •Reviewing existing documentation for quality
• •Restructuring documentation to follow best practices

Quick Reference

Note: Claude Code officially recommends ≤500 lines for SKILL.md. This project uses a stricter 200-line internal standard for token optimization and context efficiency.

What This Skill Covers

In Scope

• •File size targets based on Superpowers standards
• •Frontmatter standards for auto-discovery
• •SKILL.md/REFERENCE.md separation pattern
• •Agent model allocation

Out of Scope

• •Test writing → @.claude/skills/tdd/SKILL.md
• •Code quality → @.claude/skills/vibe-coding/SKILL.md
• •Git workflow → @.claude/skills/git-master/SKILL.md

Core Concepts

Superpowers Standard

"The context window is a public good. Skills share the context window with everything else Claude needs."

Baseline: SKILL.md <600 words (~150-200 lines)

Frontmatter Standards

Skills (required):

---
name: {skill-name}
description: {trigger-rich description for semantic matching}
---

Commands (auto-discovery):

---
description: {action-rich description for slash command discovery}
---

Agents (required):

---
name: {agent-name}
description: {clear purpose statement}
model: {haiku|sonnet|opus}
tools: [tool list]
skills: [skill list]
---

SKILL.md/REFERENCE.md Pattern

SKILL.md (≤200 lines):

• •Quick Start (when to use, quick reference)
• •Core Concepts (essential patterns)
• •Further Reading (link to REFERENCE.md)

REFERENCE.md (≤300 lines):

• •Detailed examples
• •Good/bad patterns
• •Troubleshooting
• •External references

Agent Model Allocation

3-Tier Documentation

• •Tier 1: CLAUDE.md - Project standards (400+ lines)
• •Tier 2: {folder}/CONTEXT.md - Component architecture (≤200 lines)
• •Tier 3: {feature}/CONTEXT.md - Feature implementation (≤200 lines)

Documentation Quality Checklist

Structure

• • Clear purpose statement
• • Quick reference table
• • Standard sections
• • Cross-references

Discoverability

• • Frontmatter complete
• • Description is trigger-rich
• • CONTEXT.md for navigation

Maintainability

• • Within size limits
• • No duplicated content
• • Examples provided

Common Mistakes Checklist

Metadata Errors

• • Outdated line counts: CONTEXT.md line values don't match actual files
• • Stale skill counts: README.md lists wrong number of skills (use ls .claude/skills | wc -l)
• • Version number drift: CLAUDE.md version differs from package.json or other sources
• • Missing frontmatter: SKILL.md or Agent files lack required name/description fields

Cross-Reference Errors

• • Broken links: @.claude/path/to/file.md points to non-existent file
• • Relative paths: Using ../skills/ instead of @.claude/skills/
• • Deleted file references: Documentation still mentions removed systems (e.g., Sisyphus after removal)
• • Wrong file extensions: Linking to .ts instead of .md for documentation

Content Errors

• • Duplicate content: Same info appears in CLAUDE.md and CONTEXT.md
• • Wrong tier: Implementation details in CLAUDE.md instead of docs/ai-context/
• • Missing examples: Abstract concepts without concrete usage examples
• • Over-sized files: SKILL.md >200 lines without split to REFERENCE.md

Recovery Actions

• •Before commit: Invoke docs-verify skill
• •On verification failure: Check error message, locate file, apply fix, re-verify
• •For line count violations: Extract content to REFERENCE.md or docs/ai-context/
• •For broken links: Verify file exists with test -f {path}, use absolute paths

Further Reading

Internal: @.claude/skills/documentation-best-practices/REFERENCE.md - Detailed examples, good/bad patterns, external links | @.claude/skills/coding-standards/SKILL.md - Official directory structure | @.claude/skills/three-tier-docs/SKILL.md - Complete 3-Tier system

External: Claude Code Skills Documentation | Claude Code Memory Documentation | Claude Code Best Practices - Anthropic | Superpowers - obra/superpowers