understand-codebase

understand-codebase is a portable coding-agent skill for learning unfamiliar projects. It guides an agent to inspect a repository and produce one complete PROJECT_CODE_GUIDE.md.

The skill now supports two guide modes:

• Engineer Fast-Start: for engineers who need a README-style runbook to run, test, debug, modify, or quickly onboard to a project.
• Beginner Full Runtime Code Walkthrough: for learners who want a project learning route plus a full-flow, line-level explanation of the actual execution path, including exact lines or line ranges, code goals, libraries/methods, inputs, outputs, shape/schema, and the next code path.

Both modes read README/docs first when available, extract the project's operating model, and then use a PLAN-style workflow map before detailed analysis: goal, workflow coverage, command/config/input contracts, runtime stages, output contracts, validation/error cases, and explicit conventions. This makes the generated guide useful as both a study path and a maintenance reference.

The generated PROJECT_CODE_GUIDE.md has no artificial length limit. The guide should stay navigable, but detailed sections should stay detailed when they are needed to understand, run, debug, or modify the code.

The guide defaults to English. If the user requests another language, or appears to prefer another language, the agent should ask whether to keep English or switch.

Repository Layout

understand-codebase/
  SKILL.md
  agents/openai.yaml
  references/
    analysis-checklist.md
    project-guide-template.md
adapters/
  AGENTS-understand-codebase.md
  cursor-understand-codebase.mdc

Install

Codex

Copy the understand-codebase/ folder into your Codex skills directory, such as:

~/.codex/skills/understand-codebase/

If you use a custom CODEX_HOME, place it under:

$CODEX_HOME/skills/understand-codebase/

Claude Code

Copy the understand-codebase/ folder into a Claude Code skills location:

~/.claude/skills/understand-codebase/

For project-only usage, copy it into:

.claude/skills/understand-codebase/

Cursor

For Cursor Project Rules, copy:

adapters/cursor-understand-codebase.mdc

to:

.cursor/rules/understand-codebase.mdc

For a simpler project-level instruction file, copy:

adapters/AGENTS-understand-codebase.md

to your project root as:

AGENTS.md

Usage Examples

Engineer Fast-Start:

Use understand-codebase to create an engineer fast-start guide so I can run tests and modify this project.

Beginner Full Runtime Code Walkthrough:

Use understand-codebase to create a beginner full runtime code walkthrough. Explain the actual execution path line by line or line-range by line-range, including code goals, libraries/methods, inputs, outputs, and next code path.

Composite project with default path:

Help me understand this inference framework. Default path is fine.

Shape-focused:

Generate a beginner-friendly guide for this training project, including input and output shapes.

Output

The skill writes one file by default:

PROJECT_CODE_GUIDE.md

It should clearly label what was confirmed from code, what was runtime verified, what was statically inferred, and what remains unknown.

When README/docs exist, the guide should also compare important documentation claims against code evidence and flag mismatches or unknowns.