doc-generation

name	doc-generation
description	Generate and update wiki-style documentation for codebases using AST-aware structural analysis. Use when the user wants to generate documentation, update stale documentation, create a documentation wiki, or assess documentation coverage for a repository.

Documentation Generation

Generate comprehensive wiki-style documentation for any codebase using AST-aware structural analysis and Claude's reasoning.

Supported languages: Python, JavaScript, TypeScript, Java, C, C++, C#, Kotlin, PHP

Output: Flat directory of markdown files with Mermaid diagrams, cross-references, and a repository overview. Default output path: docs/wiki/ relative to repo root.

Compatibility: This skill produces its own documentation format. It is not compatible with CodeWiki or DeepWiki output. The "update existing documentation" flow only works with docs previously generated by this skill.

Warning: Full-codebase documentation generation is token-intensive. Repos with >200 components will use significant tokens. Repos with >500 components should be documented in phases (core modules first).

---

Locating Scripts

The analysis scripts are in the scripts/ subdirectory next to this SKILL.md file. Before running any commands, determine the absolute path to this skill directory. For example, if this SKILL.md is at /home/user/.claude/skills/doc-generation/SKILL.md, then the scripts are at /home/user/.claude/skills/doc-generation/scripts/.

Store this path in a variable for use throughout:

SKILL_SCRIPTS="/absolute/path/to/.claude/skills/doc-generation/scripts"

---

Pre-flight Checks

Before starting, verify these in order:

1. Python 3.11+

python3 --version

If not available, stop and tell the user.

2. Parser Dependencies

python3 "$SKILL_SCRIPTS/analyze_repo.py" --check-deps /path/to/repo

When a repo path is provided, this scans the repo for file extensions, determines which languages are present, and only checks whether those parsers are installed. It exits 0 if all needed parsers are available, exits 1 if any are missing.

Without a repo path, it checks all parsers globally (useful for a one-time environment setup).

If needed parsers are missing, the command prints install instructions. Python analysis uses stdlib ast and never requires tree-sitter.

3. Git Repository

The target repo must be a git repository. If git rev-parse HEAD fails in the repo directory, stop and tell the user: "This directory is not a git repository. Documentation versioning requires git."

4. Fresh vs Update

Check if docs/wiki/.doc-meta.json exists in the target repo:

• Does NOT exist → follow Fresh Generation below
• Exists → follow Update Existing Documentation below

---

Fresh Generation

Phase 1 — Structural Analysis

Run the analysis script. Determine the absolute path to the scripts directory first.

python3 "$SKILL_SCRIPTS/analyze_repo.py" /path/to/repo --output /path/to/repo/.doc-analysis.json

Scoping options (pass as needed):

• --include "*.py,*.ts" — Only analyze files matching these patterns
• --exclude "*test*,*spec*,*mock*" — Skip files matching these patterns
• --focus "src/core,src/api" — Tag directories for deeper documentation (see Phase 3)
• --max-files 300 — Limit total files analyzed
• --verbose — Show detailed logging

Read the output JSON with the Read tool. Report to the user:

• Number of files analyzed
• Number of components found
• Number of relationships discovered
• Languages detected and parsed
• Languages skipped (if any — this means parsers were missing)

Critical check: If languages_skipped is non-empty, stop and warn the user. Offer two options:

1. Install the missing parsers and re-run
2. Proceed with partial analysis (documentation will only cover parsed languages)

If >200 components, warn: "This repo has {N} components. Documentation generation will be token-intensive. Proceed?"

If >500 components, suggest phased approach: "Consider documenting core modules first using --include to scope to specific directories. Which areas are most important?"

Phase 2 — Module Clustering

Using the analysis JSON, group components into logical modules. This is your reasoning — no external tool needed.

Clustering heuristics (apply in order):

