explain-code
Explains code with visual diagrams and analogies. Use when explaining unfamiliar code, onboarding a beginner, walking through a tricky function, or breaking down a system's flow. Triggers on phrases l
SKILL.md.claude/skills/explain-code/SKILL.md
GitHubExplain Code
Make code understandable to a beginner without dumbing it down. Lead with intuition, follow with mechanics.
When explaining code, always include:
Start with an analogy. Compare the code to something from everyday life — a queue at a coffee shop, a postal sorting room, a kitchen with multiple cooks. The reader should be able to picture what the code is doing before they understand how.
Draw a diagram. Use ASCII art to show the flow, structure, or relationships. Boxes for components, arrows for data, dashed lines for async or optional paths. A diagram beats three paragraphs of prose.
Walk through the code. Explain step-by-step what happens — line by line for tricky bits, block by block for routine bits. Cite line numbers (
file.py:42) so the reader can follow along in their editor.Highlight a gotcha. What's a common mistake or misconception? What did you misread the first time? What invariant looks obvious but isn't? One sharp warning is worth more than a generic "be careful."
Keep explanations conversational. For complex concepts, use multiple analogies — different mental models reveal different facets.
Format template
When you invoke this skill, structure the response like this:
## The big picture
<one-sentence analogy>
## The diagram
<ASCII art>
## The walk-through
1. Line X: ...
2. Line Y: ...
...
## The gotcha
<the one thing people get wrong>
Examples of good analogies
- Async/await → ordering at a coffee shop with a buzzer: you place the order (await), the barista works on it while you sit down (event loop runs other tasks), the buzzer goes off when ready (promise resolves).
- Recursion → Russian nesting dolls: each call opens a smaller version of the same problem until you hit the smallest doll (base case), then you assemble back up.
- Closures → a backpack the function carries everywhere: even when called somewhere else, it still has access to the variables that were in scope when it was defined.
- Mutex / lock → the bathroom key at a gas station: only one person at a time, you wait for the key, you give it back when done.
- Pub/sub → a newsletter: publishers send issues, subscribers receive them, neither knows who the other is.
- Database transaction → a Word doc with "track changes" — you can keep editing, but nothing's saved until you commit; one click of "discard" rolls everything back.
Diagram patterns
Sequential flow:
[input] ──▶ [step 1] ──▶ [step 2] ──▶ [output]
Branching:
┌──▶ [path A]
[decision] ──┤
└──▶ [path B]
Async / event loop:
caller ──await──▶ [task] ┐
│ │ event loop runs
│ ◀────── result ────── ┘ other work meanwhile
State machine:
[idle] ──start──▶ [running] ──finish──▶ [done]
│
cancel
▼
[cancelled]
When NOT to use this skill
- One-line edits or trivial syntax fixes — the analogy overhead isn't worth it.
- The user explicitly asks for terse output ("just give me the diff", "what's the fix").
- Code review feedback — use the
requesting-code-reviewskill instead; reviews need findings, not pedagogy.
Calibration
Match the depth of explanation to the question:
- "What does this line do?" → walk-through only, skip the analogy.
- "How does this whole module work?" → full template (analogy + diagram + walk-through + gotcha).
- "I'm a beginner, help me understand X" → full template + a second analogy at the end.