Codebase Knowledge Skills

A family of five Claude Code / Cowork skills that scan a codebase and produce focused Markdown reference documents — one skill per area, each saving its own file.

The goal: give Claude (and humans) a fast, accurate working understanding of an unfamiliar codebase by writing it down in a consistent, structured format.

The five skills

Skill	Output	What it captures
codebase-overview	docs/codebase-overview.md	Architecture, tech stack, directory layout, key design decisions, current branch / in-flight work, deployment
codebase-conventions	docs/conventions.md	File naming, function/class naming, type conventions, export patterns, recurring code patterns
codebase-testing-guide	docs/testing-guide.md	Test framework, structure, mocking strategy, fixtures, helpers, coverage, notable patterns
codebase-error-handling	docs/error-handling.md	Error type hierarchy, propagation, logging, observability, user-facing error surfaces
codebase-glossary	docs/glossary.md	Domain terms, acronyms, status/enum values, scope strings

Each skill is independent. You can run any one against any codebase, in any order.

Install

Skills live at one of two locations:

• Global (recommended): ~/.claude/skills/<skill-name>/SKILL.md — applies to every project on your machine.
• Project-scoped: <project>/.claude/skills/<skill-name>/SKILL.md — applies only to that project.

Folder names must exactly match the name: field in each skill's frontmatter, and the file inside must be exactly SKILL.md (no prefix, no project name).

For a global install:

# Clone or download this repo, then from its root:
mkdir -p ~/.claude/skills
cp -r codebase-overview        ~/.claude/skills/
cp -r codebase-conventions     ~/.claude/skills/
cp -r codebase-testing-guide   ~/.claude/skills/
cp -r codebase-error-handling  ~/.claude/skills/
cp -r codebase-glossary        ~/.claude/skills/

Then restart your Claude session so the skill loader picks up the new files.

Verify the install:

ls ~/.claude/skills/codebase-overview/   # should show exactly: SKILL.md

If a skill isn't detected after restart, check:

• Folder name matches the skill's name: field exactly (no -SKILL suffix)
• The file inside is named exactly SKILL.md
• You fully restarted the Claude session (not just opened a new conversation)

Usage

Each skill is triggered by natural-language prompts. Example invocations:

• codebase-overview → "use the codebase-overview skill on this project"
• codebase-conventions → "what are the naming conventions in this project?"
• codebase-testing-guide → "use the codebase-testing-guide skill on this project"
• codebase-error-handling → "document the error handling in this codebase"
• codebase-glossary → "build a glossary for this project"

Run each in a fresh session for cleanest results. Context bleed from a previous skill in the same session can affect quality.

When a skill runs successfully, you'll see Claude make tool calls (reading files, running git/grep, writing the output Markdown) and a file will appear in docs/. If you only get a chat-only response with no tool activity, the skill didn't trigger — usually an install issue.

Recommended order for a new codebase

1. codebase-overview first — gives you the lay of the land.
2. codebase-conventions and codebase-glossary — surface the project's specific vocabulary and patterns.
3. codebase-error-handling and codebase-testing-guide — depth on operational concerns.

You don't have to run all five. Each one is useful on its own.

Tested ecosystems

Validated across:

• TypeScript / React / Firebase Cloud Functions (SaaS app, ~500 files)
• Python / Click / Pydantic (CLI tool, ~150 files)
• Dart / Flutter (mobile app, ~10 files, no git history)
• TypeScript open-source library (Hono, ~700 files, mature/opinionated)

The bash detection commands in each skill explicitly handle TypeScript, JavaScript, Python, Go, Rust, Dart, Java, and Ruby. Other languages may produce thinner output until the scan commands are extended.

Design philosophy

These skills are intentionally narrow. The original design was a single skill producing a comprehensive ~600-line reference document covering all five areas at once. Across four iterations of escalating prompt enforcement — moving the template to the top, adding a verification checklist, restructuring as a step-by-step procedure with mandatory tool calls — that monolithic skill consistently failed to follow its own structure. The model defaulted to producing a freeform chat summary regardless of how strict the template was.

Splitting into narrow-scope skills bypassed the failure mode. When the request is "extract the naming conventions," there's nothing to summarize down to — the model has to do the actual extraction work and save the file. Each skill in this family has one specific job and produces one specific file. Combined output across the five skills is deeper than the monolithic version ever produced.

The lesson generalizes: broad asks produce broad summaries; narrow asks produce specific outputs. If you're building a Claude skill that needs to produce many distinct deliverables, split it.

Sample outputs

See the examples/hono/ folder for real outputs from running all five skills against Hono, a popular TypeScript web framework (~700 source files):

• codebase-overview.md — architecture, tech stack, traced flow, design decisions
• conventions.md — naming patterns, export style, recurring code patterns
• testing-guide.md — Vitest multi-project setup, four-approach mocking, notable patterns
• error-handling.md — HTTPException hierarchy, duck-typed error contract, error flow
• glossary.md — Env/Bindings/Variables distinction, status code type taxonomy

Each output file follows the same general pattern: a title and > Auto-generated by codebase-{name} on {date} attribution, every section populated, and real, copy-pasteable code snippets and file paths from the actual codebase.

Known limitations

• Large monorepos: codebase-overview has logic to split into per-package output above ~500 files, but it hasn't been heavily exercised on real monorepos.
• Non-mainstream languages: Scan commands target TS/JS/Python/Go/Rust/Dart/Java/Ruby. Codebases in less common languages (Elixir, OCaml, Haskell, etc.) may produce thinner output.
• Repos without git history: Skills handle this gracefully (the doc will say "not a git repository") but lose access to branch/commit/in-flight work info.
• Small or inconsistent codebases: The skills prefer "no clear pattern detected" over inventing conventions — small projects may have shorter outputs as a result.

Contributing

Issues and PRs welcome. The most useful contributions:

• Test runs on languages/ecosystems not in the validated list above (Go services, Java/Spring, Rust, Ruby/Rails, etc.) — share the resulting docs and any rough edges you hit.
• Scan command improvements for languages where the current output is thin.
• New sister skills following the same narrow-scope pattern (suggestions: codebase-deployment, codebase-data-model, codebase-security).

License

MIT