Code Visual Explain
Turn confusing code into a clear mental model.
Use this skill when the user asks for an explanation, walkthrough, diagram, flow, architecture overview, or "how this code works."
Workflow
1. Read the actual code first
- Inspect the relevant files, types, tests, or diffs before explaining.
- Anchor the explanation in real symbols, control flow, and file references.
- Separate what is directly confirmed by code from what is inferred.
2. Choose the right visual
Pick the diagram style that matches the question:
flowchart for control flow, request paths, or decision branchessequenceDiagram for interactions between services, classes, APIs, or async stepsclassDiagram or a simple relationship map for structure and ownershipstateDiagram for lifecycles, modes, and transitions- Prefer mermaid but use ASCII when the concept is tiny
- Use color to indicate different consepts
3. Explain in layers
Default structure:
- A one or two sentence plain-English summary
- A concrete analogy that maps to the real code
- A diagram that shows the important moving parts
- A step-by-step walkthrough of what happens
- A short "gotchas" section covering edge cases, misconceptions, or easy-to-miss behavior
For larger systems, start with the overview and then zoom into the most important path.
Rules
- Do not invent behavior that is not visible in the code.
- Do not use an analogy without mapping it back to the actual code elements.
- Keep diagrams compact and readable. Avoid decorative nodes or irrelevant branches.
- If the code is ambiguous, say what is uncertain instead of pretending it is settled.
- Match the depth to the user's goal: onboarding overview, bug-hunt walkthrough, or deep implementation explanation.
1---2name: code-explain-visually3description: Explain code with diagrams, analogies, and step-by-step walkthroughs. Use when the user wants help understanding a function, file, module, request flow, architecture slice, or unfamiliar codebase area, especially when a visual explanation would make the behavior easier to follow.4---56# Code Visual Explain78Turn confusing code into a clear mental model.910Use this skill when the user asks for an explanation, walkthrough, diagram, flow, architecture overview, or "how this code works."1112## Workflow1314### 1. Read the actual code first1516- Inspect the relevant files, types, tests, or diffs before explaining.17- Anchor the explanation in real symbols, control flow, and file references.18- Separate what is directly confirmed by code from what is inferred.1920### 2. Choose the right visual2122Pick the diagram style that matches the question:2324- `flowchart` for control flow, request paths, or decision branches25- `sequenceDiagram` for interactions between services, classes, APIs, or async steps26- `classDiagram` or a simple relationship map for structure and ownership27- `stateDiagram` for lifecycles, modes, and transitions28- Prefer mermaid but use ASCII when the concept is tiny29- Use color to indicate different consepts3031### 3. Explain in layers3233Default structure:34351. A one or two sentence plain-English summary362. A concrete analogy that maps to the real code373. A diagram that shows the important moving parts384. A step-by-step walkthrough of what happens395. A short "gotchas" section covering edge cases, misconceptions, or easy-to-miss behavior4041For larger systems, start with the overview and then zoom into the most important path.4243## Rules4445- Do not invent behavior that is not visible in the code.46- Do not use an analogy without mapping it back to the actual code elements.47- Keep diagrams compact and readable. Avoid decorative nodes or irrelevant branches.48- If the code is ambiguous, say what is uncertain instead of pretending it is settled.49- Match the depth to the user's goal: onboarding overview, bug-hunt walkthrough, or deep implementation explanation.
RileyCornelius