Skip to main content
skill CX Codex

codebase-documenter · travisjneuman — Claude Code skill: README, architecture

codebase-documenter turns a repository into readable docs: README, architecture overview, onboarding guide, API reference and code comments. Handy when someone new has to understand the project.

MIT 145 installs ★ 114 updated 2026-11-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add travisjneuman/.claude --skill codebase-documenter -a claude-code
Open on GitHub

What codebase-documenter does

The skill walks a repository and gathers what it needs: entry points, dependencies, configuration, core abstractions. Then it picks a document type in order — README, architecture, API, comments — fills a template for that project and runs a check. Purpose comes before implementation in the text it writes.

Templates ship with it: a README with quick start and a file tree, an architecture page with data flow and design decisions, an ADR format with trade-offs, good and bad comment examples. There is a pre-publish checklist too: examples copy-paste cleanly, paths and links resolve, jargon is defined. Alongside it, a list of usual failures such as stale samples or missing prerequisites.

Verification is a reading pass. Examples get compared against the current code and paths, not executed, so a snippet that no longer parses can still pass. Review, UX calls and feature work are out of scope; the skill sends those to generic-code-reviewer, generic-ux-designer and generic-feature-developer.

What it helps with

  • write a README that gets the project running in 5 minutes
  • map the architecture and data flow into a diagram
  • document endpoints with request and response samples
  • rewrite comments so they explain the reason behind the code
  • run the pre-publish checklist over existing docs

Example prompts for the agent

  • Document this repo: a README with quick start and a file tree
  • Write architecture docs for src/services and trace the data flow from the form to the database
  • Turn the routes in api/routes.ts into API reference pages with examples

How to install codebase-documenter

1Skills CLI (Vercel)

npx skills add travisjneuman/.claude --skill codebase-documenter -a claude-code

2Manually: put the files in place

~/.claude/skills/codebase-documenter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codebase-documenter/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about codebase-documenter

How do I install codebase-documenter in Claude Code?

Run npx skills add travisjneuman/.claude --skill codebase-documenter -a claude-code. The skill lands in ~/.claude/skills/codebase-documenter/SKILL.md.

What does codebase-documenter do?

It writes docs from the code: README, architecture notes, an onboarding guide, API reference and inline comments. The loop is analysis, document type, template output, verification.

Does it review code as well?

No. Code review goes to generic-code-reviewer, UX decisions to generic-ux-designer, feature work to generic-feature-developer.

Source text

SKILL.md · MIT
---
name: codebase-documenter
description: "Write codebase documentation: READMEs, architecture docs, getting-started guides, API docs, and code comments. Use when documenting code or making a project easier for new developers."
context: fork
background: false
---

# Codebase Documenter

Create comprehensive, beginner-friendly documentation for any codebase.

## When to Use

**Use for:**

- Writing or updating README files
- Creating architecture documentation
- Adding meaningful code comments
- Documenting APIs and endpoints
- Creating getting-started guides
- Explaining project structure

**Don't use when:**

- Code review → use `generic-code-reviewer`
- UX design decisions → use `generic-ux-designer`
- Adding code features → use `generic-feature-developer`

## Core Principles

1. **Start with "Why"** - Explain purpose before implementation
2. **Progressive Disclosure** - Simple to complex
3. **Provide Context** - Why code exists, not just what it does
4. **Include Examples** - Concrete usage for every concept
5. **Assume No Prior Knowledge** - Define terms, avoid jargon
6. **Visual Aids** - Diagrams, file trees, flowcharts
7. **Quick Wins** - Get something running in 5 minutes

## Documentation Workflow

