explain-code

Explains code with multiple levels of detail — high-level purpose, line-by-line walkthrough, data flow diagrams, and design rationale. Use when onboarding to unfamiliar code or trying to understand co

SKILL.md

GitHub

Code Explanation

Instructions

Step 1: Identify the Target

Read the specified file, function, or module completely. Also read:

  • Any imports/dependencies it uses
  • Any files that import/call it (to understand usage context)
  • Recent git history for the file: git log --oneline -10 <file>

Step 2: Provide Multi-Level Explanation

Level 1 — One-Sentence Summary

What does this code do in plain English? A non-technical person should understand this.

Level 2 — High-Level Overview

  • Purpose: What problem does it solve?
  • Inputs: What goes in? (parameters, config, env vars, external data)
  • Outputs: What comes out? (return values, side effects, events emitted)
  • Dependencies: What does it rely on?
  • Callers: Who uses this? In what context?

Level 3 — Detailed Walkthrough

Walk through the code section by section:

  • Explain the logic flow with numbered steps
  • Highlight non-obvious decisions ("this uses X instead of Y because...")
  • Note any error handling and what triggers each path
  • Explain any performance-sensitive sections

Level 4 — Data Flow Diagram

Create an ASCII diagram showing:

[Input] → [Processing Step 1] → [Processing Step 2] → [Output]
                ↓                       ↓
         [Side Effect 1]         [Side Effect 2]

Step 3: Highlight Key Details

  • Tricky Parts: Code that might confuse a new reader
  • Assumptions: Implicit assumptions the code makes
  • Edge Cases: How are boundary conditions handled?
  • History: Why was it written this way? (use git blame for context)

Step 4: Related Code

List the most important related files/functions that someone exploring this code should read next.


Output Style

  • Use clear section headers
  • Include code snippets with line references
  • Use analogies where helpful
  • Adjust technical depth based on the complexity of the code