Documentation Skill

Ensures all documentation follows project standards and prevents redundant files.

Purpose

This skill provides tools and workflows for efficient documentation management:

• •Section-level interaction scripts (search, get, update without reading full files)
• •Document templates for consistent structure
• •Workflows for common documentation tasks
• •Rules and standards to prevent redundancy

When to Use This Skill

Use this skill when:

• •Creating new documentation for features, screens, or architecture
• •Updating existing documentation after code changes
• •Finding and consolidating duplicate documentation
• •Splitting large documentation files (>500 lines)
• •Searching for specific information in docs
• •Checking documentation quality and compliance

Core Principles

1. DRY (Don't Repeat Yourself)

• •Check for existing documentation before creating new files
• •Update existing docs instead of creating duplicates
• •Consolidate related information into single files

2. Screen-Based Organization

docs/
├── README.md              # Master index (DO NOT MODIFY)
├── guides/                # User and developer guides
├── architecture/          # Architecture docs
└── screens/               # Screen-specific docs
    └── {screen-name}/
        ├── README.md      # Overview (required)
        ├── features.md    # Features (optional)
        ├── technical.md   # Technical (required)
        └── flows.md       # Flows (optional)

3. Size Limits

• •Maximum 500 lines per file
• •Split files approaching limit (>450 lines)
• •Keep documents focused and scannable

How to Use This Skill

Step 1: Check for Existing Documentation

Use scripts for efficient search (80-98% context reduction):

# Search without reading full files
./scripts/doc-search.sh "topic-keyword"

# Get file metadata (0 lines read)
./scripts/doc-metadata.sh docs/path/to/file.md

# List sections to navigate (structure only)
./scripts/doc-list-sections.sh docs/file.md

Complete script documentation: See scripts/README.md

Step 2: Determine Action

If similar documentation exists:

• •Load workflow: references/workflows/update-existing.md
• •Use doc-get-section.sh to read only relevant section
• •Update section with doc-update-section.sh

If creating new documentation:

• •Load workflow: references/workflows/create-screen.md
• •Load template: assets/templates/screen-readme.md or assets/templates/screen-technical.md
• •Follow template structure

If file is too large (>450 lines):

• •Load workflow: references/workflows/split-large-file.md

If duplicates found:

• •Load workflow: references/workflows/consolidate-duplicates.md

Step 3: Validate Against Rules

Load reference file: references/rules.md

Check:

• •✅ No duplicate content exists
• •✅ File under 500 lines
• •✅ Code references include file:line format
• •✅ All code blocks have language specified
• •✅ Examples are tested and working

Complete rules: See references/rules.md

Bundled Resources

Scripts (scripts/)

Efficient section-level interaction tools:

• •doc-search.sh - Search content without reading full files
• •doc-list-sections.sh - List all headings with line numbers
• •doc-get-section.sh - Extract specific section only (90% context reduction)
• •doc-update-section.sh - Update section without reading full file
• •doc-delete-section.sh - Remove section
• •doc-insert-after.sh - Insert content after section
• •doc-metadata.sh - Get file statistics (100% context reduction)
• •doc-find-duplicates.sh - Find redundant content

Benefits: 80-98% reduction in context usage vs reading entire files

Complete documentation: scripts/README.md

References (references/)

Load as needed for detailed information:

• •rules.md - Complete documentation rules and anti-patterns
• •structure.md - Directory organization details and navigation
• •examples.md - Real examples from this project (good vs bad patterns)
• •workflows/ - Step-by-step workflows for common tasks:
  • •create-screen.md - Creating new screen documentation
  • •update-existing.md - Updating existing documentation
  • •consolidate-duplicates.md - Consolidating duplicate docs
  • •split-large-file.md - Splitting files >500 lines
  • •add-examples.md - Adding examples to docs
  • •review-quarterly.md - Quarterly documentation review

Assets (assets/)

Templates used in documentation output:

• •templates/ - Document templates:
  • •screen-readme.md - For docs/screens/{name}/README.md
  • •screen-technical.md - For docs/screens/{name}/technical.md
  • •screen-features.md - For docs/screens/{name}/features.md
  • •screen-flows.md - For docs/screens/{name}/flows.md
  • •architecture.md - For docs/architecture/*.md
  • •guide.md - For docs/guides/*.md

Progressive Disclosure

This skill uses filesystem-based progressive disclosure:

Level 1: Metadata (always in context)

• •Skill name and description (~100 words)

Level 2: SKILL.md (when skill triggers)

• •Core instructions and workflow guidance (~2k words)

Level 3: Bundled resources (loaded as needed)

• •Scripts: Execute without reading into context
• •References: Load specific file when detailed info needed
• •Assets: Copy template into output

Example: Creating screen docs

• •Before: Read all 3,620 lines
• •After: SKILL.md (300 lines) + workflow (150 lines) + template (200 lines) = 650 lines (82% reduction)

Typical Workflows

Creating New Screen Documentation

1. •Check: ./scripts/doc-search.sh "ScreenName"
2. •If not exists: Load references/workflows/create-screen.md
3. •Follow workflow:
   • •Create directory: docs/screens/{screen-name}
   • •Use template: assets/templates/screen-readme.md
   • •Use template: assets/templates/screen-technical.md
   • •Validate against: references/rules.md

Updating Existing Documentation

1. •Get metadata: ./scripts/doc-metadata.sh docs/file.md
2. •List sections: ./scripts/doc-list-sections.sh docs/file.md
3. •Get section: ./scripts/doc-get-section.sh docs/file.md "Section"
4. •Update section: ./scripts/doc-update-section.sh docs/file.md "Section" new-content.md

Finding and Removing Duplicates

1. •Find duplicates: ./scripts/doc-find-duplicates.sh docs/
2. •Load workflow: references/workflows/consolidate-duplicates.md
3. •Follow consolidation steps
4. •Delete redundant files

Questions to Ask User

Before creating documentation:

• •"Found similar docs at {path}. Update existing instead of creating new?"
• •"Is this feature complete and ready to document?"
• •"Should this go in screens/{screen}/, guides/, or architecture/?"
• •"File is 450+ lines. Should split into multiple files?"

Success Criteria

Good documentation is:

• •✅ Easy to find (follows structure in references/structure.md)
• •✅ Easy to read (under 500 lines)
• •✅ No duplicates (DRY principle)
• •✅ Up to date (matches current code)
• •✅ Actionable (includes tested examples)
• •✅ Traceable (code references with file:line format)