Agent-Skill-Kit

Explaining Code

A skill that helps users understand code through analogies, ASCII diagrams, and conversational step-by-step walkthroughs.

Purpose

To make complex code accessible and understandable by breaking down technical concepts into relatable analogies, visual representations, and clear explanations. This skill is triggered when users ask questions like “How does this work?”, “Explain this code”, or “What’s happening here?”

Core Principles

1. Use Multiple Analogies — Different analogies resonate with different people
2. Visualize with ASCII — Diagrams make abstract concepts concrete
3. Step-by-Step Walkthroughs — Break complex flows into digestible chunks
4. Conversational Tone — Explain like you’re talking to a friend, not writing documentation
5. Highlight Misconceptions — Address common misunderstandings proactively

Usage

When asked to explain code, follow this approach:

1. Start with the Big Picture

Begin with a high-level analogy that captures the essence:

"Think of this function like a restaurant kitchen:
- Orders come in (input parameters)
- Chefs process them (business logic)
- Dishes go out (return values)"

2. Create Visual Diagrams

Use ASCII art to show structure, flow, or relationships:

┌─────────────┐
│   Request   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Validation  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Database   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Response   │
└─────────────┘

3. Walk Through Step-by-Step

Break down the execution flow with numbered steps and inline comments:

# Step 1: Receive the user's data
def process_user(user_data):
    # Step 2: Check if the data is valid (like checking ID at a club entrance)
    if not validate(user_data):
        return "Invalid data"
    
    # Step 3: Transform the data (like formatting a letter before mailing)
    cleaned = sanitize(user_data)
    
    # Step 4: Save to database (like filing a document)
    save_to_db(cleaned)
    
    # Step 5: Send confirmation (like a receipt)
    return "Success!"

4. Use Relatable Analogies

Connect technical concepts to everyday experiences:

Technical Concept	Analogy
Variables	Labeled boxes that hold things
Functions	Vending machines (input → process → output)
Loops	Assembly line workers repeating tasks
Conditionals	Forks in the road with signs
Classes	Cookie cutters (template for objects)
APIs	Restaurant menu (you order, kitchen handles it)
Caching	Keeping frequently used items on your desk
Recursion	Russian nesting dolls
Async/Await	Ordering food delivery while doing other things
Database indexes	Book index (quick lookup)

5. Address Common Misconceptions

Proactively clarify confusing points:

⚠️ Common Misconception:
"Does this loop run forever?"

No! The loop stops when i reaches 10. Think of it like climbing stairs:
you start at step 0 and stop when you reach step 10.

Response Structure

When explaining code, use this format:

1. Quick Summary (1-2 sentences)
2. Big Picture Analogy (relatable comparison)
3. Visual Diagram (ASCII art showing structure/flow)
4. Step-by-Step Walkthrough (numbered explanation)
5. Key Concepts (important takeaways)
6. Common Pitfalls (what could go wrong)

Examples

Example 1: Explaining a Simple Function

User: “How does this work?”

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

AI Response:

Quick Summary: This calculates Fibonacci numbers using recursion.

Analogy: Think of this like a family tree working backwards. To find out how many ancestors you have at generation N, you need to count ancestors from both your parents’ sides (N-1 and N-2), then add them together.

Visual Flow:

fibonacci(4)
    ├─ fibonacci(3)
    │   ├─ fibonacci(2)
    │   │   ├─ fibonacci(1) → 1
    │   │   └─ fibonacci(0) → 0
    │   └─ fibonacci(1) → 1
    └─ fibonacci(2)
        ├─ fibonacci(1) → 1
        └─ fibonacci(0) → 0

Step-by-Step:

1. Base case check: If n is 0 or 1, just return n (these are the “leaves” of our tree)
2. Recursive split: Otherwise, split into two smaller problems
3. Combine results: Add the results from both branches

Key Concept: Each call spawns two more calls, creating a tree of calculations that eventually hit the base cases and bubble back up.

⚠️ Common Pitfall: This is elegant but slow! It recalculates the same values many times. For fibonacci(4), it calculates fibonacci(2) twice. For larger numbers, this becomes exponentially wasteful.

Example 2: Explaining a Complex Pattern

User: “What’s happening in this decorator?”

def retry(max_attempts=3):
    def decorator(func):
        def wrapper(*args, **kwargs):
            for attempt in range(max_attempts):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if attempt == max_attempts - 1:
                        raise
            return None
        return wrapper
    return decorator

AI Response:

Quick Summary: This is a decorator that automatically retries a function if it fails.

Analogy: Think of this like a persistent salesperson:

• retry = The company policy (“try up to 3 times”)
• decorator = The training manual for the salesperson
• wrapper = The actual salesperson who follows the policy

Nesting Structure:

┌─────────────────────────────────────┐
│ retry(max_attempts=3)               │  ← Policy setter
│  ┌───────────────────────────────┐  │
│  │ decorator(func)               │  │  ← Training manual
│  │  ┌─────────────────────────┐  │  │
│  │  │ wrapper(*args, **kwargs)│  │  │  ← Actual worker
│  │  │  • Try the task         │  │  │
│  │  │  • If fail, retry       │  │  │
│  │  │  • Give up after N tries│  │  │
│  │  └─────────────────────────┘  │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Step-by-Step:

1. Outer function (retry): Sets the retry policy (how many attempts)
2. Middle function (decorator): Receives the function to be wrapped
3. Inner function (wrapper): Does the actual work:
   • Loops up to max_attempts times
   • Tries to run the original function
   • If it succeeds, returns immediately
   • If it fails, catches the error and tries again
   • On the last attempt, lets the error bubble up

Usage:

@retry(max_attempts=3)
def fetch_data():
    # This will auto-retry up to 3 times if it fails
    return requests.get(url)

⚠️ Common Misconception: “Why three nested functions?”

Each level serves a purpose:

• Level 1: Configuration (how many retries?)
• Level 2: Wrapping (which function to retry?)
• Level 3: Execution (actually doing the retries)

Best Practices

Do’s ✅

• Use concrete examples with actual values
• Show before/after states when explaining transformations
• Draw diagrams for anything with structure or flow
• Use emojis sparingly to highlight important points
• Provide multiple analogies if the first might not land
• Explain the “why” not just the “what”

Don’ts ❌

• Don’t use jargon without explaining it first
• Don’t assume prior knowledge of advanced concepts
• Don’t skip the “obvious” parts (they’re often not obvious)
• Don’t make analogies too complex (defeats the purpose)
• Don’t just restate the code in English

Tone Guidelines

• Conversational: “So what’s happening here is…” not “The function performs…”
• Encouraging: “This is a clever trick!” not “This is standard practice”
• Patient: Explain as many times as needed, in different ways
• Honest: If something is confusing or poorly written, acknowledge it

Visual Elements to Use

Flow Diagrams

Start → Check → Process → Save → End
          ↓
        Error? → Retry

State Transitions

[Idle] --request--> [Loading] --success--> [Done]
                         |
                       error
                         ↓
                     [Error]

Data Structures

Array: [1, 2, 3, 4, 5]
       ↑        ↑
     index 0  index 4

Tree:     10
         /  \
        5    15
       / \
      2   7

Call Stacks

main()
  └─ processData()
      └─ validate()
          └─ checkEmail()  ← Currently executing

Notes

• Adapt complexity to the user’s apparent skill level
• If they ask follow-up questions, they’re engaged—go deeper
• If they seem lost, back up and use simpler analogies
• Always validate understanding: “Does that make sense?”
• Encourage questions: “What part would you like me to clarify?”