learn

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# `/learn` — Educational explainer for the last commit or PR

This skill turns a recent change into a software-engineering lesson. The reader has just had Claude Code (or someone else) make a change, and they want to actually understand it: what was done, why it was done that way, and which fundamentals are at play.

The audience is someone learning software engineering. They are not a beginner programmer — they can read code — but they have not yet internalised the named patterns and principles that experienced engineers use to reason about design. The job of this skill is to bridge that gap, on a real diff, every time they ask.

## Synopsis

```
/learn [target] [level] [depth] [save] [help]

  target   <ref> | pr [<N>] | <path> | <symbol>             default: HEAD
           | "<question>" | topic <name>
  level    expert | intermediate | beginner | eli5        default: intermediate
           (synonyms — expert:    technical, staff
                       beginner:  simple, plain
                       eli5:      grandma, grandmother)
  depth    quick | standard | deep                          default: standard
           (synonyms — quick:    peek
                       standard: overview
                       deep:     deep-dive, deepdive, audit)
           Only meaningful in topic and static (folder) modes.
  save     write the lesson to .claude/learn-log/          default: off
           (synonyms: --save, export)
  help     show this synopsis instead of running           (synonyms: ?, usage,
                                                                      --help, -h)
```

Order of args does not matter. `/learn topic auth simple deep-dive save` and `/learn save deep-dive simple topic auth` are equivalent. If `help` (or `?`, `usage`) appears anywhere in the args, the skill renders this Synopsis as the response and stops — no lesson, no save, no execution.

## Target shapes

`/learn` accepts six kinds of target. The dispatcher classifies the non-keyword tokens syntactically and runs the matching gathering recipe. If more than one classification is plausible, state the inference in the first line of the response so the user can override.

| Shape | Looks like | What gets gathered | Example |
|---|---|---|---|
| **Diff** | empty, `pr`, `pr <N>`, SHA, `HEAD~N`, `HEAD^`, branch name, tag, range (`A..B`) — anything `git show`/`git diff` accepts | The diff, commit message, PR description and review comments | `/learn`, `/learn pr 42`, `/learn HEAD~3`, `/learn cfc4afb` |
| **Static** | A path that exists in the working tree | The file (single file → top-to-bottom walkthrough) or folder (directory listing + key files → structural tour) | `/learn src/auth/`, `/learn package.json`, `/learn ./foo.ts` |
| **Symbol** | A bare identifier that ripgrep finds as an exported function/class/type | The symbol's definition + the call sites that use it | `/learn OrderProcessor`, `/learn handleLogin` |
| **Trace** | Quoted natural language describing a behaviour | Entry-point search + path through the code, end to end | `/learn "how does login work"` |
| **Topic** | The literal keyword `topic` followed by a name | Topic vocabulary lookup → codebase grep using the search terms → bounded file reads (depth-controlled) | `/learn topic auth`, `/learn topic dependency-injection` |
| **Help** | `help`, `?`, `usage`, `--help`, `-h` | Nothing — render the Synopsis and stop | `/learn help`, `/learn ?` |

### Ambiguity resolution

A token like `auth` could be a branch, a folder, or a topic. When more than one match is plausible, prefer in this order:

1. Explicit `topic` keyword present → topic mode (always wins).
2. Path that exists on disk → static mode.
3. Git ref that resolves (`git rev-parse <token>` succeeds) → diff mode.
4. Bare identifier that ripgrep finds as an exported symbol → symbol mode.
5. Otherwise → trace mode if the token is a multi-word phrase, else fall back to topic mode with the token as the topic name (and state the assumption).

Always say which mode was chosen in the first line, so the user can correct with `/learn topic auth` if they meant the topic and the dispatcher picked the folder.

## When this skill runs

The user invokes it explicitly, usually with a slash:

- `/learn` → explain the last commit on the current branch (`HEAD`).
- `/learn pr` → explain the open PR for the current branch, or the most recently merged PR if there is no open one.
- `/learn pr 123` → explain a specific PR by number.
- `/learn HEAD~2`, `/learn <sha>`, `/learn main..feature` → explain a specific commit or range.

If the invocation is ambiguous, default to the last commit (`HEAD`) and state the assumption in the first line of the response.

It also runs without a slash when the user clearly asks for a teaching pass on recent work — phrases like "teach me what just changed", "explain the last commit", "walk me through this PR like a tutorial".

## Audience level

The reader can dial how technical the lesson is by adding a level keyword to the invocation. The keyword can appear anywhere in the args — order does not matter — and the skill treats any token from the closed set below as the level, with everything else as the target spec.

