Auto-Generate Documentation

What you will build

A complete documentation site for a codebase, organized by domain and Diátaxis category (tutorials, guides, reference, resources), written and maintained through Claude Code skills.

Prerequisites

• Bun installed (runs the summarize-codebase CLI)
• MEILI_MASTER_KEY set in the environment (run just fish to source it)
• A running Meilisearch instance (defaults to http://localhost:7700)
• A target repository to document
• This docs template checked out as a sibling directory

The workflow at a glance

Six skills handle the full lifecycle:

1. /index-repo — summarize the codebase and push to Meilisearch
2. /plan-docs — analyze summaries and plan the doc structure
3. /write-doc — write individual documents from summaries and source code
4. /index-docs — re-index written docs for cross-linking
5. /review-doc — verify accuracy against source code
6. /update-docs — sync docs when source code changes

Each skill searches Meilisearch for context, reads actual source files for detail, and writes .mdx files into the Starlight content directory.

Step 1: Index the target codebase

The summarize-codebase script walks a repository, generates LLM summaries for every file and folder, and pushes them into Meilisearch.

/index-repo /absolute/path/to/repo my-project

This runs three stages internally:

1. Scan — walks the repo with git ls-files, records file paths, sizes, and checksums in a local SQLite database (.summarize-codebase.db in the repo root)
2. Summarize — sends each file to an LLM for a one-paragraph summary, then summarizes folders bottom-up from their children
3. Index — pushes all summaries into a Meilisearch index named my-project

The process is incremental. On re-runs, it detects added, changed, and removed files by checksum and only re-summarizes what changed.

After indexing, verify it worked:

uv run --script .claude/tools/search-summaries.py "config" --index my-project --limit 3

You should see file and folder results with summaries.

Step 2: Plan the documentation

/plan-docs my-project "My Project"

The planning skill queries Meilisearch with broad searches (“architecture”, “API”, “authentication”, “database”, “components”) to map the codebase. It groups findings into documentation domains, then for each domain plans specific documents across the four Diátaxis categories.

The output is a docs-plan.md file at src/content/docs/<project-slug>/docs-plan.md. Review this plan before proceeding — it drives what gets written.

Step 3: Write the docs

The plan skill spawns writer agents automatically in batches of 3-5. You can also write individual docs manually:

/write-doc my-project src/content/docs/my-project/api/guides/auth.mdx "Authentication" guides

Each writer:

1. Searches summaries with keywords extracted from the doc title
2. Gets file context for the top hits — folder summaries, sibling files
3. Reads 5-8 actual source files for implementation detail
4. Searches existing docs for cross-link targets
5. Writes the .mdx file with frontmatter and body content

Between batches, docs are re-indexed so later writers can cross-link to earlier output.

Step 4: Index the written docs

/index-docs my-project

This chunks every .mdx and .md file under src/content/docs/ and indexes them into a my-project-docs Meilisearch index. The docs index powers cross-linking and the /lookup skill.

Step 5: Review for accuracy

/review-doc src/content/docs/my-project/api/guides/auth.mdx my-project

The review skill extracts every technical claim from a document, searches for the source files that should back each claim, reads them, and flags anything inaccurate or outdated. Run this after writing or after the source code changes.

Step 6: Keep docs in sync

When source code changes, update the docs:

/update-docs my-project /absolute/path/to/repo HEAD~5

This analyzes the git diff, searches for affected docs, updates them in place, and writes new docs for new features. It flags docs that reference deleted code with a caution banner rather than deleting them.

From within the source project itself, use /sync-docs instead — it gathers the diff locally and spawns the update agent in the docs project without switching directories.

Search tools

Six Python scripts in .claude/tools/ query Meilisearch. The skills use them internally, but you can run them directly:

Tool	Purpose
search-summaries.py	Search file/folder summaries by keyword
search-docs.py	Search indexed documentation chunks
get-file-context.py	Get a file’s summary, folder context, and siblings
get-folder-tree.py	Get folder structure with summaries
find-links.py	Find related docs for cross-linking
list-indexes.py	List all Meilisearch indexes

All tools take --index explicitly and output JSON to stdout. Run them with uv run --script:

uv run --script .claude/tools/search-summaries.py "authentication" --index my-project --type file --limit 10

Legacy: scripts/docs-mcp

The scripts/docs-mcp directory contains an earlier documentation pipeline implementation. It used a standalone CLI (docs-mcp) with a five-stage pipeline (file tree → structure extraction → summarization → planning → writing) orchestrated through TypeScript commands and the Anthropic API directly.

This implementation is non-functional and scheduled for removal. It has been fully replaced by the .claude/skills/ and .claude/tools/ workflow described above. The current system uses Claude Code’s native agent capabilities instead of a custom orchestration layer, which makes it simpler to maintain and extend.

Do not use scripts/docs-mcp for documentation generation. Use the /index-repo → /plan-docs → /write-doc workflow instead.