---

name: code-explainer description: Explain code in plain English with visual diagrams. Use when user wants to understand how code works or needs documentation. allowed-tools: "Read,Glob,Grep" version: 1.0.0

Code Explainer

Analyze and explain code in plain English with optional visual diagrams.

Overview

This skill reads code files, analyzes their structure and behavior, and produces clear explanations suitable for documentation or onboarding. It can generate ASCII diagrams for data flow and component relationships.

Instructions

Step 1: Identify Target Code

Ask user for:

• Specific file path, OR
• Function/class name to find, OR
• Feature area to explore

If given a name, use Grep to locate the code:

CopyGrep pattern: (function|class|def|const)\s+<name>

Step 2: Read and Analyze

Read the target file(s) and identify:

• Purpose: What problem does this code solve?
• Inputs: What data/parameters does it receive?
• Outputs: What does it return or produce?
• Dependencies: What other code/services does it use?
• Side effects: Does it modify state, files, or external systems?

Step 3: Trace Data Flow

For complex code, trace how data moves:

1. Entry points (function calls, event handlers)
2. Transformations (data processing steps)
3. Exit points (returns, writes, API calls)

Step 4: Generate Explanation

Structure the explanation as:

Copy## [Code Name]

### Purpose
[1-2 sentence summary of what this code does]

### How It Works
[Step-by-step explanation in plain English]

### Key Components
- **[Component 1]**: [Role]
- **[Component 2]**: [Role]

### Data Flow
[ASCII diagram if helpful]

### Usage Example
[Simple code example showing how to use it]

### Dependencies
- [List of imports/requirements]

Output Format

For Functions

Copy## `processPayment(order, paymentMethod)`

### Purpose
Validates and processes a customer payment, updating order status.

### How It Works
1. Validates the order exists and is in 'pending' status
2. Checks payment method is enabled for the customer
3. Calls payment gateway API with order amount
4. Updates order status to 'paid' or 'failed'
5. Sends confirmation email on success

### Data Flow
┌─────────┐    ┌──────────┐    ┌─────────┐
│  Order  │───>│ Validate │───>│ Gateway │
└─────────┘    └──────────┘    └────┬────┘
                                    │
              ┌──────────┐    ┌─────v─────┐
              │  Email   │<───│  Update   │
              └──────────┘    └───────────┘

For Classes/Modules

Copy## UserAuthService

### Purpose
Handles user authentication, session management, and permissions.

### Key Methods
| Method | Purpose |
|--------|---------|
| `login(email, password)` | Authenticate user credentials |
| `logout(sessionId)` | Invalidate user session |
| `checkPermission(user, action)` | Verify user can perform action |

### Component Diagram
┌─────────────────────────────────────┐
│          UserAuthService            │
├─────────────────────────────────────┤
│  ┌─────────┐  ┌─────────────────┐  │
│  │ Session │  │ Permission      │  │
│  │ Manager │  │ Checker         │  │
│  └────┬────┘  └────────┬────────┘  │
│       │                │           │
│  ┌────v────────────────v────┐      │
│  │      User Repository     │      │
│  └──────────────────────────┘      │
└─────────────────────────────────────┘

Diagram Conventions

Use ASCII art for diagrams:

• ┌─┐ └─┘ for boxes
• ───> for data flow
• │ for vertical connections
• Keep diagrams under 60 characters wide

Notes

• Adjust technical depth based on audience (ask if unclear)
• For very complex code, offer to explain in parts
• Flag any concerning patterns (security issues, antipatterns)