ReddRadar
Agent skill
code-explanation
Install this agent skill to your Project
npx add-skill https://github.com/brendendurham/claude-code-config/tree/main/skills/code-explanation
SKILL.md
Code Explanation Skill
Explain code clearly using ASCII diagrams, real-world analogies, and Mermaid visualizations.
When to Use
- User asks "explain this code" or "what does this do"
- User wants to understand how something works
- User asks for architecture visualization
- User needs help understanding complex logic
Explanation Framework
Step 1: Quick Summary
Start with a one-sentence plain English summary:
"This function takes a list of orders, filters out cancelled ones, calculates the total, and applies any applicable discounts."
Step 2: Identify the Audience Level
Adjust explanation depth based on context:
- Beginner: Use analogies, avoid jargon, explain fundamentals
- Intermediate: Focus on patterns, design decisions, trade-offs
- Expert: Discuss edge cases, performance, alternatives
Step 3: Break Down the Logic
Use structured sections:
- Purpose: What problem does this solve?
- Inputs: What data comes in?
- Process: What transformations happen?
- Outputs: What comes out?
- Side Effects: What else changes?
ASCII Diagram Patterns
Data Flow
Input Process Output
| | |
v v v
+------+ +-----------+ +--------+
| User | -> | Validator | -> | Result |
| Data | | Function | | Object |
+------+ +-----------+ +--------+
|
v
+----------+
| Database |
+----------+
Function Pipeline
[Raw Data]
|
v
+-------------+
| Parse JSON |
+-------------+
|
v
+-------------+
| Validate |
+-------------+
|
+-+-+
| |
v v
Valid Invalid
| |
v v
+----+ +-------+
|Save| |Error |
+----+ +-------+
Class Relationships
+----------------+
| BaseClass |
+----------------+
| - privateVar |
| + publicMethod |
+-------+--------+
|
+-------+-------+
| |
v v
+----------+ +----------+
| ChildA | | ChildB |
+----------+ +----------+
| + methodA| | + methodB|
+----------+ +----------+
State Machine
+--------+
| START |
+---+----+
|
v
+--------+--------+
| |
v v
+-------+ +--------+
| IDLE |<------>| ACTIVE |
+---+---+ +----+---+
| |
v v
+-------+ +--------+
| ERROR | | DONE |
+-------+ +--------+
Request/Response Flow
Client Server Database
| | |
| 1. POST /users | |
|----------------------->| |
| | 2. INSERT INTO users |
| |----------------------->|
| | |
| | 3. Return new ID |
| |<-----------------------|
| 4. 201 Created | |
|<-----------------------| |
| | |
Mermaid Diagram Generation
Flowchart
flowchart TD
A[Start] --> B{Is Valid?}
B -->|Yes| C[Process Data]
B -->|No| D[Return Error]
C --> E[Save to DB]
E --> F[Send Response]
D --> F
F --> G[End]
Sequence Diagram
sequenceDiagram
participant U as User
participant A as API
participant D as Database
participant C as Cache
U->>A: Request Data
A->>C: Check Cache
alt Cache Hit
C-->>A: Return Cached
else Cache Miss
A->>D: Query Database
D-->>A: Return Results
A->>C: Store in Cache
end
A-->>U: Send Response
Class Diagram
classDiagram
class User {
+String id
+String email
+String name
+getProfile()
+updateSettings()
}
class Order {
+String id
+User user
+List items
+calculateTotal()
}
class Item {
+String id
+String name
+Number price
}
User "1" --> "*" Order : places
Order "*" --> "*" Item : contains
State Diagram
stateDiagram-v2
[*] --> Pending
Pending --> Processing: submit
Processing --> Completed: success
Processing --> Failed: error
Failed --> Pending: retry
Completed --> [*]
Architecture Diagram
graph TB
subgraph Client
A[Web App]
B[Mobile App]
end
subgraph Backend
C[API Gateway]
D[Auth Service]
E[User Service]
F[Order Service]
end
subgraph Data
G[(PostgreSQL)]
H[(Redis Cache)]
I[(S3 Storage)]
end
A --> C
B --> C
C --> D
C --> E
C --> F
E --> G
E --> H
F --> G
F --> I
Real-World Analogies
Common Programming Concepts
| Concept | Analogy |
|---|---|
| Variable | A labeled box that stores something |
| Function | A recipe that takes ingredients and produces a dish |
| Class | A blueprint for building houses |
| Instance | An actual house built from the blueprint |
| Interface | A job contract specifying required skills |
| Inheritance | Children inheriting traits from parents |
| Callback | Leaving your phone number for a callback |
| Promise | An IOU note that will be fulfilled later |
| Cache | A sticky note reminder of frequently used info |
| Queue | A line at a coffee shop (FIFO) |
| Stack | A stack of plates (LIFO) |
| Hash Map | A library card catalog for quick lookups |
| API | A restaurant menu - shows what you can order |
| Database | A giant filing cabinet with organized folders |
| Middleware | Security checkpoints before entering a building |
| Event Loop | A receptionist handling one task at a time |
Architecture Patterns
| Pattern | Analogy |
|---|---|
| Microservices | A food court with specialized restaurants |
| Monolith | A single restaurant doing everything |
| Load Balancer | A host at a busy restaurant seating guests |
| Message Queue | A post office sorting and delivering mail |
| Circuit Breaker | A fuse box that trips to prevent damage |
| Pub/Sub | A newspaper subscription service |
Explanation Template
## What This Code Does
{One-sentence summary}
## Visual Overview
{ASCII diagram or Mermaid diagram}
## Step-by-Step Breakdown
### 1. {First major step}
{Explanation with code snippet}
### 2. {Second major step}
{Explanation with code snippet}
## Analogy
Think of this like {real-world comparison}...
## Key Concepts
- **{Concept 1}**: {Brief explanation}
- **{Concept 2}**: {Brief explanation}
## Common Questions
**Q: Why is it done this way?**
A: {Explanation of design decision}
**Q: What could go wrong?**
A: {Edge cases and error scenarios}
Tips
- Start simple: Give the overview before diving into details
- Use visuals: A diagram often explains better than paragraphs
- Relate to familiar concepts: Analogies bridge the knowledge gap
- Show, don't just tell: Include relevant code snippets
- Anticipate questions: Address the "why" not just the "what"
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
brendendurham/claude-code-config
api-documentation
brendendurham/claude-code-config
doc-intelligence
This skill orchestrates comprehensive documentation intelligence operations. Use when asked to "analyze documentation", "learn from docs", "create SOPs from documentation", "maximize documentation understanding", or any request involving systematic multi-agent documentation analysis with parallelization.
brendendurham/claude-code-config
commit-message-generator
brendendurham/claude-code-config
parallel-orchestration
This skill should be used when the user asks to "run multiple agents", "parallel review", "comprehensive analysis", "full review", "multi-agent workflow", or needs to coordinate multiple specialized agents working simultaneously. Provides patterns for launching agents in parallel and synthesizing results.
brendendurham/claude-code-config
pr-review-standards
mattpocock/skills
edit-article
Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
Didn't find tool you were looking for?