1. File path proximity: Components in the same directory or subdirectory belong together. Group by the first 2-3 path segments (e.g., src/auth/* → "authentication" module).

2. Dependency relationships: Components that call each other frequently belong together. Use the relationships array from the analysis.

3. Naming conventions: Components with common prefixes or domain terms (auth, db, api, payment, user) form natural modules.

4. For small repos (<30 components): Skip clustering. Document everything in a single comprehensive overview.

5. For large repos (>100 components): Create hierarchical sub-modules. A top-level module like "api-layer" might have sub-modules for routes, middleware, and validators.

Module naming: Use lowercase-with-hyphens for all module names. These become filenames: authentication.md, database-layer.md, api-routes.md.

Persist the module tree: Write docs/wiki/module-tree.json with the clustering result:

{
  "authentication": {
    "components": ["src.auth.service.AuthService", "src.auth.models.User"],
    "description": "User authentication and session management",
    "doc_file": "authentication.md"
  },
  "database-layer": {
    "components": ["src.db.pool.ConnectionPool", "src.db.models.BaseModel"],
    "description": "Database connection and ORM layer",
    "doc_file": "database-layer.md"
  }
}

Phase 3 — Module Documentation

Process modules leaf-first (modules with no sub-modules first, then parent modules).

Focus areas: If --focus was used, each component in the analysis JSON has an is_focus field (true/false). Modules containing focus components get deeper documentation: more detailed component descriptions, more code snippets, additional Mermaid diagrams for internal flows. Non-focus modules get standard documentation.

For each module, use the Read tool to read the actual source files of its components, then write a markdown documentation file.

Each module doc ({module-name}.md) should include:

1. Module Overview — 2-3 sentences describing purpose and responsibility
2. Architecture Diagram — Mermaid diagram showing components and their relationships within the module:

   graph TD
     A[ComponentA] --> B[ComponentB]
     B --> C[ComponentC]
   

3. Component Descriptions — For each key component:
   • What it does
   • Key methods/functions and their purpose
   • Important parameters and return types
4. Dependencies — Mermaid diagram showing what other modules this module depends on:

   graph LR
     ThisModule --> DatabaseModule
     ThisModule --> ConfigModule
   

5. Key APIs — The most important public interfaces with brief usage notes
6. Cross-references — Links to related module docs using the exact filename: [Database Layer](database-layer.md)

Important rules:

• All .md files go in the same flat directory (docs/wiki/)
• Cross-reference format: [Display Name](filename.md) — all files are siblings, filenames use lowercase-with-hyphens
• Include source code snippets for key interfaces — short, focused excerpts
• Mermaid diagrams should be clear and not overly complex — 5-15 nodes max per diagram

Phase 4 — Repository Overview

After all module docs are written, generate overview.md:

1. Repository Purpose — What this codebase does, in 2-3 sentences
2. Architecture Overview — Top-level Mermaid diagram showing all modules and their relationships:

   graph TD
     API[API Layer] --> Auth[Authentication]
     API --> DB[Database]
     Auth --> DB
     API --> Cache[Cache Layer]
   

3. Module Index — Table linking to all module documentation files with one-line descriptions
4. Technology Stack — Languages, key frameworks, and tools detected
5. Getting Started — Brief orientation for a developer new to the codebase

Phase 5 — Validation

Before declaring success, verify:

1. Cross-reference links: Scan each generated .md file for markdown links of the form [...](*.md). Verify every linked filename exists in docs/wiki/. Report any broken links.

2. Mermaid diagrams: Scan each file for mermaid code blocks. Read each one and verify:

   • It starts with a valid diagram type (graph, flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram)
   • Node and edge syntax is well-formed
   • No obvious syntax errors (unclosed brackets, invalid arrows) If any diagram looks invalid, fix it before proceeding.

3. Completeness: Every module in module-tree.json has a corresponding .md file. The overview.md exists and links to all modules.

4. No empty sections: Scan for markdown headings followed immediately by another heading or end-of-file with no content between them. Fill or remove empty sections.

Phase 6 — Metadata

Write .doc-meta.json to the output directory:

{
  "generated_at": "2026-03-14T10:30:00Z",
  "commit_hash": "abc123def456",
  "module_tree": {
    "authentication": {
      "components": ["src.auth.service.AuthService"],
      "doc_file": "authentication.md"
    }
  },
  "files_generated": ["overview.md", "authentication.md", "database-layer.md"],
  "component_count": 142,
  "repo_name": "my-service",
  "output_path": "docs/wiki",
  "scoping": {
    "include_patterns": null,
    "exclude_patterns": null
  }
}

Report completion: "Documentation generated: {N} module docs + overview. Output: docs/wiki/"

---

Update Existing Documentation

Use this flow when .doc-meta.json already exists.

Step 1 — Detect Staleness

Read docs/wiki/.doc-meta.json using the Read tool. Extract the commit_hash field.

Run git rev-parse HEAD in the repo directory to get the current commit.

If they match, docs are current. Tell the user: "Documentation is up to date (generated at commit {hash})."

If they differ, proceed.

Step 2 — Compute Changes

git diff --name-only {stored_hash} HEAD

This gives you the list of files that changed since docs were last generated.

Step 3 — Re-run Analysis

Run the analysis script again, using the same scoping options from .doc-meta.json if they were set:

python3 "$SKILL_SCRIPTS/analyze_repo.py" /path/to/repo --output /path/to/repo/.doc-analysis.json

Step 4 — Identify Affected Modules

Read the new analysis JSON and the stored .doc-meta.json module tree. Compare:

1. Changed components: Any component whose relative_path appears in the git diff file list
2. New components: Components in the new analysis that don't exist in the stored module tree
3. Removed components: Components in the stored module tree that don't appear in the new analysis
4. Changed relationships: New or removed dependency edges

A module is affected if any of its components were changed, added, or removed.

Step 5 — Re-cluster if Needed

• If only content changed within existing files (no new files, no deleted files): keep existing module tree
• If new files were added or files were deleted: re-evaluate clustering for affected areas. New components may belong to existing modules or may warrant a new module.

Step 6 — Regenerate Affected Docs

For each affected module:

1. Re-read the current source code of its components
2. Rewrite that module's markdown file with updated content
3. Update Mermaid diagrams to reflect any structural changes

For unaffected modules: leave their docs untouched.

Step 7 — Validate and Update Metadata

Run the same validation checks from Phase 5 of Fresh Generation (cross-references, Mermaid, completeness, empty sections).

If any module was affected:

1. Regenerate overview.md to ensure it reflects current state
2. Update .doc-meta.json with new commit hash, timestamp, and module tree

Report: "Updated documentation for {N} modules. {M} modules unchanged."

---

Output Directory Structure

docs/wiki/
├── .doc-meta.json          # Generation metadata (commit hash, module tree, scoping)
├── module-tree.json        # Module clustering structure
├── overview.md             # Repository overview with architecture diagram
├── authentication.md       # Module documentation
├── database-layer.md       # Module documentation
├── api-routes.md           # Module documentation
└── ...                     # Additional module docs

---

When to Stop and Ask

Do not proceed silently in these situations:

• Repo has no supported languages: Stop. Tell the user which languages were detected and that none have parsers.
• More than 20% of files failed analysis: The output is unreliable. Stop and recommend installing missing parsers.
• No git history: The commit hash is "unknown." Warn the user that update/staleness tracking won't work.
• Large repo with no scoping: If >500 components, recommend using --include or --exclude to focus on core areas first.
• Existing docs in a different format: If docs/wiki/ exists but has no .doc-meta.json, it wasn't generated by this skill. Ask whether to overwrite or use a different output path.

---

Documentation Quality Guidelines

Good documentation answers: What does this do? Why does it exist? How does it connect to the rest of the system? How would I use or modify it?

Mermaid diagram types to use:

• graph TD or graph LR — Architecture and dependency diagrams
• sequenceDiagram — For request/response flows or multi-step processes
• classDiagram — For class hierarchies (use sparingly)
• flowchart — For decision trees or process flows

What to include:

• Purpose and responsibility of each module
• How modules connect to each other
• Key interfaces and their contracts
• Source code snippets for important APIs (brief, focused)
• Mermaid diagrams for visual understanding

What NOT to include:

• Line-by-line code commentary
• Implementation details obvious from reading the code
• Test file documentation
• Configuration file documentation (unless critical to understanding architecture)
• Speculative or aspirational content — document what IS, not what could be