- **expert** (synonyms: `technical`, `staff`) — peer-to-peer. Assume the reader knows SOLID, the common GoF patterns, and standard vocabulary. Don't define everyday terms; lean on precise jargon. Skip analogies unless the diff contains a genuinely unusual idea.
- **intermediate** (default — no keyword needed) — for someone who can read code but is still building their library of named patterns. Define each named concept the first time it appears. Connect every abstraction to a concrete consequence the reader will eventually feel (testability, blast radius, swap-ability). This is the audience the skill was originally written for.
- **beginner** (synonyms: `simple`, `plain`) — minimise jargon. When you must use a term, explain it in everyday language *before* naming it. Prefer "the function asks for what it needs as arguments instead of grabbing it from somewhere global, which is called **dependency injection**" over "the constructor injects its dependencies." One concept per sentence.
- **eli5** (synonyms: `grandma`, `grandmother`) — analogy-first. Lead every named concept with a non-code metaphor — kitchens, libraries, post offices, plumbing, restaurant orders. Code references are still allowed; the reader is not literally five. But every principle must be motivated by a real-world picture before any jargon enters the sentence. Use this level when the reader is very new, or when the change is conceptually far from their comfort zone.

Examples:

- `/learn simple` → last commit, plain language.
- `/learn pr 42 expert` → PR 42, full technical depth.
- `/learn HEAD~2 eli5` → that commit, analogy-driven explanation.
- `/learn grandma` → last commit, maximum accessibility.

If the user's invocation contains both a level keyword *and* a natural-language hint ("can you make this really simple?"), respect the natural-language signal even if the keyword disagrees or is missing. If two level signals genuinely conflict, pick the gentler one and state the assumption in the first line.

The level affects **writing only** — it does not change which concepts get surfaced. A correct `eli5` lesson still names the right principles; it just leads with the metaphor and keeps the jargon density low.

## Depth

For target shapes where section 4 is *"where this lives in your codebase"* (topic mode, and static mode for folders), the depth keyword controls how far the skill walks through the codebase. Order-independent in the args; default `standard` if no keyword is present.

| Keyword | Coverage | Use when |
|---|---|---|
| `quick` (synonym: `peek`) | 2–3 representative `path:line` hits, locations + a one-liner each | "Just point me at the relevant files" |
| `standard` (synonym: `overview`) *(default)* | 4–6 places walked through with explanation; flag what's NOT covered | The default learning lesson |
| `deep` (synonyms: `deep-dive`, `deepdive`, `audit`) | Comprehensive coverage, capped at **20 files**; flag missing sub-concepts | "Audit this topic across the codebase" |

The 20-file cap on `deep` is hard. Past that it's a search engine, not a lesson — say so and stop adding. Reaching the cap is itself a finding: the topic is *bigger than this codebase* in some meaningful sense, and naming that is more useful than truncating silently.

Depth has no effect on diff/symbol/trace/help modes — section 4 in those is the critical-review pass, which sizes itself naturally to the input.

## How to gather the change

The gathering recipe depends on which target shape was selected (see **Target shapes** above). The first three steps are common to every mode; from step 4 onward, branch by mode.

1. **Parse the args.** Walk the tokens once and bucket each one:
   - **Level keywords** (closed set): `expert`, `technical`, `staff`, `intermediate`, `beginner`, `simple`, `plain`, `eli5`, `grandma`, `grandmother`. Default `intermediate` if none.
   - **Depth keywords** (closed set): `quick`, `peek`, `standard`, `overview`, `deep`, `deep-dive`, `deepdive`, `audit`. Default `standard` if none.
   - **Save keywords** (closed set): `save`, `--save`, `export`. Default off if none.
   - **Help keywords** (closed set): `help`, `--help`, `-h`, `?`, `usage`. If any appear, **short-circuit**: render the Synopsis block above as the response and stop.
   - **Topic marker**: the literal token `topic` followed by its argument (the next non-keyword token) → topic mode, with the next token as the topic name.
   - **Quoted phrase**: a multi-word string in quotes → trace mode.
   - **Everything else** is the target spec, classified per the **Target shapes** rules.
2. **Classify the target.** Apply the ambiguity-resolution order from **Target shapes** to pick a mode. State the inferred mode in the first line of the response.
3. **If the target is invalid**, say so plainly. Empty repo, no commits, nonexistent path, no matching symbol, no topic vocabulary entry *and* no fallback search terms reasonable for the topic name → ask the user how they want to proceed.

### Diff mode

From carlosboeing/agentic-toolkit, MIT.

More from carlosboeing/agentic-toolkit