Explain Code

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----> |
  |              | [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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: helderberto
• Source: helderberto/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.