First follow [Memory and documentation](../../CLAUDE.md#memory-and-documentation) to update the owning subject note before generating repository documentation. The templates below describe public code/contributor docs, not default destinations for private project knowledge.

1. **Analyze** - Entry points, dependencies, core concepts, configuration
2. **Choose Type** - README → Architecture → API → Comments
3. **Generate** - Use templates, customize for project
4. **Verify** - Read as beginner, check examples against the code by reading

## Documentation Types

### README (Project Entry Point)

```markdown
# Project Name

## What This Does

[1-2 sentence explanation]

## Quick Start

[< 5 minute setup]

## Project Structure

[Visual file tree]

## Key Concepts

[Core abstractions]

## Common Tasks

[Step-by-step guides]
```

### Architecture Documentation

```markdown
# Architecture Overview

## System Design

[High-level diagram]

## Data Flow

[How data moves through system]

## Key Design Decisions

[Why certain choices were made]

## Extension Points

[Where to add new features]
```

### Code Comments

```typescript
// ✅ GOOD - Explains WHY and context
// IndexedDB quota check: Prevents silent failures when storage is full.
// Without this, writes fail with cryptic QuotaExceededError.
if (quota.percentUsed > 80) showStorageWarning();

// ❌ BAD - Just repeats what code does
// Check if quota is over 80
```

### API Documentation

```markdown
## Endpoint: POST /api/resource

### What It Does

[Plain-English purpose]

### Request/Response

[JSON examples]

### Common Errors

[Error codes and meanings]
```

## Visual Patterns

### File Tree

```
project/
├── src/                    # Source code
│   ├── components/        # Reusable UI
│   ├── services/          # Business logic
│   └── types/             # TypeScript types
├── tests/                 # Test files
└── package.json           # Dependencies
```

### Data Flow

```
User Request Flow:
1. User submits → 2. Validation → 3. API → 4. Database → 5. Response

[1] components/Form.tsx
    ↓ validates
[2] services/validation.ts
    ↓ calls API
[3] services/api.ts
    ↓ queries
[4] Database
    ↓ returns
[5] Form.tsx (updates UI)
```

### Design Decision (ADR)

```markdown
## Why We Use [Technology]

**Decision:** [What we chose]
**Context:** [Why we needed to choose]
**Reasoning:** [Why this option]
**Trade-offs:** [What we gave up]
```

## Documentation Quality Checklist

### Before Publishing

- [ ] Quick start works in < 5 minutes
- [ ] Code examples are copy-pasteable
- [ ] File paths are accurate
- [ ] Links work
- [ ] Jargon is defined
- [ ] Diagrams are included for complex flows

### Common Mistakes to Avoid

- Assuming reader knows the codebase
- Outdated code examples
- Missing prerequisites
- No visual aids for complex systems
- Explaining "what" without "why"

## Verification Workflow

After writing documentation:

1. **Fresh Eyes Test** - Read as if you've never seen the codebase
2. **Check Examples** - Read each example against the current code, APIs, and paths it uses
3. **Check Links** - All internal/external links resolve
4. **Beginner Review** - Would a new developer understand?
5. **Update Check** - Does it reflect current code?

## See Also

- [Code Review Standards](../_shared/CODE_REVIEW_STANDARDS.md) - Documentation quality
- Project `CLAUDE.md` - Documentation rules

## Your task

$ARGUMENTS

© travisjneuman · MIT · travisjneuman/.claude

Similar skills

All skills for Writing and docs →

codebase-documenter by other authors comes first.

codebase-documenter ailabs-393 codebase-documenter generates beginner-friendly README files, architecture guides, code comments, and API documentation. Helps onboarding developers grasp a project structure quickly. CX Codex +1 1,500installs codebase-documenter mhattingpete codebase-documenter — a skill for Claude Code and Cursor that walks a repository and writes documentation covering architecture, key components, data flow, and development guidelines. CX Codex +1 595installs doc-forge rohitg00 doc-forge — a Claude Code plugin that generates code documentation, API docs, and maintains README files. The agent invokes it when you work on project documentation. ★ 2,858repo stars documentation official anthropics documentation — a skill for technical writing that drafts READMEs, API references, runbooks, architecture docs and onboarding guides. Useful when the code exists but the description does not. CX Codex +1 10,800installs documentation-engineer zhaono1 documentation-engineer — a skill for writing technical documentation: READMEs, API references, code comments and architecture notes. Useful when the codebase has grown but the docs have not. CX Codex +1 722installs code-documentation-analyzer Jeremy Longshore Auto-activating skill for auditing code documentation: API references, user guides, architecture docs. Triggers on phrases like "code documentation analyzer" or "code analyzer". CX Codex +1 1installs documentation-templates davila7 The documentation-templates skill provides outlines and templates for READMEs, API references, code comments, and project records. Use it when starting documentation or bringing existing pages into a clearer structure. CX Codex +1 305installs gem-documentation-writer official github The gem-documentation-writer subagent for GitHub Copilot creates technical documentation, READMEs, API docs, and diagrams. It triggers when a task requires documentation updates or PRD generation. CX Codex +1 ★ 41,430repo stars

From the same set117

The whole set →
generic-react-code-reviewer generic-react-code-reviewer walks your React/TypeScript diff for bugs, security holes, render costs and accessibility gaps. Fits right before a commit or when a pull request lands on your desk. CX Codex +1 148installs security This Claude Code skill covers security architecture, incident response, and vulnerability assessment. It activates for security program design, incident handling, and reviews against frameworks such as NIST and ISO 27001. CX Codex +1 148installs generic-code-reviewer generic-code-reviewer inspects code diffs for security risks, runtime errors, bundle bloat, and WCAG AA gaps. It adapts checks to your project stack and enforces workflow rules from CLAUDE.md. CX Codex +1 147installs monitoring-observability monitoring-observability equips AI coding agents to set up OpenTelemetry, structured JSON logging, and distributed tracing. Useful when defining SLO alerts or instrumenting services. CX Codex +1 146installs impact-report-writer The impact-report-writer skill helps structure program impact reports, choose outcome metrics, and plan data visualizations. Use it for annual reports or program evaluations. CX Codex +1 145installs frontend-enhancer frontend-enhancer polishes the visual side of a web app: palette, layout, motion, component states. Useful when the UI still reads as a stock starter. CX Codex +1 145installs status-report-generator The status-report-generator Claude Code skill builds project status reports from Git activity, task context, and milestone tracking. It can create weekly updates, sprint reviews, and stakeholder reports. CX Codex +1 145installs generic-ux-designer generic-ux-designer — a UX skill for Claude and other coding agents: design-thinking steps, heuristic review and accessibility checks, packaged as checklists the agent follows. CX Codex +1 145installs

Project sponsors

Companies that keep this analytics open