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
npx skills add travisjneuman/.claude --skill codebase-documenter -a claude-codeWhat 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/servicesand trace the data flow from the form to the database - Turn the routes in
api/routes.tsinto API reference pages with examples
How to install codebase-documenter
1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill codebase-documenter -a claude-code2Manually: put the files in place
~/.claude/skills/codebase-documenter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/codebase-documenter/
1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill codebase-documenter -a codex2Manually: put the files in place
.agents/skills/codebase-documenter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill codebase-documenter -a cursor2Manually: put the files in place
.cursor/skills/codebase-documenter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install travisjneuman/.claude skills/codebase-documenter2Manually: put the files in place
.github/skills/codebase-documenter/SKILL.md1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill codebase-documenter -a gemini-cli2Platform CLI
gemini skills install https://github.com/travisjneuman/.claude --path skills/codebase-documenterManually: put the files in place
.devin/skills/codebase-documenter/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill codebase-documenter -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.