mcpField
E
explain-code

explain-code

github.com/helderbertoDevelopment2060 installsUpdated 1w ago
Repository

About explain-code

explain-code is a skill for explaining code conversationally through an analogy, an ASCII diagram, a step-by-step walkthrough, and a common gotcha. It is intended for people seeking structured explanations of code and its flow.

Key features

  1. 01Begins with an everyday analogy
  2. 02Illustrates structure with ASCII diagrams
  3. 03Explains execution step by step
  4. 04Highlights a common gotcha
  5. 05Offers multiple diagram formats

Use cases

  1. 01Explaining a function’s control flow
  2. 02Clarifying how modules call one another
  3. 03Showing a data structure’s hierarchy

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/helderberto/agent-skills --skill explain-code

After installing, type/explain-codein Claude Code to confirm it loaded.

Details

From the project README

When explaining code, always include:

  1. Start with an analogy: Compare the code to something from everyday life
  2. Draw a diagram: Use ASCII art to show the flow, structure, or relationships
  3. Walk through the code: Explain step-by-step what happens
  4. Highlight a gotcha: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

Diagram Types

Flow / Control flow:

Input -> [Validate] -> [Process] -> [Save] -> Output
                          |
                       [Error] -> Return 400

Call stack / Sequence:

Client          API           DB
  |--request-->  |             |
  |              |--query----> |
  |              |<--result--- |
  |<-response--  |             |

Tree / Hierarchy:

App
+-- Header
|   +-- Nav
+-- Main
|   +-- Sidebar
|   +-- Content
+-- Footer

State machine:

[Idle] --submit--> [Loading] --success--> [Done]
                       |
                    error|
                   [Failed] --retry--> [Loading]

Data structure:

User {
  id: string
  profile: Profile --> { name, avatar, bio }
  posts: Post[]    --> [{ id, title, body }]
}

Before / After:

Before:               After:
fn()                  fn()
  doA()                 doA()
  doB()                 doB()
  doC()     ->          helpers()
  doD()                   doC()
  doE()                   doD()
                          doE()

Error Handling

  • Code references external files/modules -- read them before explaining
  • Diagram too complex -- split into multiple focused diagrams, each covering one concept

Comments

Markdown supported