learn-codebase skill
A Socratic tutor that teaches a codebase through questions and recall, keeping progress in a learning journal.
- 106 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The skill drives a conversation and writes only the learning journal in the project.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/learn-codebaseDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The skill drives a conversation and writes only the learning journal in the project.
This is third-party code. Review the repository files before installing.
What it does
learn-codebase is an anti-vibe-coding skill: the agent does not hand over answers but leads you through a project with questions. It first asks what you want to learn, then asks you to predict a result before showing code, so a gap in understanding cannot slip by. When it notices a misunderstanding, for example about `AbortController`, it explains briefly and returns to questions. Progress lives in the `.claude/learning-journal.md` journal: which topics you know confidently and where you still bluff. In a new session the agent reads the journal and continues where you stopped. A session ends with concrete options for next steps. The skill is called with `/learn-codebase` in the project you need to understand.
Who it is for. Engineers joining an unfamiliar or mature repository and contributors preparing their first serious pull request.
Good fit when
- A new hire must understand the architecture of a large monorepo within a week.
- Before refactoring a legacy module you need to check that you understand it rather than guess.
- An author prepares a pull request and wants to defend it in review without false confidence.
- Sessions happen with breaks and the agent must remember what has been covered.
Not a fit when
- You need a quick patch with no explanations: the regular agent mode fits better.
- You are prototyping from scratch where speed matters more than depth.
- You want finished code: the skill asks questions first and answers later.
Example request
/learn-codebase — help me understand the architecture before I touch code, and quiz me with questions.Limitations
The skill leads a session with questions, so do not expect a quick answer: it optimizes retention, not speed. The journal sits in the project at `.claude/learning-journal.md` and should stay out of the shared repository if the notes are personal. Claude Code input suggestions give answers away early and the skill cannot turn them off: switch them off through `/config` or the `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false` variable. The skill reminds you once per project.
How to disable. Delete the skill folder from the skills directory (`~/.claude/skills/learn-codebase` or `.claude/skills/learn-codebase`). The `.claude/learning-journal.md` file stays in the project and is removed by hand.
FAQ
How do I install the skill?
Run `npx skills add ktaletsk/learn-codebase -g` for all projects or without `-g` for the current one. Pick an agent with the `-a` flag, for example `-a cursor`.
How do I install it manually?
Run `git clone https://github.com/ktaletsk/learn-codebase ~/.claude/skills/learn-codebase` for a personal skill or clone into the project's `.claude/skills/`.
How do I start a session?
Open the project you want to study and call `/learn-codebase`. The agent asks about your goal: a feature, a bug or a review.
What does the learning journal hold?
Topics you know confidently, those with gaps and moments of insight. The next session continues from them.
How do I update the skill?
Run `npx skills update`, adding `-g` for a global install.
Discussion
No questions or reviews yet.
Related
SkillsA Claude Code and Codex skill that offers short learning exercises during coding so the developer builds expertise, not just accepts generated code
With rederive, the agent asks questions that help a learner reconstruct the reasoning behind a codebase’s design decisions.
OwnYourCode makes Claude Code a mentor: the agent asks and reviews, and the human writes the code and understands every line
A set of 11 skills for Claude Code, Codex and others: from understanding the task to a live site URL and a final report.
A skill that runs a full refactor so agents read code more easily: it finds hidden links and needless dependencies.
A Claude Code skill that delegates tasks to OpenAI's Codex CLI for code analysis, review and edits
README in short
The repository has the `SKILL.md` skill, the `JOURNAL-TEMPLATE.md` journal template, `QUESTION-PATTERNS.md` question patterns and READMEs in English and Chinese. The method rests on Socratic questions, prediction before an answer and active recall.
README badge
Original SKILL.md
---
name: learn-codebase
description: >
Socratic tutor that teaches codebase understanding through questioning,
challenges, and active recall. Invoke with /learn-codebase when onboarding
to a new codebase or deepening understanding of existing code.
Maintains a learning journal that tracks mastery and schedules reviews.
disable-model-invocation: true
---
# Codebase Learning Tutor
You are a Socratic tutor helping the user deeply understand this codebase. Your
primary goal is to BUILD UNDERSTANDING IN THE USER'S HEAD through questioning
and active recall—not to simply answer questions or generate code.
## Core Philosophy
**Ask before telling.** Always give the learner a chance to figure things out.
**Predict before revealing.** Have them predict behavior before showing execution.
**Challenge productively.** Questions should be just beyond current ability.
**Track progress.** Update the learning journal frequently—don't wait until session end.
**Find their angle.** Discover what aspects genuinely interest the learner.
**Keep it concise.** Short responses, more exchanges. Don't lecture.
## Using AskUserQuestion Tool
Use the `AskUserQuestion` tool for structured choices. It renders a nice multiple-choice UI in the terminal, making interactions smoother.
**When to use it:**
- Interest discovery (goal, learning style)
- Session focus selection
- Quiz questions with discrete answers
- Session end options (continue, pause, switch topics)
- Difficulty calibration ("Was that too easy / just right / too hard?")
**Example usage for session start:**
```
AskUserQuestion with:
- question: "What's your goal with this codebase?"
- options: ["Contributing features", "Fixing bugs", "Code review", "General exploration"]
```
**Example for session end:**
```