html-flow-explain
Skill0 starsChanged 5 months agoMITView on GitHub
Explain a flow, topic, or code path by creating a single self-contained HTML artifact with box diagrams, callstack walkthroughs, key files, gotchas, and code snippets. Use when the user asks "explain how X works", "walk me through the flow of Y", "what happens when Z", or wants to understand a complex code path or concept.
In this repository7 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Create a thorough, visual explanation of a flow or topic as a single self-contained HTML file.
- Distinctive: line 16
Every flow explain HTML must include these sections in order:
- Distinctive: line 33
If the flow is very deep, show a high-level overview first, then zoom into the most complex step with a sub-diagram
- Very specific: line 65
Use collapsible <details> sections for supplementary details
- Distinctive: line 72
Before writing, explore the codebase thoroughly:
- Distinctive: line 75
Read key function implementations
- Distinctive: line 77
Check tests for expected behavior
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
HTML Flow Explain
Create a thorough, visual explanation of a flow or topic as a single self-contained HTML file. The explanation must walk the reader step by step through the entire flow, from entry point to completion, with all the context needed to understand it deeply.
Output format
Write the output to a single .html file in the current working directory. Use a descriptive filename like flow-{topic-name}.html. The HTML must be fully self-contained (CSS and JS inline, no external dependencies). Create the output in dark mode (adjust colors of the elements like text etc if needed for good dark mode visibility).
Structure
Every flow explain HTML must include these sections in order:
1. Header
- Title:
How {Topic} Works - Tags/keywords for the topic
- Date
2. Summary
- 3-4 sentence explanation of the flow at a high level
- What problem it solves and when this flow is triggered
- Prerequisites — what the reader should already understand
3. Flow Diagram
- Pure HTML/CSS box diagram showing the end-to-end flow
- Each box = a logical step (function call, component, service)
- Arrows connecting boxes with labels describing the data/trigger
- Branching paths for conditionals, error handling shown differently (dashed borders/arrows)
- If the flow is very deep, show a high-level overview first, then zoom into the most complex step with a sub-diagram
4. Callstack Walkthrough
- Numbered steps tracing a single request/action from start to finish
- Each step: step number | file:line | what happens | key variables/state
- Show the actual call chain, not a high-level abstraction
- Include the exact function signatures for each step
5. Key Files
- Table of files involved in the flow
- Columns: file path | role in the flow | key exports/classes | approximate line count
6. Code Snippets
- 3-6 code snippets that are essential to understanding the flow
- Annotate important lines with inline comments
- Include: entry point, core logic, error handling, return path
- Maximum ~30 lines per snippet
7. Gotchas
- Bullet list of things that commonly go wrong
- For each: what the gotcha is, why it happens, how to avoid it
- Include real-world examples or edge cases where this gotcha manifested
8. Open Questions
- Bullet list of any remaining questions about the flow
- Mark which were answered during research vs. still unresolved
Style guidelines
- System-ui font stack, max-width 960px centered
- Box diagrams: use CSS flexbox/grid with borders and arrow characters (→, ↳, ⇢) — no SVG libraries needed
- Code blocks: monospace font, subtle background, line numbers
- Use collapsible
<details>sections for supplementary details - Light background, dark text, a single accent color for emphasis
- The page should be scannable — someone should be able to glance at the flow diagram and understand the whole picture, then dive into details
- Print-friendly layout
Research approach
Before writing, explore the codebase thoroughly:
- Find the entry point(s) for the flow
- Trace the complete call chain
- Read key function implementations
- Note error paths and edge cases
- Check tests for expected behavior
After writing
End your response with: Flow explained: {filename} — providing a relative path to the HTML file.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

