Use this skill when generating AI-agent-friendly documentation for a git repo or directory, answering questions about a codebase from existing docs, or incrementally updating documentation after code changes. Triggers on codedocs:generate, codedocs:ask, codedocs:update, "document this codebase", "generate docs for this repo", "what does this project do", "update the docs after my changes", or any task requiring structured codebase documentation that serves AI agents, developers, and new team members.
Use this skill when generating AI-agent-friendly documentation for a git repo or directory, answering questions about a codebase from existing docs, or incrementally updating documentation after code changes. Triggers on codedocs:generate, codedocs:ask, codedocs:update, "document this codebase", "generate docs for this repo", "what does this project do", "update the docs after my changes", or any task requiring structured codebase documentation that serves AI agents, developers, and new team members.
When this skill is activated, always start your first response with the 🧢 emoji.
Codedocs
Codedocs generates structured, layered documentation for any git repository or code
directory - documentation designed to be consumed by AI agents first and human developers
second. Instead of flat READMEs that lose context, codedocs produces a docs/ tree with
an architecture overview, per-module deep dives, cross-cutting pattern files, and a
manifest that tracks what has been documented and when. Once docs exist, the skill answers
questions from the docs (not by re-reading source code), and supports incremental updates
via targeted scope or git-diff detection.
Activation Banner
At the very start of every codedocs invocation, before any other output, display this ASCII art banner:
Follow the banner immediately with the active sub-command and target path, e.g.:
codedocs:generate · src/ → docs/
When to use this skill
Trigger this skill when the user:
Wants to generate documentation for a codebase, repo, or directory
Asks "what does this project do" or "explain this codebase"
Needs onboarding docs for new team members joining a project
Wants AI-agent-readable documentation for a repo
Asks a question about a codebase that already has codedocs output
Needs to update existing docs after code changes or a new feature
Wants to document only a specific module or subdirectory
Asks to refresh docs based on recent git commits or a diff
Do NOT trigger this skill for:
Writing standalone technical documents (RFCs, ADRs, runbooks) - use internal-docs
API reference docs for external consumers - use technical-writing
README creation for open-source packaging - use open-source-management
Key principles
Docs-first answers - Once codedocs output exists, always answer questions from the
docs before falling back to source code. The docs are the cached, structured knowledge
layer. Only read source code when docs are missing, stale, or insufficient for the
specific question.
Language-agnostic detection - Detect the tech stack from manifest files (package.json,
Cargo.toml, go.mod, requirements.txt, pyproject.toml, composer.json, pom.xml, build.gradle,
Gemfile, mix.exs, etc.) and directory conventions. Never assume a specific language.
Modules map to code, patterns cut across - Module docs correspond to distinct code
directories or bounded contexts (auth, api, database). Pattern docs capture cross-cutting
concerns (error handling, testing strategy, logging conventions) that span multiple modules.
This split prevents duplication and matches how developers think about code.
Manifest-driven incremental updates - The .codedocs.json manifest tracks every
documented module, its source path, and the git SHA at documentation time. Updates use
this manifest to know what changed, what to re-scan, and what to skip.
Output is configurable, structure is not - The output directory (default docs/) is
configurable. The internal structure (OVERVIEW.md, INDEX.md, .codedocs.json, modules/, patterns/)
is fixed. Consistency across repos means any agent or developer knows where to look.
Coverage is a first-class metric - Documentation that covers 40% of a codebase is
often worse than none - it gives a false sense of completeness. Always run coverage
verification before presenting the plan. Target 70%+ for mid-size repos. Report coverage
percentage in OVERVIEW.md and the manifest. See references/coverage-strategy.md for targets.
Go deep, not just wide - For large repos, top-level modules are just the starting point.
Any module with 15+ source files must be analyzed for sub-modules. Scan recursively through
the full directory tree - a huge repo should generate 30-80 doc files, not 8-12.
Core concepts
Output structure - Codedocs always produces the same directory tree. OVERVIEW.md is the
entry point covering architecture, tech stack, project structure tree, and module map.
GETTING_STARTED.md is the authoritative local development guide with every runnable command
in the repo. INDEX.md is the file-to-module lookup table. The modules/ directory contains one
markdown file per major code module (with optional sub-module directories for large modules).
The patterns/ directory contains cross-cutting concern docs. The .codedocs.json manifest
tracks metadata, coverage stats, and SHAs for incremental updates. See
references/output-structure.md for the full spec.
Four sub-commands - The skill exposes four operations: generate for full or scoped
documentation creation, ask for docs-first Q&A, update for incremental refresh, and
status for coverage reporting. Each has its own workflow and parameters. See the common
tasks below and the corresponding reference files for detailed workflows.
Sub-modules - When a module directory has 15+ source files with distinct internal groupings,
it is split into sub-modules. The parent module doc becomes an index; sub-module docs live at
modules/<parent>/<child>.md. This keeps docs focused and prevents any single file from
becoming an unreadably long catch-all.
Coverage verification - Before presenting the generation plan, codedocs computes what
percentage of source files are covered by the proposed module set. If below target, it
expands the scan to find additional modules. Coverage is tracked in the manifest and reported
in OVERVIEW.md. See references/coverage-strategy.md.
Discovery phase - Before writing any docs, the generate command runs a discovery phase:
scan the directory tree, identify the tech stack from manifest files, map module boundaries
from directory structure and import graphs, and detect cross-cutting patterns from shared
utilities and conventions. This phase produces the plan that drives doc generation.
Staleness detection - The update command compares the current git SHA against the SHA
recorded in .codedocs.json for each module. Modules with changed files since last
documentation are flagged as stale. The --diff flag uses git diff to identify exactly
which files changed, enabling surgical updates to only the affected module docs.
Common tasks
1. Generate full codebase documentation
Command:codedocs:generate [path] [--output docs/]
Workflow:
Discover - Scan the target path (default: repo root). Identify language/framework
from manifest files. Map directory structure to candidate modules. Detect entry points
(main files, index files, route definitions, CLI entry points).
Plan - Present the user with a proposed doc plan: list of modules to document,
patterns detected, estimated scope, and coverage percentage. Confirm before proceeding if the plan is large or ambiguous.
Write GETTING_STARTED.md - Full local development guide: prerequisites, installation,
environment setup, dev server, test commands, build commands, lint/format, database
workflow, common dev tasks, and how to reproduce CI locally. Sourced from package.json
scripts, Makefile targets, CI config, and any existing README setup sections.
Write module docs - For each module: purpose, public API/exports, internal structure,
dependencies (what it imports), dependents (what imports it), and key implementation notes.
Write pattern docs - For each cross-cutting pattern: description, where it appears,
conventions to follow, and examples from the codebase.
Write manifest - Create .codedocs.json with module list, source paths, git SHA,
generation timestamp, coverage stats, and config. See references/output-structure.md.
See references/generate-workflow.md for the complete discovery heuristics, module
boundary detection logic, and OVERVIEW.md template.
2. Ask a question about the codebase
Command:codedocs:ask "<question>"
Workflow:
Check for docs - Look for .codedocs.json in the output directory. If missing,
suggest running codedocs:generate first.
Route the question - Determine which doc file(s) are relevant. Architecture questions
go to OVERVIEW.md. Module-specific questions go to the relevant module doc. Cross-cutting
questions go to pattern docs.
Read docs first - Load the relevant doc file(s) and attempt to answer from them.
Fall back to source - If the docs don't contain enough detail, read the relevant
source files. Flag in the response: "Note: this answer required reading source code -
consider running codedocs:update to capture this in the docs."
Cite sources - Always cite which doc file or source file the answer came from.
See references/ask-workflow.md for the question routing logic and fallback strategy.
3. Update docs incrementally (targeted scope)
Command:codedocs:update --scope path/to/module
Workflow:
Read manifest - Load .codedocs.json to find the existing module mapping.
Re-scan the scoped path - Run the discovery phase only on the specified path.
Diff against existing docs - Compare the new discovery against the current module
doc. Identify new exports, removed functions, changed dependencies.
Update the module doc - Rewrite only the sections that changed.
Update OVERVIEW.md - If the module's one-line description or dependency graph changed,
update the module map in OVERVIEW.md.
Update manifest - Bump the git SHA and timestamp for the updated module.
4. Update docs from git diff
Command:codedocs:update --diff [base..head]
Workflow:
Get changed files - Run git diff --name-only base..head (default: last documented
SHA from manifest to HEAD).
Map files to modules - Using the manifest's source path mappings, determine which
documented modules contain changed files.
Re-generate affected modules - For each affected module, re-run the module doc
generation workflow.
Detect new modules - If changed files are in directories not yet documented, flag
them as new module candidates and prompt the user.
Update manifest - Bump SHAs for all updated modules.
See references/update-workflow.md for the diff detection logic and new module handling.
Same workflow as full generation but scoped to a subdirectory. The output defaults to a
docs/ folder inside the specified path. Useful for monorepos where each package needs
its own documentation.
6. Check documentation coverage
Command:codedocs:status
Workflow:
Read manifest - Load .codedocs.json. If missing, suggest running codedocs:generate.
Compute coverage - Count total source files in the repo vs files covered by documented
modules.
Detect staleness - For each module, compare the manifest SHA against the latest git
commit SHA on that module's source path.
Find gaps - List directories in the repo not covered by any module doc.
Report - Print a structured status report: coverage percentage, stale modules, gap
directories, and recommendations.
See references/coverage-strategy.md for coverage targets, the status report format, and
strategies for improving coverage on large repos.
Anti-patterns / common mistakes
Mistake
Why it's wrong
What to do instead
Re-reading source code when docs exist
Wastes context window and time; docs are the structured cache
Always check for .codedocs.json first; read docs before source
Documenting every file individually
Creates noise; most files are internal implementation details
Document at the module level; only call out key files within a module
Skipping the discovery/plan phase
Jumping straight to writing produces unstructured, incomplete docs
Always run discovery first; present the plan to the user for approval
Hardcoding language assumptions
Breaks on polyglot repos or unfamiliar stacks
Detect from manifest files; handle multiple languages in one repo
Ignoring the manifest on updates
Leads to full re-generation when only one module changed
Always read .codedocs.json to scope updates to changed modules only
Mixing module docs and pattern docs
Cross-cutting concerns documented in one module become invisible
Use the patterns/ directory for anything that spans 2+ modules
Writing docs without git SHA tracking
Makes incremental updates impossible; no way to know what's stale
Always populate the manifest with per-module git SHAs
Stopping at top-level directories
A huge repo generates only 8-12 files; most of the codebase is invisible
Run the full recursive census (Step 3), verify coverage, and scan deeper
One flat doc for a 50-file module
The doc is too long to be useful; every question returns the same giant file
Split modules with 15+ files into sub-modules (modules/<parent>/<child>.md)
Not checking coverage before presenting plan
Low-coverage plans look complete but leave most of the repo undocumented
Always run Step 6 (coverage verification) before showing the plan
Skipping INDEX.md
AI agents can't map a specific file to its module doc
Always generate INDEX.md as part of the output
Skipping GETTING_STARTED.md
Developers and agents can't run the project without hunting through package.json and README
Always generate GETTING_STARTED.md; source commands from scripts, Makefile, and CI config
Copying README verbatim into GETTING_STARTED.md
READMEs are often incomplete or outdated; the guide adds no value
Extract commands from README but expand with context, fill gaps, and verify against actual scripts
Gotchas
Manifest SHA drift causes phantom staleness - If the repo has uncommitted changes when codedocs:generate runs, the recorded git SHA doesn't match the working tree. Subsequent codedocs:update runs see all files as stale and attempt full re-generation. Run codedocs against a clean working tree or committed state where possible.
Coverage counts source files, not lines - A large 2,000-line file and a small 50-line config file each count as one source file for coverage. A 70% coverage score can hide an undocumented core module if it happens to be split into many small files. Review the gap directory list in codedocs:status rather than trusting the percentage alone.
Sub-module splitting creates orphaned parent docs - When a module with 15+ files is split into sub-modules, the parent modules/<name>.md should become an index pointing to sub-modules. If you create modules/api/routes.md and modules/api/middleware.md but leave the original modules/api.md intact unchanged, agents get conflicting information from two sources about the same code.
Polyglot repos confuse module boundary detection - A repo with both a Python backend and a TypeScript frontend may have overlapping directory names (utils/, types/, config/) at different levels. The discovery phase can conflate these into one module. Explicitly verify module boundaries during the plan phase for monorepos or polyglot projects.
GETTING_STARTED.md sourced only from README - READMEs are often incomplete or outdated. Commands listed in package.json scripts, Makefile targets, and CI config files frequently include critical developer workflows not mentioned in the README. Always cross-check all three sources when generating GETTING_STARTED.md.
References
For detailed workflows and schemas, read the relevant file from references/:
references/ask-workflow.md - Question routing logic, doc-first resolution strategy,
source code fallback rules, and citation format. Load when running codedocs:ask.
references/update-workflow.md - Diff detection logic, manifest-driven scoping, new
module detection, and OVERVIEW.md sync rules. Load when running codedocs:update.
references/output-structure.md - Complete .codedocs.json manifest schema (v1.1 with
coverage stats and sub-modules), directory layout spec including sub-module directories
and INDEX.md, and file format guidelines. Load when creating or validating output.
references/coverage-strategy.md - Coverage targets by repo size, the codedocs:status
report format, prioritization framework for large repos, and coverage improvement
strategies. Load when running codedocs:status or when coverage is below target.
Only load a references file if the current task requires deep detail on that topic.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
