joaquimscosta 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_numberformat - 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.