Skip to content
Skills Library
Programming · Learning & explanation

study

/study

Interactive, guided code walk through generated onboarding docs — one layer at a time or by a route you choose (e.g. start at the database, follow a request). Three study modes — guided (drive-to-code, default), lecture (dense, optional questions), reference (dense, no questions). Use when the user runs /tutor:study or wants to be walked through a codebase.

Repository
tutor ↗
Licence
Apache-2.0
Last repository change
10.06.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.06.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Interactive, guided code walk through generated onboarding docs — one layer at a time or by a route you choose (e.g. start at the database, follow a request). Three study modes — guided (drive-to-code, default), lecture (dense, optional questions), reference (dense, no questions). Use when the user runs /tutor:study or wants to be walked through a codebase.

Arguments

/study [layer-id] [--route data-flow|top-down|bottom-up] [--mode guided|lecture|reference]
Original author description

Interactive, guided code walk through generated onboarding docs — one layer at a time or by a route you choose (e.g. start at the database, follow a request). Three study modes — guided (drive-to-code, default), lecture (dense, optional questions), reference (dense, no questions). Use when the user runs /tutor:study or wants to be walked through a codebase.

How it works

  1. Preconditions
  2. Choosing a route
  3. Saved topics
  4. Choosing a mode
  5. Walking a layer
  6. Diagram rules
  7. Drive-to-code rule (guided mode)
  8. See also
Original SKILL.md headings · 186 lines, 1,808 words
SKILL.md preview
---
name: study
description: Interactive, guided code walk through generated onboarding docs — one layer at a time or by a route you choose (e.g. start at the database, follow a request). Three study modes — guided (drive-to-code, default), lecture (dense, optional questions), reference (dense, no questions). Use when the user runs /tutor:study or wants to be walked through a codebase.
user-invocable: true
disable-model-invocation: true
argument-hint: "[layer-id] [--route data-flow|top-down|bottom-up] [--mode guided|lecture|reference]"
---

# /tutor:study

Lead the user through the onboarding docs as a code walk, one layer at a time, in one of three study modes (see **Choosing a mode**): `guided` drives them into specific file lines with questions they can only answer by reading the code; `lecture` and `reference` present a whole layer at once with code quoted inline. Coverage is tracked per topic so a session can be resumed later.

## Preconditions

Check for `docs/onboarding/index.md` in the current repo root. If it does not exist, tell the user to run `/tutor:build-study-guide` first and stop.

If the file exists, run the **Freshness** procedure defined in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`. Surface its advisory line verbatim if triggered; otherwise proceed silently.

Read `.tutor/review.md` if it exists and build the coverage set — the `(layer, topic)` pairs already walked, per the `review.md` format in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`. Keep this in scope for the session to drive **Resume** and the coverage summary below. If the file does not exist, there is no prior coverage.

## Choosing a route

Parse the argument(s) passed to the skill:

- **`layer-id` given** — start the walk on that layer. Read its `NN-<layer>.md` doc.
- **`--route data-flow`** — order the layers to trace the end-to-end data path described in `docs/onboarding/00-overview.md`. Reorder the `index.md` layer list to follow that path.
- **`--route top-down`** — walk layers in the order they appear in `index.md`.
- **`--route bottom-up`** — walk layers in reverse `index.md` order.
- **No argument** — ask the user where they want to start. If prior coverage exists, lead with a one-line summary (e.g. "You've walked 3 of 7 layers; next un-walked is *model-builder · cache-roles*."). Offer:
  1. **Resume** — continue at the first un-walked topic in route order (the next un-walked layer, starting at its first un-walked topic). Only offer this when prior coverage exists.
  2. **Saved topics** — study from your bookmarks. Only offer this option when `.tutor/saved-topics.jsonl` exists and has ≥ 1 active entry (see **Saved topics** below).
  3. Pick a layer by name or number from the `index.md` table (this is how you start a *different* review).
  4. Describe a named entry point ("start at the database", "follow a request from the API") and you will map it to the corresponding starting layer or topic within a layer.

  Wait for their choice before proceeding.

When the route resolves, compute **Resume** as the first topic — in the active route order — whose `(layer, topic)` pair has no row in the coverage set. Already-walked topics are not re-walked on Resume unless the user asks; mention them briefly and move to the first un-walked one.

## Saved topics

When the user picks **Saved topics**:

1. **Build the active list.** Read `.tutor/saved-topics.jsonl` and apply the active-entry rules defined in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`:
   - Exclude entries tombstoned by a `"studied"` event.
   - Exclude linked entries (`layer`+`topic` both non-empty) whose `(layer, topic)` pair already has a row in `.tutor/review.md`.
   
2. **If the active list is empty:** Tell the user all saved topics have already been walked, then fall back to the normal route/layer picker (options 3 and 4 above).

3. **Display the list.** Number the active entries, most-recent first, showing title, timestamp, and (if present) the linked layer + topic.

4. Wait for the user to pick one by number or title.

5. **If the chosen entry has `layer` + `topic`:** Navigate directly — load that layer's doc, start at that specific topic. Before the first question, show the saved description as a one-line context note so the user remembers why they bookmarked it. From here, proceed as in normal guided/lecture/reference mode; the topic is marked walked in `review.md` as usual, which retires this bookmark automatically.

6. **If `layer`/`topic` are empty:** Show the description and ask the user which layer they'd like to start on (standard layer-pick UI, same as option 3 above). The description is context, not a route — use it to orient the session but do not constrain which layer is chosen. When the session ends or the user stops, append a `"studied"` tombstone to `.tutor/saved-topics.jsonl` for this entry (format in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`).

## Choosing a mode

Parse `--mode guided|lecture|reference` from the arguments.

- **`--mode` given** — use that mode for the session.
- **`--mode` omitted** — ask the user which mode they want, together with the route/layer
  question above. Present the three choices:
  - **guided** *(default)* — one topic at a time. I point you to `file:line` and ask a
    question you can only answer by reading the code; I don't narrate until you've looked.
  - **lecture** — I present a whole layer at once, narrating each topic and quoting the
    relevant code inline (with citations). After the layer I offer an optional comprehension
    check.
  - **reference** — same dense, inline-quoted narration of the whole layer, with no
    questions. Read straight through.

  If the user gives a route/layer but no mode, default to **guided** rather than blocking.

The mode is **switchable mid-session**. If the user asks to "switch to lecture/reference/
guided", apply the new mode starting with the next layer.

## Walking a layer

How you work through each layer's `## Topics` depends on the active mode. In every mode,
read citations using the format defined in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`.

### guided (default)

Work through the `## Topics` one at a time. For each topic:

1. **Point to the code.** Read the topic's first citation. Tell the user the `file:line`
   reference and ask them to open it — do not quote the code for them.
2. **Ask a grounded question.** Pose a question that can only be answered by reading those
   specific lines (e.g. "What field does the constructor set here?"). Phrase it so a correct
   answer proves the user looked.
3. **Wait.** Do not continue until the user responds.
4. **Confirm or correct.** Acknowledge what they got right. If their answer is wrong or
   vague, send them back to the same lines with a more precise pointer — never supply the
   answer yourself (see **Drive-to-code rule**).
5. **Expand.** Once the user has demonstrated they read the code, explain the concept,
   data-flow context, or gotcha from the doc. Narrate after, not before.

If a topic has multiple citations, use the first to anchor the question; bring in additional
citations during the expansion step or to deepen follow-up questions.

### lecture

Present the whole layer as continuous reading. Work through all `## Topics` in order; for
each, narrate the concept and **quote the relevant code snippet inline**, keeping its
`file:line` citation so the user can click through. Do not gate progress on questions.

After the layer, offer one comprehension check with three choices:
1. Ask a few grounded questions (guided-style) on this layer's topics.
2. Skip to the next layer.
3. Launch the full quiz by invoking the `/tutor:quiz <layer-id>` skill directly.

### reference

Same dense, inline-quoted narration of the whole layer as **lecture**, but ask **no
questions**. After the layer, go straight to the next-layer/stop prompt below.

### Recording coverage (all modes)

The moment a topic is **walked**, append one row for its `(layer, topic, mode)` to
`.tutor/review.md`, using the format in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`
(create the file with its header if it does not yet exist). Write each row immediately —
do not batch — so an interrupted session is preserved. A topic is walked:

- **guided** — after the *Expand* step (the user read the code and you explained it).
- **lecture** / **reference** — after you have narrated and quoted that topic.

Do not record a topic the user explicitly skipped without it being walked.

## Diagram rules

### When to show

Diagrams are orientation aids, not answers. Showing a diagram **never violates the
Drive-to-code rule** — that rule prohibits narrating code before the user reads it;
structural flowcharts do not contain code answers. A diagram may be shown in any mode
at any time if the user requests it.

Automatic display rules by mode:

| Trigger | guided | lecture | reference |
|---------|--------|---------|-----------|
| Layer start (layer doc has `## Diagram`) | Show once, before first topic | Show once, before narration begins | Show once, before narration begins |
| Topic name contains "flow", "boundary", "path", "security", or "pipeline" | Skip | Re-show diagram once per layer (not once per matching topic) | Re-show diagram once per layer (not once per matching topic) |
| User explicitly requests a diagram | Show immediately | Show immediately | Show immediately |

