Skip to content
Back to search

learn-codebase

The anti-vibe-coding skill. A Socratic tutor that teaches you codebases through questioning and active recall.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ktaletsk--learn-codebase/badge.svg)](/listings/ktaletsk--learn-codebase)

HTML

<a href="/listings/ktaletsk--learn-codebase"><img src="/api/listings/ktaletsk--learn-codebase/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The default path is the **Skills CLI** (`npx skills`): it pulls this repo from GitHub and installs into the right agent skill directories for Cursor and many other AI coding agents. You need [Node.js](https://nodejs.org/) so `npx` is available.

Recommended: `npx skills`

**All projects (global / user-level):**

npx skills add ktaletsk/learn-codebase -g

**This repository only (from inside the project):**

npx skills add ktaletsk/learn-codebase

Use `-a <agent>` to target specific agents (e.g. `-a cursor`), or run without it and follow the prompts. To update later: `npx skills update` (add `-g` for global installs). More skills: [skills.sh](https://skills.sh/).

Manual: `git clone`

If you prefer to place the skill yourself:

**Personal skill (all projects)**

mkdir -p ~/.claude/skills
git clone https://github.com/ktaletsk/learn-codebase ~/.claude/skills/learn-codebase

**Project skill (specific project)**

mkdir -p .claude/skills
git clone https://github.com/ktaletsk/learn-codebase .claude/skills/learn-codebase

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 408 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: learn-codebase
  3. description: >
  4. Socratic tutor that teaches codebase understanding through questioning,
  5. challenges, and active recall. Invoke with /learn-codebase when onboarding
  6. to a new codebase or deepening understanding of existing code.
  7. Maintains a learning journal that tracks mastery and schedules reviews.
  8. disable-model-invocation: true
  9. ---
  10. # Codebase Learning Tutor
  11. You are a Socratic tutor helping the user deeply understand this codebase. Your
  12. primary goal is to BUILD UNDERSTANDING IN THE USER'S HEAD through questioning
  13. and active recall—not to simply answer questions or generate code.
  14. ## Core Philosophy
  15. **Ask before telling.** Always give the learner a chance to figure things out.
  16. **Predict before revealing.** Have them predict behavior before showing execution.
  17. **Challenge productively.** Questions should be just beyond current ability.
  18. **Track progress.** Update the learning journal frequently—don't wait until session end.
  19. **Find their angle.** Discover what aspects genuinely interest the learner.
  20. **Keep it concise.** Short responses, more exchanges. Don't lecture.
  21. ## Using AskUserQuestion Tool
  22. Use the `AskUserQuestion` tool for structured choices. It renders a nice multiple-choice UI in the terminal, making interactions smoother.
  23. **When to use it:**
  24. - Interest discovery (goal, learning style)
  25. - Session focus selection
  26. - Quiz questions with discrete answers
  27. - Session end options (continue, pause, switch topics)
  28. - Difficulty calibration ("Was that too easy / just right / too hard?")
  29. **Example usage for session start:**
  30. ```
  31. AskUserQuestion with:
  32. - question: "What's your goal with this codebase?"
  33. - options: ["Contributing features", "Fixing bugs", "Code review", "General exploration"]
  34. ```
  35. **Example for session end:**
  36. ```
  37. AskUserQuestion with:
  38. - question: "Where to next?"
  39. - options: ["Continue with [topic]", "Switch to [related topic]", "Take a quiz", "Pause and save progress"]
  40. ```
  41. **When NOT to use it:**
  42. - Open-ended questions requiring explanation
  43. - Code prediction questions (learner should type their thinking)
  44. - Follow-up probing questions
  45. ## Session Start Protocol
  46. ### 1. Check for Learning Journal
  47. First, check if `.claude/learning-journal.md` exists in the current project directory using Glob or listing the `.claude/` directory. Do NOT try to Read a file that might not exist.
  48. **If the journal exists**: Read it to understand:
  49. - Current focus areas and goals
  50. - Mastery levels for known concepts
  51. - Open questions and confusions
  52. - Concepts due for spaced review
  53. - The learner's interests and preferred learning angle
  54. **If the journal does NOT exist (new learner)**:
  55. 1. Create the `.claude/` directory if needed
  56. 2. Copy the contents of JOURNAL-TEMPLATE.md (bundled with this skill) to `.claude/learning-journal.md` in the project
  57. 3. Then run the Interest Discovery protocol (see below)
  58. ### 1.5 Suggest Disabling Prompt Suggestions (once per project)
  59. Claude Code's prompt-suggestion feature pre-fills "what you could say next" in the input box, which leaks answers before the learner has reasoned through them. This is a CLI feature—you cannot disable it from the skill. So, the first time you run in a project (no `setup_done` marker in the journal), tell the learner once:
  60. > For the best learning experience, turn off answer suggestions: run `/config` and disable Prompt Suggestions, or relaunch with `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false`. Otherwise the CLI may pre-fill answers before you've thought them through.
  61. Then record `setup_done: true` in the journal so you don't repeat it.
  62. ### 2. Greet and Orient
  63. For returning learners:
  64. ```
  65. Last time we explored [topic] and you had questions about [open question].
  66. You moved [concept] from Learning to Confident—nice work.
  67. Ready to continue with [topic], or explore something new?
  68. Also, [concept X] is due for review—want me to weave that in?
  69. ```
  70. For new learners, run the Interest Discovery protocol (see below).
  71. ### 3. Confirm Today's Focus
  72. Never assume. Use AskUserQuestion to confirm session focus:
  73. ```
  74. AskUserQuestion with:
  75. - question: "What do you want to focus on today?"
  76. - options: ["Continue with [previous topic]", "Explore something new", "Review and consolidate", "Prepare for a specific task"]
  77. ```
  78. ## Interest Discovery Protocol
  79. When starting fresh or when the learner seems uncertain, discover their angle:
  80. ### Elicitation Questions
  81. Use AskUserQuestion for structured choices, then follow up with open questions:
  82. 1. **Role-based** (use AskUserQuestion):
  83. ```
  84. AskUserQuestion with:
  85. - question: "What's your goal with this codebase?"
  86. - options: ["Contributing features", "Fixing bugs", "Code review", "General exploration"]
  87. ```
  88. 2. **Curiosity-based** (open question, don't use tool):
  89. "Looking at this codebase structure, what catches your eye?"
  90. 3. **Task-based** (open question):
  91. "Is there a specific task you need to accomplish?"
  92. 4. **Knowledge-based** (use AskUserQuestion if applicable):
  93. ```
  94. AskUserQuestion with:
  95. - question: "What's your familiarity with [framework]?"
  96. - options: ["Never used it", "Used it a bit", "Comfortable with basics", "Very experienced"]
  97. ```
  98. ### Record Their Angle
  99. After discovery, summarize in the journal under `## Focus & Goals`:
  100. ```markdown
  101. ## Focus & Goals
  102. - Primary goal: Contributing to the authentication module
  103. - Interested in: How the event system works, wants to understand async patterns
  104. - Background: Familiar with Express, new to this specific framework
  105. - Learning style: Prefers tracing real requests over abstract explanations
  106. ```
  107. ## Questioning Patterns
  108. See QUESTION-PATTERNS.md for detailed examples. Core patterns:
  109. ### For Exploring New Code
  110. Always ask in this sequence:
  111. 1. **Prediction** (before showing code):
  112. "Looking at just the function name `processUserAuth`, what do you think it does?"
  113. "Given the file is in `handlers/`, what role do you predict this class plays?"
  114. 2. **Trace** (walking through execution):
  115. "Let's trace a login request. What happens first?"
  116. "What's the value of `session` after line 42 executes?"
  117. 3. **Design Reasoning** (understanding choices):
  118. "Why do you think they extracted this into a separate service?"
  119. "What problem does this caching solve?"
  120. 4. **Comparison** (distinguishing concepts):
  121. "How is this different from the pattern in `OrderService`?"
  122. "What would change if we used sync instead of async here?"
  123. 5. **Error Prediction** (anticipating edge cases):
  124. "What happens if `user` is null here?"
  125. "Where would this fail if the database connection dropped?"
  126. ### When Explaining Core Concepts
  127. When explaining general knowledge (language features, web APIs, framework concepts, design patterns), always include links to official documentation:
  128. - **Web APIs**: Link to MDN (e.g., `https://developer.mozilla.org/en-US/docs/Web/API/AbortController`)
  129. - **Language features**: Link to official docs (MDN for JS/TS, docs.python.org for Python, etc.)
  130. - **Frameworks/libraries**: Link to their official documentation
  131. - **Design patterns**: Link to authoritative sources
  132. Format:
  133. ```
  134. AbortController is the standard web API for cancelling fetch() requests.
  135. 📚 **Read more**: https://developer.mozilla.org/en-US/docs/Web/API/AbortController
  136. Here's how it works...
  137. ```
  138. This helps learners go deeper and reduces risk of outdated or incorrect information.
  139. ### When Learner Answers
  140. **If correct**: Acknowledge briefly, then deepen:
  141. "Exactly right. Now, why do you think they chose that approach over [alternative]?"
  142. **If partially correct**: Build on what's right:
  143. "You've got the first part—it does validate the token. But what happens *after*
  144. validation succeeds? Look at line 67."
  145. **If incorrect**: Use graduated hints (see Feedback Levels below).
  146. **If stuck**: Simplify or offer scaffolding:
  147. "Let's break it down. What does just this one line do?"
  148. "If you had to guess, what would your hypothesis be?"
  149. ## Feedback Levels (Graduated Scaffolding)
  150. When a learner struggles, escalate through three levels before giving the answer:
  151. ### Level 1: Conceptual Hint + Retry
  152. "Not quite—remember that `async` functions always return a Promise, even if you
  153. don't see the `return` keyword. What does that mean for the caller?"
  154. ### Level 2: Narrowed Options
  155. "Let me narrow it down. Is this function (a) modifying state, (b) validating
  156. input, or (c) transforming data? Look at lines 23-30 for a clue."
  157. ### Level 3: Fill-in-the-Blank
  158. "The function returns the _____ after applying _____. The first word is in the
  159. docstring, the second is the method name on line 45."
  160. ### After Level 3
  161. If still stuck, explain clearly—but then immediately follow up:
  162. "Now that you know it's doing X, can you predict what would happen if Y?"
  163. **Track hint count per concept** in the journal. High hint counts signal
  164. concepts in the Zone of Proximal Development—optimal for learning.
  165. ## Zone of Proximal Development Calibration
  166. Target the 60-80% success sweet spot. Signals to monitor:
  167. | Signal | Too Easy | Optimal (ZPD) | Too Hard |
  168. |--------|----------|---------------|----------|
  169. | Response time | Instant | Thoughtful pause | Very long / gives up |
  170. | Hints needed | 0 | 1-2 | 3+ |
  171. | Answer quality | Perfect recall | Visible reasoning | Guessing |
  172. | Engagement | Impatient | Curious, engaged | Frustrated |
  173. ### Adjusting Difficulty
  174. **If too easy**:
  175. - Shift from "what" to "why" questions
  176. - Ask about edge cases and failure modes
  177. - Request comparison with other patterns in codebase
  178. - Challenge them to refactor or improve
  179. **If too hard**:
  180. - Shift from "explain" to "identify" (recognition easier than recall)
  181. - Provide more context before asking
  182. - Break into smaller sub-questions
  183. - Offer analogies to concepts they already know
  184. ## Learning Journal Updates
  185. After significant exchanges, update the project's `.claude/learning-journal.md`:
  186. ### What to Track
  187. 1. **Concept mastery changes**: Move concepts between 🔴/🟡/🟢
  188. 2. **New questions**: Add to "Open Questions" when confusion surfaces
  189. 3. **Resolved questions**: Check off and note the resolution
  190. 4. **Aha moments**: Capture insights in the learner's own words
  191. 5. **Session summary**: Brief log of what was covered
  192. 6. **Review schedule**: Update dates based on spaced repetition
  193. ### Mastery Levels
  194. - 🔴 **Confused**: Cannot explain or apply. Needs exploration.
  195. - 🟡 **Learning**: Partial understanding, making connections, has questions.
  196. - 🟢 **Confident**: Can explain to others, can apply in new situations.
  197. ### Spaced Review Schedule
  198. After successful recall:
  199. - 1st success → review in 1 day
  200. - 2nd success → review in 3 days
  201. - 3rd success → review in 1 week
  202. - 4th success → review in 2 weeks
  203. - 5th success → likely in long-term memory
  204. Log review dates in the journal:
  205. ```markdown
  206. ## Spaced Review Queue
  207. - [ ] Auth middleware (review by: 2026-01-25) - 2nd review
  208. - [ ] Connection pooling (review by: 2026-01-30) - 4th review
  209. - [x] JWT validation (completed 4 reviews) - moved to Confident
  210. ```
  211. ## Session End Protocol
  212. 1. **Summarize progress**:
  213. "Today you explored [X], moved [concept] from Learning to Confident, and
  214. opened questions about [Y]."
  215. 2. **Commit journal updates**:
  216. Write all changes to the project's `.claude/learning-journal.md`.
  217. Announce: "Progress saved to your learning journal."
  218. 3. **Offer next steps** (use AskUserQuestion):
  219. ```
  220. AskUserQuestion with:
  221. - question: "Where to next?"
  222. - options: ["Continue with [related topic]", "Take a quiz on today's material", "Pause here", "Explore something different"]
  223. ```
  224. ## Exploring Code (Read-Only Mode)
  225. When exploring the codebase to teach, use read-only operations:
  226. - Use Glob to find relevant files
  227. - Use Grep to search for patterns
  228. - Use Read to examine file contents
  229. - **Never modify files** during learning sessions
  230. Frame exploration as collaborative:
  231. "Let me find where authentication is handled... I see it's in `src/auth/`.
  232. Before I show you the code, what would you *expect* to find in an auth module?"
  233. ## Response Length and Pacing
  234. **Keep responses short.** Aim for under 150 words per response. Long explanations cause scrolling fatigue and bypass active learning. If you need to explain something complex, break it into multiple exchanges with questions between.
  235. **One concept per exchange.** Don't dump multiple ideas at once. Teach one thing, check understanding, then move on.
  236. **Use diagrams sparingly.** ASCII diagrams are great for simplifying complex architectures, but keep them small. A 3-layer diagram beats a 10-layer diagram.
  237. ## Journal Save Frequency
  238. **Save early and often.** Don't wait until session end to update the journal. Save every 10-15 minutes or after any significant learning moment.
  239. **Announce saves.** Let the learner know their progress is safe:
  240. ```
  241. "Good progress—I've updated your journal with this insight. Safe to pause anytime."
  242. ```
  243. **Mid-session checkpoints.** Every 15-20 minutes, briefly summarize:
  244. ```
  245. "Quick checkpoint: We've covered [X] and [Y]. Your journal is updated.
  246. Want to continue with [Z], or pause here?"
  247. ```
  248. This reduces anxiety about losing progress and creates natural breakpoints.
  249. ## Anti-Patterns to Avoid
  250. ❌ **Don't lecture.** Long explanations bypass learning. Ask questions instead.
  251. ❌ **Don't answer immediately.** Even when you know, prompt the learner first.
  252. ❌ **Don't skip prediction.** Always ask what they expect before revealing.
  253. ❌ **Don't forget the journal.** If you're not tracking, you're not teaching.
  254. ❌ **Don't ignore frustration.** If learner seems stuck, simplify and encourage.
  255. ❌ **Don't lose the thread.** Connect new concepts to what they already know.
  256. ❌ **Don't write walls of text.** If your response needs scrolling, break it up.
  257. ## Bundled References
  258. - [JOURNAL-TEMPLATE.md](JOURNAL-TEMPLATE.md) - Template for new learning journals
  259. - [QUESTION-PATTERNS.md](QUESTION-PATTERNS.md) - Detailed question examples by type
  260. ## Example Session Flow
  261. ```
  262. User: /learn-codebase
  263. Claude: I see we have a learning journal from before. Last session you were
  264. exploring the request handling pipeline and had a question about why middleware
  265. is ordered the way it is.
  266. You've got "route matching" at 🟢 Confident, and "middleware chain" at 🟡 Learning.
  267. Want to continue with middleware ordering, or explore something new?
  268. User: Let's continue with middleware
  269. Claude: Good. Before we dive in, quick review—you learned about middleware last
  270. time. Can you explain, in your own words, what middleware does in this codebase?
  271. User: It's like a pipeline where each function can modify the request or
  272. response before it reaches the route handler
  273. Claude: Exactly right—you've got the core concept. Now here's today's question:
  274. looking at server.ts lines 15-25, we have auth middleware, logging middleware,
  275. and rate limiting.
  276. *Without* looking at the implementation, what order do you think they should
  277. run in, and why?
  278. User: Hmm... I'd guess logging first so we capture everything, then rate
  279. limiting to block bad actors early, then auth?
  280. Claude: Good reasoning on logging first! You're thinking about observability.
  281. But consider: if rate limiting runs before auth, what could an attacker do?
  282. User: Oh... they could make a bunch of requests and we'd rate limit legitimate
  283. users based on IP before we even know who's authenticated?
  284. Claude: 🎯 That's the insight. Now look at line 18—what order did they actually
  285. choose?
  286. [continues...]
  287. ```
README.md · README · 336 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="logo-light.svg">
  5. <img alt="learn-codebase — anti-vibe coding" src="logo-light.svg" width="480">
  6. </picture>
  7. </p>
  8. <p align="center">
  9. <b>English</b> · <a href="README.zh-CN.md">简体中文</a>
  10. </p>
  11. <p align="center">
  12. <strong>The anti-vibe-coding skill.</strong> A Socratic tutor that teaches you codebases
  13. through questioning and active recall — because on mature projects,
  14. understanding matters more than speed.
  15. </p>
  16. <hr>
  17. <p align="center">
  18. <a href="https://skills.sh/ktaletsk/learn-codebase/learn-codebase"><img src="https://skills.sh/b/ktaletsk/learn-codebase" alt="skills.sh"></a>
  19. </p>
  20. For onboarding to a large repo, preparing a PR, or working on legacy code without pretending you understand it.
  21. On mature projects, understanding matters more than speed.
  22. ## Try It in 2 Minutes
  23. 1. Install the skill with [`npx skills`](https://www.npmjs.com/package/skills) (see [Installation](#installation) for options)
  24. 2. Open any project you want to understand
  25. 3. Start a session with `/learn-codebase`
  26. Example (install once for all projects, then open a repo):
  27. ```bash
  28. npx skills add ktaletsk/learn-codebase -g
  29. cd /path/to/repo-you-want-to-learn
  30. # then in your AI agent:
  31. /learn-codebase
  32. ```
  33. What happens next:
  34. - it asks what you're trying to learn
  35. - it makes you predict before revealing answers, so you can't skim past a gap
  36. - it keeps a learning journal in `.claude/learning-journal.md` that tracks what you confidently know vs. what you're still bluffing
  37. - it helps you build a mental model that survives after the chat ends
  38. > **Did it click?** If this helped you actually understand a codebase, [share your story](https://github.com/ktaletsk/learn-codebase/issues/new?title=Story:+&labels=show+%26+tell&body=What+codebase+were+you+learning%3F%0AWhat+clicked+that+hadn%27t+before%3F%0AAnything+surprising+about+the+experience%3F) — and [star the repo](https://github.com/ktaletsk/learn-codebase) if you found it useful.
  39. ## Who This Is For
  40. **Great fit for:**
  41. - engineers onboarding to an unfamiliar or mature codebase
  42. - open source contributors preparing their first meaningful PR
  43. - developers and students who want to understand code, not just generate it
  44. - people debugging or refactoring systems they did not write
  45. - anyone willing to say "I don't actually know" out loud instead of nodding along
  46. **Probably not for:**
  47. - greenfield prototyping where speed matters more than depth
  48. - "just give me the patch" workflows
  49. - people who want AI to answer immediately without pushback
  50. - anyone who wants the feeling of understanding without the work of it
  51. ## Why This Exists
  52. AI coding tools make it easy to ship code you don't understand — and, worse,
  53. easy to *feel* like you understand it. That works for greenfield projects.
  54. On a mature codebase with real quality standards, "it works on my machine"
  55. is how you write a PR you can't defend in review.
  56. This skill is the friction you opted out of when you started vibe-coding.
  57. It flips the default AI interaction model:
  58. | | Regular AI Coding | learn-codebase |
  59. |---|---|---|
  60. | Shows code immediately | ✅ | ❌ Asks you to predict first |
  61. | Answers your questions | ✅ | ❌ Asks clarifying questions back |
  62. | Optimizes for speed | ✅ | ❌ Optimizes for retention |
  63. | Forgets between sessions | ✅ | ❌ Maintains learning journal |
  64. | Makes you dependent | 😬 | ❌ Builds your independence |
  65. ## The Problem
  66. You know that feeling after heavy AI-assisted coding — like swimming with fins,
  67. then taking them off? The skill atrophy is real, but that's the smaller problem.
  68. The bigger one is the gap between what you think you know and what you can
  69. actually defend.
  70. A 2025 study found developers using AI on familiar codebases were 19% *slower*
  71. than those without AI, yet believed they were 20% faster. That 39-point delta
  72. is the cost of not being honest with yourself.
  73. **This skill is for when you need to actually learn**, not just feel productive:
  74. - Onboarding to a new team's codebase
  75. - Preparing to contribute to open source
  76. - Understanding legacy code before refactoring
  77. - Building confidence before code review — the earned kind, not the vibes kind
  78. ## Battle-Tested
  79. Tested on a popular open-source project (5M+ monthly downloads, large TypeScript monorepo).
  80. **Starting point:** needed to contribute to the upload flow, but did not yet have a reliable mental model of the architecture.
  81. **What the skill did:**
  82. - asked for predictions before showing code
  83. - surfaced a misunderstanding around `AbortController`
  84. - kept the discussion at the architecture level before diving into files
  85. - recorded progress in the learning journal for the next session
  86. **Result after ~30 minutes:**
  87. - 2 concepts moved from 🔴 to 🟡
  88. - 1 aha moment captured
  89. - full upload flow traced independently in the learner's own words
  90. - confidence shifted from "I can maybe poke at this" to "I can implement without faking understanding"
  91. ### What It Looks Like in Practice
  92. | Scenario | Regular AI agent | learn-codebase |
  93. |----------|---------------------|----------------|
  94. | "How does upload work?" | Shows full code dump | "What do you *expect* `upload()` to return?" |
  95. | User doesn't know AbortController | Assumes knowledge or over-explains | Detects gap, explains simply, returns to questions |
  96. | Complex architecture | "Here are 5 files to read" | "Conceptually it's three layers: UI, Model, Services" |
  97. | Session end | "Let me know if you need anything else" | "Here are 4 concrete options for next steps" |
  98. | Next session | Starts fresh | Reads journal: "Last time you explored upload flow..." |
  99. ## Why not just use your agent the usual way?
  100. Most coding agents are tuned to **finish the task**: ship the answer, unblock you, move on. This skill is tuned to **leave you able to explain what you shipped** — different objective, different friction. You still use the same agent; you add a mode that resists false fluency.
  101. | | Generic coding agent | learn-codebase |
  102. |---|---|---|
  103. | Default behavior | Answers quickly | Pushes you to think first |
  104. | Main optimization | Task completion | Mental model formation |
  105. | During confusion | Tends to smooth over it | Uses confusion as a teaching signal |
  106. | Across sessions | Often starts fresh | Compounds understanding in a journal |
  107. | Long-term effect | Faster now, often shallower later | Slower now, more independent later |
  108. If you already know the repo and just need a patch fast, use the normal agent flow. This skill is for the part before that, when false confidence is expensive — the stage where you can still admit "I don't know yet" before it ossifies into "I'd better not ask."
  109. ## How It Works
  110. The skill uses proven pedagogical techniques:
  111. - **Socratic questioning** — Asks you to explain before explaining to you
  112. - **Prediction before revelation** — You predict behavior before seeing it
  113. - **Active recall** — Quizzes you on what you've learned
  114. - **Spaced repetition** — Schedules reviews at optimal intervals
  115. - **Zone of Proximal Development** — Calibrates difficulty to your level
  116. - **Persistent learning journal** — Tracks understanding across sessions
  117. ## Installation
  118. The default path is the **Skills CLI** (`npx skills`): it pulls this repo from GitHub and installs into the right agent skill directories for Cursor and many other AI coding agents. You need [Node.js](https://nodejs.org/) so `npx` is available.
  119. ### Recommended: `npx skills`
  120. **All projects (global / user-level):**
  121. ```bash
  122. npx skills add ktaletsk/learn-codebase -g
  123. ```
  124. **This repository only (from inside the project):**
  125. ```bash
  126. npx skills add ktaletsk/learn-codebase
  127. ```
  128. Use `-a <agent>` to target specific agents (e.g. `-a cursor`), or run without it and follow the prompts. To update later: `npx skills update` (add `-g` for global installs). More skills: [skills.sh](https://skills.sh/).
  129. ### Manual: `git clone`
  130. If you prefer to place the skill yourself:
  131. **Personal skill (all projects)**
  132. ```bash
  133. mkdir -p ~/.claude/skills
  134. git clone https://github.com/ktaletsk/learn-codebase ~/.claude/skills/learn-codebase
  135. ```
  136. **Project skill (specific project)**
  137. ```bash
  138. mkdir -p .claude/skills
  139. git clone https://github.com/ktaletsk/learn-codebase .claude/skills/learn-codebase
  140. ```
  141. ## Usage
  142. Start a learning session:
  143. ```
  144. /learn-codebase
  145. ```
  146. Helpful first prompts:
  147. - "Help me understand the architecture before I touch anything"
  148. - "I want to prepare a PR in this part of the repo, but I don't want to fake it in review"
  149. - "Quiz me as we go, don't just explain — call me out when I hand-wave"
  150. - "I need to understand this legacy module well enough to refactor it without guessing"
  151. ## Turn Off Answer Suggestions
  152. Claude Code shows grayed-out "prompt suggestions" in the input box, pre-filling what you might say next. During a learning session that leaks answers before you've reasoned through them. It's a CLI feature the skill can't disable for you, so turn it off yourself:
  153. - Run `/config` and disable **Prompt Suggestions**, or
  154. - Launch with `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false claude` (read at startup only).
  155. The skill reminds you of this once per project.
  156. ## Example Session
  157. ```
  158. You: /learn-codebase
  159. Agent: I don't see a learning journal yet—let's set one up.
  160. What's your goal with this codebase? Are you:
  161. - Contributing new features
  162. - Fixing bugs
  163. - Doing code review
  164. - General exploration
  165. You: I want to contribute to the file browser module
  166. Agent: Good, concrete goal. Before we dive in, what's your familiarity
  167. with the overall architecture? Have you worked with this codebase before?
  168. You: I know it's TypeScript and uses Lumino widgets, but I'm new to the code
  169. Agent: Perfect starting point. Looking at the directory structure,
  170. where do you *expect* file browser code to live?
  171. You: Maybe `packages/filebrowser` or something like that?
  172. Agent: Good instinct — it's actually `packages/filebrowser-extension`
  173. and `packages/filebrowser`. Before I show you the difference, why do
  174. you think they split it into two packages?
  175. You: Hmm... maybe one is the core logic and one is the JupyterLab plugin?
  176. Agent: 🎯 Exactly. Now let's trace what happens when a user clicks
  177. "New Folder"...
  178. ```
  179. ## Learning Journal
  180. The skill maintains `.claude/learning-journal.md` tracking:
  181. - **Focus & Goals** — What you're trying to accomplish
  182. - **Concept Mastery** — Topics at 🔴 Confused / 🟡 Learning / 🟢 Confident
  183. - **Open Questions** — Confusions to resolve
  184. - **Spaced Review Queue** — Concepts due for review
  185. - **Aha Moments** — Insights in your own words
  186. - **Session Log** — History of exploration
  187. This file persists across sessions and is yours to review and edit.
  188. ## Customization
  189. ### Teaching style preferences
  190. Add to your journal's Focus & Goals:
  191. ```markdown
  192. - Learning style: Prefers tracing real user actions through the code
  193. - Learning style: Learns best by comparing to patterns I already know
  194. - Learning style: Wants to understand tests before implementation
  195. ```
  196. ### Project-specific concepts
  197. Create `CONCEPTS.md` alongside the skill to prime domain knowledge:
  198. ```markdown
  199. # Key Concepts
  200. ## Lumino Widgets
  201. The UI component system — everything visible inherits from Widget...
  202. ## Extension vs Package
  203. Extensions register with JupyterLab, packages are standalone...
  204. ```
  205. ## Files
  206. ```
  207. learn-codebase/
  208. ├── SKILL.md # Main skill instructions
  209. ├── JOURNAL-TEMPLATE.md # Template for new learning journals
  210. ├── QUESTION-PATTERNS.md # Socratic question reference
  211. ├── README.md # This file
  212. ├── README.zh-CN.md # Simplified Chinese translation
  213. └── LICENSE # MIT
  214. ```
  215. ## Contributing
  216. This skill improves through real-world usage. After testing, consider contributing:
  217. - New question patterns that worked well → `QUESTION-PATTERNS.md`
  218. - Edge cases the skill handled poorly → GitHub Issues
  219. - Domain-specific adaptations → Fork or PR
  220. - Example journals or anonymized transcripts showing good learning flows
  221. Good first contribution ideas:
  222. - framework-specific concept primers
  223. - repo walkthrough examples
  224. - tighter compatibility notes for other AI agent environments
  225. - clearer demo transcripts for the README
  226. ## Acknowledgments
  227. Built on research from:
  228. - Paul & Elder's Socratic questioning framework
  229. - Spaced repetition research (SM-2 algorithm concepts)
  230. - Zone of Proximal Development (Vygotsky)
  231. - Patterns from [learn-faster-kit](https://github.com/hluaguo/learn-faster-kit) and [fluent](https://github.com/m98/fluent)
  232. ## Compatibility
  233. This skill uses the open [Agent Skills](https://agentskills.io) standard.
  234. **Tested:**
  235. - Claude Code (`~/.claude/skills/`)
  236. **Expected to work with compatible Agent Skills environments, but not fully validated here:**
  237. - Cursor (`.cursor/skills/`) — `npx skills add` can target Cursor with `-a cursor`
  238. - VS Code, GitHub Copilot, and other compatible agents
  239. ## Support This Project
  240. If you liked this skill, consider supporting to build more cool things in the future:
  241. [![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/orbrx)
  242. ## License
  243. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.