New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Codebase Docs

by espennilsen in espennilsen/pi

Generate and maintain AI-readable markdown documentation for a codebase in docs/.

MITAuto-check passedDevelopment

Install Codebase Docs

skills CLI
$ npx skills add espennilsen/pi --skill codebase-docs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install espennilsen/pi codebase-docs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/espennilsen/pi.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/codebase-docs .claude/skills/codebase-docs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
codebase-docs
GitHub stars
122
Token cost
~1.8k tokens
SKILL.md length
881 words
Files
2 (incl. references)
Skills in repo
36
Repo updated
First seen
Licence
MIT

At a glance

Generate and maintain AI-readable markdown documentation for a codebase in docs/.

  • Works in 5 steps: Assess the Codebase → Generate the Documentation Set → Writing Guidelines → …
  • The user asks to document their codebase
  • SKILL.md covers Philosophy, When to Use This Skill, Step 1: Assess the Codebase and Step 2: Generate the…, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Codebase Docs is an agent skill from espennilsen/pi. 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…

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/doc-templates.md`).

It sits in Development, covering Technical documentation, Codebase onboarding and Project scaffolding. The licence is MIT.

When your agent uses it

  • The user asks to document their codebase
  • Generate project docs
  • Create architecture docs
  • Update documentation after code changes

Example prompts

  • “document this repo”
  • “create docs for my project”
  • “update the docs”
  • “/codebase-docs”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Assess the Codebase
  2. Generate the Documentation Set
  3. Writing Guidelines
  4. Updating Existing Docs
  5. Validation

What it can do on your machine

Read from SKILL.md and the folder at commit 79d019b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Codebase Docs loads about 1.8k tokens when it runs, and up to ~4.9k if it reads all its reference files. Until then it costs about 202 tokens; SKILL.md has 881 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~202
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from espennilsen/pi at commit 79d019b, republished under its MIT licence (© espennilsen). 881 words, ~1,847 tokens.

Download SKILL.mdSave it as .claude/skills/codebase-docs/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
codebase-docs
description
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
Show full SKILL.md (352 more words)Show less
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).

© espennilsen, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in skills/codebase-docs of espennilsen/pi.

  • SKILL.md
  • references/doc-templates.md

Open the folder on GitHubat commit 79d019b

Compare with similar skills

Codebase Docs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Codebase Docs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Codebase Docs this skillespennilsen/pi122—~1.8kAutomated safety check: PassMIT
Project Docsjezweb/claude-skills1.1k—~1.6kAutomated safety check: NotesMIT
Project Onboarding Guide from Knowledge GraphEgonex-AI/Understand-Anything85k—~1.2kAutomated safety check: PassMIT
Deepwiki Rssopaco/deepwiki-rs3.1k—~748Automated safety check: PassMIT
Acquire Codebase Knowledgegithub/awesome-copilot40k1 repos~2.3kAutomated safety check: PassMIT
Qwen Agentthananon/9arm-skills3.2k—~1.5kAutomated safety check: PassNone

Similar skills

  • Project Docs

    jezweb/claude-skills

    Generate project documentation from codebase analysis — ARCHITECTURE.md, APIENDPOINTS.md, DATABASESCHEMA.md.

    1.1k GitHub stars~1.6k tokensUpdated 2 days ago
    DatabasesAuto-check: notes

  • Project Onboarding Guide from Knowledge Graph

    Egonex-AI/Understand-Anything

    Writes an onboarding guide for new team members from a project's existing knowledge graph, after checking that the graph still matches the current commit.

    85k GitHub stars~1.2k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Deepwiki Rs

    sopaco/deepwiki-rs

    AI-powered Rust documentation generation engine for comprehensive codebase analysis, C4 architecture diagrams, and automated technical documentation.

    3.1k GitHub stars~748 tokensUpdated 23 days ago
    DevelopmentAuto-check passed

  • Acquire Codebase Knowledge

    github/awesome-copilot

    Official

    Maps an unfamiliar codebase into seven evidence-backed documents in docs/codebase/, using a scan script and templates, for onboarding or architecture write-ups.

    40k GitHub starsUsed in 1 repo~2.3k tokens
    DevelopmentAuto-check passed

  • Qwen Agent

    thananon/9arm-skills

    Delegate menial, well-scoped coding tasks to a cheap Qwen-backed subagent via the claude-9arm command instead of burning Claude tokens/quota.

    3.2k GitHub stars~1.5k tokensUpdated 3 mo ago
    DevelopmentAuto-check passed

  • README and DESIGN Generator

    fengshao1227/ccg-workflow

    Generates README.md and DESIGN.md skeletons for a module by scanning its structure with a Node script, then lists what to fill in by hand.

    5.9k GitHub stars~410 tokensUpdated 22 days ago
    DevelopmentAuto-check: notes

More from espennilsen/pi

All 36 skills in this repo

  • GitHub

    espennilsen/pi

    Interact with GitHub repos, PRs, issues, CI, and notifications via the pi-github extension commands and gh CLI.

    122 GitHub stars~1k tokensUpdated 16 days ago
    Auto-check passed

  • Skill Creator

    espennilsen/pi

    Create, review, and improve skills for Pi agents. An agent skill from espennilsen/pi.

    122 GitHub stars~2.1k tokensUpdated 16 days ago
    Auto-check passed

  • Dry Code Review

    espennilsen/pi

    Perform a comprehensive DRY (Don't Repeat Yourself) code review on a codebase.

    122 GitHub stars~1.7k tokensUpdated 16 days ago
    Auto-check passed

  • Extract Design System

    espennilsen/pi

    Reverse-engineer a design system from a live website (public URL or localhost).

    122 GitHub stars~2k tokensUpdated 16 days ago
    Auto-check passed

  • PDF Reader

    espennilsen/pi

    Read and extract content from PDF files — text, tables, metadata, and images.

    122 GitHub stars~1.6k tokensUpdated 16 days ago
    Auto-check passed

  • Google Workspace

    espennilsen/pi

    Manage Google Workspace via the gws CLI — Drive, Gmail, Sheets, Docs, Slides, People, Chat, Meet, Forms, and cross-service workflows.

    122 GitHub stars~3.4k tokensUpdated 16 days ago
    Auto-check passed

Categories

Questions about Codebase Docs

What does Codebase Docs do?

Generate and maintain AI-readable markdown documentation for a codebase in docs/. Codebase Docs is an agent skill from espennilsen/pi. Generate and maintain AI-readable markdown documentation for a codebase in docs/.

When should I use Codebase Docs?

Codebase Docs fits situations like: the user asks to document their codebase; generate project docs; create architecture docs; update documentation after code changes.

How do I install Codebase Docs in Claude Code?

Run `npx skills add espennilsen/pi --skill codebase-docs -a claude-code`. Or copy the skill folder (skills/codebase-docs in espennilsen/pi) into .claude/skills/codebase-docs in your project. Claude Code loads it when a task matches its description.

How do I install Codebase Docs in Codex?

Run `npx skills add espennilsen/pi --skill codebase-docs -a codex`. Or copy the skill folder (skills/codebase-docs in espennilsen/pi) into .agents/skills/codebase-docs in your project. Codex loads it when a task matches its description.

Can I use Codebase Docs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add espennilsen/pi --skill codebase-docs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/codebase-docs, .gemini/skills/codebase-docs, .github/skills/codebase-docs and .opencode/skills/codebase-docs in your project.

What does Codebase Docs need to run?

SKILL.md names no scripts, command-line tools or credentials: Codebase Docs is instructions for the agent only.

Does Codebase Docs access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Codebase Docs safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Codebase Docs use?

Codebase Docs is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Codebase Docs use?

About 1.8k tokens (SKILL.md is roughly 7.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3k tokens, read only when the agent opens those files.

What are the alternatives to Codebase Docs?

Skills that share tags, products or a category with Codebase Docs: Project Docs (jezweb/claude-skills, 1.1k stars), Project Onboarding Guide from Knowledge Graph (Egonex-AI/Understand-Anything, 85k stars), Deepwiki Rs (sopaco/deepwiki-rs, 3.1k stars) and Acquire Codebase Knowledge (github/awesome-copilot, 40k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Codebase Docs?

espennilsen (a GitHub user) maintains it in espennilsen/pi, which has 122 GitHub stars. The repository holds 36 skills in this directory. The repository was last updated on September 21, 2026.

Source: espennilsen/pi on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.