Code Explainer Skill

Explain how a feature or codebase works with focus on data flow and key logic.

When to trigger

• •User asks: "how does this work", "explain this feature", "remind me how X works"
• •Before making changes to unfamiliar code
• •When revisiting old code

Instructions

1. •

   Identify scope:

   • •Ask user what feature/file/function to explain if unclear
   • •For features: find entry points (routes, components, CLI commands)
   • •For files: focus on that file and its direct dependencies
2. •

   Map the flow:

   • •Trace execution path from entry to exit
   • •Identify key decision points (if/match statements, loops)
   • •Note external calls (APIs, DB, file I/O)
   • •Track state changes and side effects
3. •

   Extract key info:

   • •Purpose: What problem does this solve?
   • •Entry points: Where does execution start?
   • •Data flow: Input → transformations → output
   • •Key logic: Important algorithms, validations, business rules
   • •Side effects: DB writes, API calls, file changes, state updates
   • •Dependencies: External libs, services, other modules
4. •

   Output format:

   code

   ## What it does
   [1-2 sentence summary]
   
   ## How it works
   1. [Step 1 with file:line references]
   2. [Step 2 with file:line references]
   3. [Step 3...]
   
   ## Key files
   - path/to/file.ts:123 - [what happens here]
   - path/to/other.rs:45 - [what happens here]
   
   ## Important logic
   [Any non-obvious algorithms, validations, or business rules]
   
   ## External dependencies
   [APIs called, DB tables used, services involved]
   
   ## Gotchas
   [Edge cases, assumptions, constraints, footguns]
   

5. •

   Focus on:

   • •The "why" behind non-obvious code
   • •Critical paths and error handling
   • •State mutations and side effects
   • •Include file:line references for easy navigation
6. •

   Keep concise:

   • •Skip obvious stuff (standard library usage, simple getters)
   • •Focus on the unique/complex parts
   • •Summarize repeated patterns instead of listing each instance

Tool access

allowed-tools:

• •Read
• •Grep
• •Glob
• •Bash
• •Write

Output method

1. •Generate explanation in the format above
2. •Determine project name:
   • •Get current directory name or git repo name
   • •Example: if in /path/to/my-project, project is my-project
3. •Write to explanations directory:
   • •Create dir: ~/Developer/explanations/<project-name>/ if not exists
   • •Write file: ~/Developer/explanations/<project-name>/<feature-name>-<timestamp>.md
   • •Use feature name from user query (e.g., "auth", "parser", "sync-logic")
   • •This keeps explanations outside project so they won't be committed
4. •Preview:
   • •Run gh markdown-preview ~/Developer/explanations/<project-name>/<file>.md in background
   • •This starts a server and opens browser, but runs in background to yield control
   • •User can stop server later with Ctrl+C or by killing the process
5. •Output to terminal:
   • •Show file path where explanation was saved
   • •Show brief summary
   • •Inform user that preview server is running in background

Examples

User: "How does authentication work?" Output:

## What it does
JWT-based auth with refresh tokens. Access tokens expire in 15min, refresh in 7 days.

## How it works
1. User sends credentials to /api/auth/login (routes/auth.ts:23)
2. Validate against DB, generate access + refresh tokens (lib/auth.ts:45)
3. Store refresh token in httpOnly cookie (lib/auth.ts:67)
4. Middleware validates access token on protected routes (middleware/auth.ts:12)
5. If expired, /api/auth/refresh issues new access token (routes/auth.ts:89)

## Key files
- routes/auth.ts:23 - Login endpoint, credentials validation
- lib/auth.ts:45 - Token generation with JWT
- middleware/auth.ts:12 - Token verification on each request

## Important logic
- Tokens signed with RS256 (private key in env)
- Refresh rotation: old token invalidated after refresh
- Rate limiting: 5 login attempts per 15min per IP

## Gotchas
- Refresh tokens stored in DB, must clear on logout
- Clock skew tolerance: 30 seconds
- CORS credentials must be true for cookies

Principles

• •Assume the user wrote this but forgot
• •Be a helpful reminder, not a lecture
• •Trace the actual execution path
• •Point to specific lines for deep-dive
• •Highlight non-obvious decisions