Skip to content

espennilsen/pi / skills/codebase-docs

codebase-docs

Verified

Generate and maintain AI-readable markdown documentation for a codebase in docs/. Use this skill whenever the user asks to document their codebase, generate project docs, create architecture docs, update documentation after code changes, build a knowledge base for AI agents, create onboarding docs, map out a codebase, or explain a project structure. Also trigger when users say things like "document this repo", "create docs for my project", "update the docs", "write architecture documentation", "help AI understand my code", "generate a codebase overview", or "maintain docs". This skill is specifically about creating structured markdown files in a docs/ directory that serve as a knowledge base — NOT about writing inline code comments, README files, or API reference docs from docstrings.

Codebase Documentation Skill

Generate and maintain a structured set of markdown files in docs/ that give AI agents (and humans) a fast, accurate understanding of a codebase without needing to search through source files.

Philosophy

The docs you produce are a map, not the territory. They should let an AI agent answer questions like "where does authentication happen?", "how does data flow from API to database?", or "what are the key abstractions?" — without reading every file. Optimize for navigability and accuracy over exhaustiveness.

When to Use This Skill

  • User asks to document a codebase or project
  • User wants to update existing docs after making changes
  • User wants AI-friendly project documentation
  • User mentions docs/ directory maintenance
  • User wants architecture or structural documentation

Step 1: Assess the Codebase

Before writing anything, understand what you're documenting.

  1. Read the project root — check for existing README, package.json/Cargo.toml/pyproject.toml, config files, and any existing docs/ directory
  2. Map the directory structure — identify source directories, test directories, config, scripts, assets
  3. Identify the tech stack — languages, frameworks, key dependencies, build tools
  4. Find entry points — main files, route definitions, CLI entry points, exported modules
  5. Detect patterns — architecture style (MVC, microservices, monolith, plugin-based), state management, data layer

If a docs/ directory already exists, read it first. You'll be updating, not starting from scratch.

Step 2: Generate the Documentation Set

Create the docs/ directory with the files described below. Not every project needs every file — use judgment. A small CLI tool doesn't need DATA_MODEL.md, and a pure library doesn't need DEPLOYMENT.md.

Refer to references/doc-templates.md for the exact templates and structure for each file. Read that file before writing any documentation.

Required Files (always generate)

FilePurpose
docs/OVERVIEW.mdProject purpose, tech stack, architecture style, key concepts. This is the entry point — an AI agent should read this first.
docs/STRUCTURE.mdAnnotated directory tree showing what lives where and why. Maps directories to responsibilities.
docs/ARCHITECTURE.mdHow components connect. Data flow, request lifecycle, key abstractions, dependency graph between modules.

Situational Files (generate when relevant)

FileWhen to IncludePurpose
docs/DATA_MODEL.mdProject has a database, ORM, or significant data structuresSchema overview, entity relationships, key types/interfaces
docs/API.mdProject exposes or consumes APIsEndpoints, request/response shapes, auth patterns
docs/CONFIGURATION.mdNon-trivial config (env vars, feature flags, multi-environment)All configuration knobs, defaults, and where they're used
docs/PATTERNS.mdProject uses recurring patterns worth documentingDesign patterns, conventions, error handling strategy, logging approach
docs/DEPLOYMENT.mdProject has deployment infrastructureBuild process, environments, CI/CD, infrastructure overview
docs/DEVELOPMENT.mdProject has non-obvious dev setup or workflowLocal setup, testing strategy, debugging tips, contribution workflow
docs/GLOSSARY.mdDomain-specific or project-specific terminologyTerm definitions that an AI agent needs to understand the codebase

Index File

Always generate docs/INDEX.md as the last file. This is a table of contents linking all other docs with one-line descriptions. An AI agent uses this to decide which file to read for a given question.

Step 3: Writing Guidelines

Follow these principles for every file:

Structure for Scannability

  • Start each file with a 2-3 sentence summary of what it covers
  • Use headers (##, ###) to create clear sections
  • Keep paragraphs short — 2-4 sentences max
  • Use code blocks for file paths, commands, and type signatures
  • Use tables for structured comparisons or listings

Write for AI Agents

  • Be explicit about relationships — "Module A calls Module B's process() method when..."
  • Include file paths — always reference actual paths like src/auth/middleware.ts
  • Name functions and classes that are key entry points or interfaces
  • Describe data flow with clear directionality — "User request → Router → Controller → Service → Repository → Database"
  • State assumptions and constraints — "This service assumes a PostgreSQL connection is available"

Keep It Maintainable

  • Include a Last updated date at the top of each file
  • Add a brief ## Changes Log section at the bottom of each file with space for noting updates
  • Reference specific file paths so staleness is detectable — if a referenced file moves, the docs are clearly wrong
  • Prefer describing intent and architecture over implementation details that change frequently

What NOT to Document

  • Don't duplicate what's already in README.md — reference it instead
  • Don't document every function — focus on public interfaces and key internal abstractions
  • Don't copy-paste code — describe what it does and where to find it
  • Don't document generated files or node_modules

Step 4: Updating Existing Docs

When updating rather than creating from scratch:

  1. Read all existing files in docs/ first
  2. Re-scan the codebase to detect changes since the docs were last updated
  3. Update affected files only — don't rewrite everything
  4. Update the Last updated date and add a note to the Changes Log
  5. Update docs/INDEX.md if any files were added or removed
  6. If a documented file has been deleted or moved, update or remove the reference

Step 5: Validation

After generating or updating docs, do a quick sanity check:

  1. Verify all file paths mentioned in docs actually exist
  2. Confirm the directory tree in STRUCTURE.md matches reality
  3. Ensure INDEX.md links to all docs that were created
  4. Check that cross-references between doc files are correct

Output

All files go in the docs/ directory at the project root. Use the exact filenames specified above (UPPERCASE with .md extension). Present the full set to the user when done, summarizing what was created and any areas where the docs might need human review (e.g., business logic descriptions, architectural decisions that aren't obvious from code alone).

rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 465kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall