Code Explainer
Interactive code walkthrough. Scans the codebase for a feature, builds a segment plan, then walks through each segment — highlighting code in VS Code and explaining at their chosen depth.
Models
Configure your preferred models here. All docs reference these tiers by name — change them once and the whole skill updates.
| Tier |
Default |
Role |
LARGE |
opus |
Deep Dive planner — narrative reasoning, transition objects |
MEDIUM |
sonnet |
Deep Dive segment agents — deep code reading, dense highlights |
SMALL |
haiku |
Scout, Overview plan+highlights — fast exploration and scanning |
When dispatching sub-agents, look up the model for the tier and use that exact model name.
Checklist
Complete these steps in order:
Parallel init — Dispatch both in a single response:
- Sidebar check (Bash):
PORT=$(cat ~/.claude-explainer-port 2>/dev/null) && TOKEN=$(cat ~/.claude-explainer-token 2>/dev/null) && curl -sf -H "Authorization: Bearer $TOKEN" "http://localhost:$PORT/api/health" — {"status":"ok"} means sidebar is active. When active, NEVER output walkthrough content as terminal text; all output goes through sidebar HTTP API only.
- Ask preferences (AskUserQuestion): Read
docs/assess.md and ask all three questions listed there (familiarity + depth level + delivery mode) in a single call. Do NOT skip any or invent new ones.
Scout — Read docs/scan.md. Dispatch SMALL sub-agent to discover relevant files and map the call chain. No highlights yet — discovery only.
Plan + generate — Two paths depending on depth:
- Overview — Single
SMALL sub-agent reads scout output, builds plan, generates highlights in one pass. Send set_plan when done.
- Deep Dive — Read
docs/plan.md. Dispatch LARGE planner to build narrative + transition objects. Then read docs/segments.md and dispatch parallel MEDIUM segment agents (all at once). Create a unique temp dir with mktemp -d and have each agent write its segment there. Wait for ALL agents to complete, then assemble from files with jq and send one full set_plan. Clean up the temp dir after sending. Do NOT send anything to the sidebar until everything is ready.
Execute walkthrough — Read the doc for chosen mode: docs/walkthrough.md, docs/read.md, or docs/podcast.md. Walkthrough and podcast reference docs/tts.md.
Wrap up — 3-5 key takeaways, how feature fits the broader architecture, offer to dive deeper or explain related features.
First-time setup? Read docs/setup.md.
Q&A on Active Walkthrough
When the user says they're in an active explainer walkthrough and asks a question (even in a new chat), skip the full checklist above and instead:
- Get context: Run
~/.claude/skills/explainer/scripts/explainer.sh state — the response now includes a segment field with the full current segment (file, start, end, title, explanation, highlights). Use this to understand what code the user is currently viewing.
- Read the code: Use the segment's
file, start, and end to read the relevant source code.
- Answer in context: Ground your answer in the specific code and segment the user is looking at. Reference line numbers from the segment, not abstract concepts.
If state returns status: "idle" (no active walkthrough), check .walkthroughs/ for saved plans and ask the user which one they mean.
Common Mistakes
| Mistake |
Fix |
| Scope too large |
Stick to segment boundaries. Overview: max 80 lines, Deep Dive: max 40. Split if bigger |
| Not connecting segments |
Include a context line linking to previous segment |
| Forgetting to highlight |
Sidebar: automatic. Fallback: write to ~/.claude-highlight.json |
| Reading entire file |
Use offset+limit on Read for just the segment |
| Not waiting for user |
Pause after each segment for questions |
| ttsText missing or has markdown |
Include plain ttsText in every segment — strip backticks, bold, line refs from spoken text |
| Explaining obvious code, missing the "why" |
Skip standard patterns (loops, imports, null checks). Always explain intent before mechanism |
| Ignoring complexity tags |
[core] = thorough, [wiring] = breeze through, [supporting] = brief |
| Sidebar check not parallelized |
Dispatch Bash health check + AskUserQuestion in one response, not sequentially |
| Text output when sidebar active |
If health check returned ok, send plan JSON only — no terminal text |
| Sub-highlights too many or too granular |
Deep Dive: 6-12 highlights per segment, 1-4 lines each. Highlights are a moving pointer over one continuous voice stream — ttsText across highlights is concatenated and spoken as one TTS call, so write it as flowing narration, not self-contained slides. Overview: 1-8 lines, 3-6 per segment |
| Wrong field names in sidebar JSON |
Use start/end/title/ttsText/highlights — NOT startLine/endLine/label/subHighlights. See docs/plan.md for exact schema |
Skipping set_plan before goto |
Sidebar needs the full plan loaded first. Always send set_plan via explainer.sh plan before any goto messages |
| Sending plan before agents finish |
Wait for ALL parallel segment agents to complete. Each writes to a unique temp dir (created via mktemp -d). Assemble from files with jq, then send one set_plan. Clean up temp dir after. Never send stubs or partial plans |
| Scout generating highlights |
Scout only maps files and call chain. Highlights are generated in step 2 (Overview: single agent, Deep Dive: parallel agents) |
| Running planner + parallel agents for Overview |
Overview uses one fast SMALL agent for plan + highlights. Planner and segment agents are Deep Dive only |
| Using tier names as literal model names |
LARGE, MEDIUM, SMALL are placeholders — always resolve to the actual model name from the Models table in SKILL.md before dispatching |
Source: Royal-lobster/code-explainer — distributed by TomeVault.
1---2name: explainer3description: Use when the user asks to explain, walk through, or understand a feature, module, or code flow in the codebase. Triggers on 'explain', 'walk me through', 'how does X work', 'what does this code do'.4---56# Code Explainer78Interactive code walkthrough. Scans the codebase for a feature, builds a segment plan, then walks through each segment — highlighting code in VS Code and explaining at their chosen depth.910## Models1112Configure your preferred models here. All docs reference these tiers by name — change them once and the whole skill updates.1314| Tier | Default | Role |15|------|---------|------|16| `LARGE` | `opus` | Deep Dive planner — narrative reasoning, transition objects |17| `MEDIUM` | `sonnet` | Deep Dive segment agents — deep code reading, dense highlights |18| `SMALL` | `haiku` | Scout, Overview plan+highlights — fast exploration and scanning |1920When dispatching sub-agents, look up the model for the tier and use that exact model name.2122## Checklist2324Complete these steps in order:25260. **Parallel init** — Dispatch both in a **single response**:27 - **Sidebar check (Bash):** `PORT=$(cat ~/.claude-explainer-port 2>/dev/null) && TOKEN=$(cat ~/.claude-explainer-token 2>/dev/null) && curl -sf -H "Authorization: Bearer $TOKEN" "http://localhost:$PORT/api/health"` — `{"status":"ok"}` means sidebar is active. When active, **NEVER output walkthrough content as terminal text**; all output goes through sidebar HTTP API only.28 - **Ask preferences (AskUserQuestion):** Read `docs/assess.md` and ask all three questions listed there (familiarity + depth level + delivery mode) in a single call. Do NOT skip any or invent new ones.29301. **Scout** — Read `docs/scan.md`. Dispatch `SMALL` sub-agent to discover relevant files and map the call chain. No highlights yet — discovery only.312. **Plan + generate** — Two paths depending on depth:32 - **Overview** — Single `SMALL` sub-agent reads scout output, builds plan, generates highlights in one pass. Send `set_plan` when done.33 - **Deep Dive** — Read `docs/plan.md`. Dispatch `LARGE` planner to build narrative + transition objects. Then read `docs/segments.md` and dispatch parallel `MEDIUM` segment agents (all at once). Create a unique temp dir with `mktemp -d` and have each agent write its segment there. Wait for ALL agents to complete, then assemble from files with `jq` and send one full `set_plan`. Clean up the temp dir after sending. Do NOT send anything to the sidebar until everything is ready.343. **Execute walkthrough** — Read the doc for chosen mode: `docs/walkthrough.md`, `docs/read.md`, or `docs/podcast.md`. Walkthrough and podcast reference `docs/tts.md`.354. **Wrap up** — 3-5 key takeaways, how feature fits the broader architecture, offer to dive deeper or explain related features.3637**First-time setup?** Read `docs/setup.md`.3839## Q&A on Active Walkthrough4041When the user says they're in an active explainer walkthrough and asks a question (even in a new chat), skip the full checklist above and instead:42431. **Get context:** Run `~/.claude/skills/explainer/scripts/explainer.sh state` — the response now includes a `segment` field with the full current segment (`file`, `start`, `end`, `title`, `explanation`, `highlights`). Use this to understand what code the user is currently viewing.442. **Read the code:** Use the segment's `file`, `start`, and `end` to read the relevant source code.453. **Answer in context:** Ground your answer in the specific code and segment the user is looking at. Reference line numbers from the segment, not abstract concepts.4647If `state` returns `status: "idle"` (no active walkthrough), check `.walkthroughs/` for saved plans and ask the user which one they mean.4849## Common Mistakes5051| Mistake | Fix |52|---------|-----|53| Scope too large | Stick to segment boundaries. Overview: max 80 lines, Deep Dive: max 40. Split if bigger |54| Not connecting segments | Include a context line linking to previous segment |55| Forgetting to highlight | Sidebar: automatic. Fallback: write to `~/.claude-highlight.json` |56| Reading entire file | Use offset+limit on Read for just the segment |57| Not waiting for user | Pause after each segment for questions |58| ttsText missing or has markdown | Include plain `ttsText` in every segment — strip backticks, bold, line refs from spoken text |59| Explaining obvious code, missing the "why" | Skip standard patterns (loops, imports, null checks). Always explain intent before mechanism |60| Ignoring complexity tags | `[core]` = thorough, `[wiring]` = breeze through, `[supporting]` = brief |61| Sidebar check not parallelized | Dispatch Bash health check + AskUserQuestion in one response, not sequentially |62| Text output when sidebar active | If health check returned ok, send plan JSON only — no terminal text |63| Sub-highlights too many or too granular | Deep Dive: 6-12 highlights per segment, 1-4 lines each. Highlights are a moving pointer over one continuous voice stream — ttsText across highlights is concatenated and spoken as one TTS call, so write it as flowing narration, not self-contained slides. Overview: 1-8 lines, 3-6 per segment |64| Wrong field names in sidebar JSON | Use `start`/`end`/`title`/`ttsText`/`highlights` — NOT `startLine`/`endLine`/`label`/`subHighlights`. See `docs/plan.md` for exact schema |65| Skipping `set_plan` before `goto` | Sidebar needs the full plan loaded first. Always send `set_plan` via `explainer.sh plan` before any `goto` messages |66| Sending plan before agents finish | Wait for ALL parallel segment agents to complete. Each writes to a unique temp dir (created via `mktemp -d`). Assemble from files with `jq`, then send one `set_plan`. Clean up temp dir after. Never send stubs or partial plans |67| Scout generating highlights | Scout only maps files and call chain. Highlights are generated in step 2 (Overview: single agent, Deep Dive: parallel agents) |68| Running planner + parallel agents for Overview | Overview uses one fast `SMALL` agent for plan + highlights. Planner and segment agents are Deep Dive only |69| Using tier names as literal model names | `LARGE`, `MEDIUM`, `SMALL` are placeholders — always resolve to the actual model name from the Models table in SKILL.md before dispatching |7071---72> Source: [Royal-lobster/code-explainer](https://github.com/Royal-lobster/code-explainer) — distributed by [TomeVault](https://tomevault.io).73<!-- tomevault:4.0:skill_md:2026-06-17 -->
tomevault-io