🧭 learning-codebases

From “I can read Python” to “I can explain this system.”

A token-aware Codex Skill that turns unfamiliar repositories into evidence-backed, beginner-friendly learning journeys.

中文 · Install · How it works · Safety

---

Most codebase explainers do one of two things:

• dump the directory tree and call it “architecture”; or
• explain everything at once until the context window—and the learner—are exhausted.

learning-codebases takes a different path. It finds the active entry point, follows one real execution or data flow, explains unfamiliar ideas at the learner’s level, and stops when the next useful mental model is complete.

The goal is not to make AI read the repository for you.
The goal is to help you become able to navigate, explain, and question it.

What makes it different

🧩 Beginner-first	Assumes basic Python—not framework knowledge, architecture jargon, or another language.
🔎 Evidence-backed	Anchors important claims to real paths and symbols, and separates code, runtime, docs, inference, and unknowns.
🧵 Flow before files	Traces one real request, training loop, data pipeline, or agent workflow before expanding.
🧠 Built for retention	Uses a light explain → predict → inspect → verify → restate loop.
⚖️ Token-aware	Reads the smallest useful evidence set, reuses verified context, and expands only when the goal requires it.
🔐 Private-repo conscious	Keeps private source out of web searches and never creates learning files without permission.

Install

git clone https://github.com/Eijnewgnaw/learning-codebases.git
mkdir -p ~/.codex/skills
cp -R learning-codebases/skill/learning-codebases ~/.codex/skills/

Start a new Codex task, then say:

I only know basic Python. Help me learn this project.
Start with its input, processing, and output, then choose one real call path.

Or invoke it explicitly:

Use $learning-codebases to guide me through this repository.

How it works

flowchart LR
    A["Your learning goal"] --> B["Cheap repository inventory"]
    B --> C["Compact project compass"]
    C --> D["One real execution or data flow"]
    D --> E["Explain at your level"]
    E --> F["Inspect and verify"]
    F --> G["One learning checkpoint"]
    G --> H{"Go deeper?"}
    H -- "Not yet" --> I["Stop with a clear next step"]
    H -- "Yes" --> J["Expand one evidence hop"]
    J --> D

Loading

The Skill does not begin by reading everything. It first checks repository instructions, manifests, startup commands, tests, and targeted symbols. It then selects the minimum files needed to support the next useful learning unit.

Three depth modes

Mode	Best for	You get
Quick	Orientation or a short question	Purpose, active entry, one flow, unknowns
Standard	Most learning sessions	Project compass, one supported flow, essential concepts, checkpoint
Deep	Preparing a change or defending the design	Tests, alternatives, errors, runtime checks, more subsystems

Standard is the default. You can switch at any time:

Give me the quick version.

Go deep—I need to modify this module safely.

A learning unit looks like this

1. What this module is for
2. Input → processing → output
3. The real path and symbol
4. What changes before and after the key code block
5. One beginner-friendly concept
6. One short understanding check
7. Why the analysis stopped, and what to inspect next

For non-Python projects, the Skill explains the language-independent responsibility first, maps it to familiar Python, states where the analogy breaks, and then returns to the real implementation.

Evidence, not vibes

The Skill distinguishes:

• Code-confirmed — visible in current code and wiring
• Runtime-confirmed — observed through a command, test, log, or process
• Documented — stated by project docs but not independently verified
• Inferred — reasoned from evidence
• Unknown — needs more code, environment, data, credentials, or execution

It never claims to have run something that was only read.

Token-aware by design

This project does not use a rigid token cap. Hard caps often save context by sacrificing the exact evidence a learner needs.

Instead, it follows four rules:

1. Inventory cheaply before opening broad source context.
2. Read the minimum evidence set for the current learning unit.
3. Reuse verified findings while the repository revision is unchanged.
4. Stop with an honest unknown instead of guessing to save tokens.

When two explanations are equally correct, the shorter and narrower one wins. Correctness never loses to cost.

Safe for real-world codebases

By default, learning-codebases:

• inspects repositories read-only;
• keeps private code and internal identifiers out of web queries;
• does not upload repositories to third-party analysis sites;
• does not echo secret values;
• does not install dependencies or access production systems implicitly;
• asks before creating a learning journal;
• recommends external learning-state storage for company repositories.

This Skill does not replace the underlying Codex product’s data-handling contract. It prevents additional disclosure through tools, searches, and generated artifacts.

Project structure

learning-codebases/
├── README.md
├── README.zh-CN.md
├── LICENSE
├── eval/
│   ├── rubric.md
│   └── scenarios.md
└── skill/
    └── learning-codebases/
        ├── SKILL.md
        ├── agents/
        │   └── openai.yaml
        └── references/
            ├── repository-analysis.md
            ├── beginner-teaching.md
            └── lesson-templates.md

The installable Skill stays intentionally small: a 416-word core plus three references loaded only when needed.

Example prompts

Help me understand the architecture before I touch anything.

Trace what happens after a user submits this form. I only know basic Python.

Explain this TypeScript module using Python analogies, but tell me where the analogy is inaccurate.

I will ask the questions. Answer from the active code path and label anything not verified.

Turn today's session into a five-minute review, but do not write files into this company repo.

Validation

The repository includes a reusable 14-point rubric and realistic scenarios covering:

• a Python CLI;
• a large Python web framework;
• an agentic knowledge project;
• missing runtime prerequisites;
• non-Python explanation;
• private-repository boundaries;
• context and output efficiency.

Validate the Skill structure with:

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skill/learning-codebases

Contributing

Issues and pull requests are welcome—especially:

• learning transcripts that expose confusing behavior;
• better beginner analogies with clear limits;
• new codebase types and evaluation scenarios;
• improvements that reduce context without reducing evidence quality.

Please keep the core concise. Put detailed guidance in a reference file and add a scenario that proves the change helps.

License

MIT © 2026 WangWenJie

---

Read less blindly. Understand more deeply.

If this helps you finally feel at home in an unfamiliar repository, consider giving it a ⭐.