Code Explanation

Expert skill for explaining complex code to developers at all levels through visual aids, step-by-step breakdowns, and progressive complexity.

Quick Start

1. Analyze Complexity First

Before explaining, assess the code:

• Lines of code and structural complexity

• Concepts used (async, decorators, generators, etc.)

• Design patterns present

• Difficulty level (beginner/intermediate/advanced)

2. Choose Explanation Depth

Audience Approach

Beginner Start with analogies, avoid jargon, explain fundamentals

Intermediate Focus on patterns and design decisions

Advanced Deep dive into implementation details and trade-offs

3. Use Visual Aids

Generate Mermaid diagrams for:

• Flow diagrams - Control flow and decision trees

• Class diagrams - Object relationships and inheritance

• Sequence diagrams - Method calls and interactions

4. Progressive Disclosure

Structure explanations from simple to complex:

• Overview - What does this code do? (1-2 sentences)

• Key Concepts - What programming concepts are used?

• Step-by-Step - Walk through the logic

• Deep Dive - Advanced details for those who want more

Output Format

Standard Explanation Structure

What This Code Does

[1-2 sentence summary]

Key Concepts

• Concept 1: Brief explanation
• Concept 2: Brief explanation

Visual Overview

[Mermaid diagram if complexity warrants]

Step-by-Step Breakdown

1. [First step with code reference]
2. [Second step with code reference] ...

Common Questions

• Why is X done this way?
• What happens if Y?

Related Patterns

[Links to similar patterns or alternatives]

Core Techniques

Explaining Algorithms

• State the problem being solved

• Show input → output transformation

• Visualize with step-by-step execution

• Analyze time/space complexity

Explaining Design Patterns

• Name the pattern

• Explain the problem it solves

• Show UML-style diagram

• List benefits and trade-offs

Explaining Complex Functions

• Signature and purpose

• Parameter meanings

• Return value

• Side effects (if any)

• Edge cases

Best Practices

• Use analogies - Compare to real-world concepts

• Show, don't just tell - Include code snippets

• Reference line numbers - Use file_path:line_number format

• Highlight gotchas - Point out non-obvious behavior

• Suggest improvements - When appropriate

Resources

• WORKFLOW.md - Detailed step-by-step methodology

• EXAMPLES.md - Comprehensive explanation examples

• TROUBLESHOOTING.md - Common issues and fixes

Integration

This skill auto-invokes when triggered by explanation-related keywords. For explicit control, use the /code-explain command.