"Show" means: output the `## Diagram` section's code block verbatim inline. ASCII diagrams
render correctly in the TUI and all other environments with no special handling.

### System overview diagram

Before walking the first layer (any mode, any route), check whether `00-overview.md`
contains a fenced code block. If it does, show it as a brief system-orientation step — a
single message with the diagram and one sentence of context — before proceeding to the
first layer. Show it only once per session.

### No diagram exists and the user asks

If the current layer doc has no `## Diagram` section and the user asks for a diagram,
generate a minimal ASCII diagram from the layer's overview prose (≤ 12 components), using
the drawing conventions in `${CLAUDE_PLUGIN_ROOT}/references/conventions.md`. Do not write
it back to the doc. In **guided** mode, after showing the ad-hoc diagram, re-issue the
pending `file:line` pointer and question so the user knows where they left off — the
diagram interruption does not count as walking a topic.

### After each layer (all modes)

Offer the quiz: "Ready to test yourself on this layer?" If the user agrees, launch it by
invoking the `/tutor:quiz <layer-id>` skill directly (do not just print the command).

Then ask whether to continue to the next layer in the route or stop. (In `lecture`, this
follows the comprehension check above.)

## Drive-to-code rule (guided mode)

In **guided** mode you are a guide, not a narrator. The user must open the files. Answering
on their behalf defeats the purpose of the session.

- Never front-load the answer before the user has looked at the cited lines.
- If the user's answer is vague ("it does something with the cache"), send them back to the
  specific `file:line` with a tighter prompt: "Look at line N specifically — what is the
  return type?"
- If the user asks you to just explain it, decline politely and redirect: "Open
  `<file>:<line>` and tell me what you see — then I can give you the full picture."
- A guided session in which the user never opens a file has failed.

**This rule is scoped to guided.** `lecture` and `reference` are textbook-style reading:
quote relevant code inline (always with `file:line` citations) so the user can absorb a
layer without opening files, while keeping citations clickable so they still can.

## See also

- `${CLAUDE_PLUGIN_ROOT}/references/conventions.md` — authoritative formats for `index.md` front-matter, layer docs, citation syntax, the Freshness procedure, `.tutor/progress.md`, and `.tutor/review.md` (review coverage).

Versions

RepositoryScoreLicence
This page · patmagee/tutor90Apache-2.0
harmix/open-stanley100MIT
boston-harness-group/remote-factory100MIT
alaliqing/claude-paper100MIT
adamthewilliam/grepika100MIT
lucastamoios/skills95MIT
oskarijuurikkala/ac-hub-starter95CC-BY-4.0
DaniilKi/pali-canon-claude92MIT
flc1125/skills90MIT

Database snapshot: 13.11.2026 · package version 5b499bfde8ea (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90walk-with-me
    Use when the user wants to be walked through code, not handed a report: "walk through this", "guided code walk", or "explain this codebase". Not for tasks that require source or remote-system changes.
  • 100build-study-guide
    Review a codebase and generate layered, evidence-cited onboarding docs (overview, per-layer, gotchas, how-to-build, how-to-run-and-debug) under docs/onboarding/. Use when the user wants to onboard to or document an unfamiliar repo, or runs /tutor:build-study-guide.
  • 90walk-the-diff
    Use when the user wants to walk through their local changes interactively before or instead of a PR review — e.g., "guided review", "walk me through the changes", "review my branch", "let's go through the diff". Also use when the user explicitly invokes the walk-the-diff skill…
  • 100study-session
    Use when the user asks for a guided comprehension/study session over existing code: '/study-session', 'study session', 'sesión de estudio', 'repasemos <subsystem>', 'help me understand <area>', or a recurring comprehension-recovery ritual. Recovers AND measures the mental model…
  • 100repo-study
    Use when the user explicitly invokes `$repo-study` to research a GitHub repository; never invoke it implicitly for ordinary repository questions.
  • 95intent-layer-onboarding
    Get oriented in an unfamiliar codebase using its Intent Layer. Use when joining a new project, exploring a codebase for the first time, or helping someone understand "where do I start?" questions.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.