explain-code_skill

Overview

This skill explains code using visual diagrams and everyday analogies to make concepts accessible. It combines ASCII-art flowcharts, step-by-step walkthroughs, and clear highlights of common pitfalls to teach how code works. The goal is fast comprehension for readers of varying technical levels. Explanations stay natural and practical.

How this skill works

When given code, the skill first maps the program to one or more familiar analogies to set high-level context. It then renders simple ASCII diagrams showing control flow, data structures, or module relationships. Next it walks through the code line-by-line or block-by-block, describing intent and effects. Finally it flags likely bugs, performance issues, and typical misunderstandings with concise remediation tips.

When to use it

• Teaching a codebase to new contributors or teammates
• Explaining how a function, class, or module works for review
• Preparing documentation or onboarding materials with visuals
• Debugging by locating likely sources of common errors
• Converting complex logic into simple, teachable pieces

Best practices

• Start with a high-level analogy before diving into code details
• Keep ASCII diagrams minimal and focused on the core flow
• Walk through examples with concrete input and expected output
• Call out assumptions, side effects, and state changes explicitly
• List common mistakes and how to detect/fix them

Example use cases

• Explain a recursive algorithm by comparing it to nested boxes and drawing the call tree
• Document an HTTP handler by showing a request-to-response flowchart and stepwise data transformations
• Teach a contributor how a caching layer interacts with a database using a diagram and highlight race conditions
• Break down a complex class by mapping methods to responsibilities and showing object relationships
• Review a pull request by explaining changed logic, drawing the new flow, and identifying potential regressions