Overview
The Code Explainer skill transforms complex code into understandable explanations using multiple teaching techniques: analogies, diagrams, and step-by-step breakdowns.
SKILL.md Template
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
## 1. Start with an Analogy
Compare the code to something from everyday life that illustrates the core concept.
## 2. Draw a Diagram
Use ASCII art to show:
- Data flow
- Component relationships
- State transitions
- Call hierarchies
## 3. Walk Through the Code
Explain step-by-step what happens:
- Entry points
- Key transformations
- Exit conditions
- Return values
## 4. Highlight Gotchas
Point out:
- Common mistakes
- Edge cases
- Performance considerations
- Security implications
## Style Guidelines
- Keep explanations conversational
- Use multiple analogies for complex concepts
- Break into digestible sections
- Include "Why" not just "What"
Example Output
When explaining a debounce function:
Analogy
Think of debounce like an elevator door. When someone presses the button, the door doesn't close immediately—it waits a moment in case more people want to get in. Each new person "resets the timer." Only when no one has pressed the button for a while does the door finally close.
Diagram
User Input: X X X X ----wait---- X X ----wait----
│ │ │ │ │ │
Timer Reset: ↓ ↓ ↓ ↓ ↓ ↓
[====][====][====][====] [====][====]
│
Function Calls: ↓ (only here!)
Step by Step
- User triggers event
- Timer starts (or resets if already running)
- If timer completes without interruption → call function
- If new event arrives → reset timer, go to step 2
Usage
/explain-code src/utils/debounce.ts
Or ask naturally:
How does the authentication flow work?
Best Practices
- Start simple, add complexity gradually
- Use the reader's likely experience level
- Include runnable examples when possible
- Link to related concepts