Generate Repository Documentation

Generates Level 2 repository documentation from design docs with topic-based organization.

Overview

This skill transforms design documentation into comprehensive repository documentation by:

1. Analyzing design docs for the module
2. Creating topic-based documentation structure
3. Generating architecture guides
4. Creating integration guides
5. Adding troubleshooting sections
6. Following the Level 2 template structure

Quick Start

Generate all repository docs for a module:

/docs-generate-repo effect-type-registry

Generate specific topic only:

/docs-generate-repo effect-type-registry --topic=caching

Preview without writing:

/docs-generate-repo rspress-plugin-api-extractor --dry-run

How It Works

1. Parse Parameters

• module

  : Module name to generate docs for [REQUIRED]

• --topic

  : Generate specific topic only (default: all topics)

• --structure

  : Output directory structure (default:

  docs/

  )

• --dry-run

  : Preview file structure without writing

2. Load Configuration and Design Docs

Read

.claude/design/design.config.json

for:

• Module configuration and paths
• Repository docs settings (Level 2)
• Quality standards

Read design docs:

• Find all design docs for module
• Parse frontmatter and content
• Identify major topics and sections
• Map design content to user-facing topics

3. Identify Topics from Design Docs

Extract major topics from design documentation:

• Architecture topics - System design, components, data flow
• Feature topics - Specific capabilities and how they work
• Integration topics - Using with other tools and frameworks
• Performance topics - Optimization and benchmarks
• Testing topics - How to test code using the package

4. Generate Topic Documentation

For each topic:

Extract Content:

• Overview from design doc introduction
• Key concepts explained simply
• Usage patterns and examples
• API reference for topic
• Common issues and solutions

Apply Transformations:

• Simplify technical language
• Add practical examples
• Include troubleshooting
• Cross-link related topics

5. Create Documentation Structure

Organize generated docs into directories:

docs/
├── README.md               # Index of all documentation
├── architecture/
│   ├── overview.md        # High-level architecture
│   └── components.md      # Component breakdown
├── guides/
│   ├── getting-started.md # Detailed getting started
│   └── {topic}.md         # Topic-specific guides
└── troubleshooting.md     # Common issues

6. Write Documentation Files

Write each generated document:

• Apply repo-doc template
• Fill in topic-specific content
• Add table of contents for longer docs
• Validate against Level 2 standards

7. Validate Output

Check generated docs:

• Length: 500-2000 words per document
• Code examples present
• Cross-references valid
• Markdown linting passes

Supporting Documentation

Load these files for detailed guidance:

• instructions.md

  - Step-by-step implementation

• examples.md

  - Example repository documentation

• topic-mapping.md

  - Design doc to user doc topic mapping

Success Criteria

Generated repository documentation is successful when:

• ✅ Comprehensive coverage of module features
• ✅ Topic-based organization (not implementation-based)
• ✅ 500-2000 words per document
• ✅ Practical code examples in each guide
• ✅ Cross-references between related topics
• ✅ Table of contents for documents >800 words
• ✅ Troubleshooting section with common issues
• ✅ Valid markdown and working examples

Integration Points

• Uses

  .claude/design/design.config.json

  for configuration
• Uses

  .claude/skills/docs-generate-repo/templates/repo-doc.template.md

  for structure
• Reads design docs from module's

  designDocsPath

• Writes to module's

  userDocs.repoDocs

  path
• Validates against

  quality.userDocs.level2

  standards

Related Skills

• /docs-generate-readme

  - Generate Level 1 package README

• /docs-generate-site

  - Generate Level 3 site documentation

• /docs-sync

  - Sync docs with design doc changes

• /design-review

  - Review source design docs