agentleFS
anirudhaxeanirudhaxe/friday-skills/skills/html-flow-explain/SKILL.md

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.

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
  1. Distinctive:

    Create a thorough, visual explanation of a flow or topic as a single self-contained HTML file.

    line 8
  2. Distinctive:

    Every flow explain HTML must include these sections in order:

    line 16
  3. Distinctive:

    If the flow is very deep, show a high-level overview first, then zoom into the most complex step with a sub-diagram

    line 33
  4. Very specific:

    Use collapsible <details> sections for supplementary details

    line 65
  5. Distinctive:

    Before writing, explore the codebase thoroughly:

    line 72
  6. Distinctive:

    Read key function implementations

    line 75
  7. Distinctive:

    Check tests for expected behavior

    line 77

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Find the entry point(s) for the flow
  2. Trace the complete call chain
  3. Read key function implementations
  4. Note error paths and edge cases
  5. Check tests for expected behavior

After writing

End your response with: Flow explained: {filename} — providing a relative path to the HTML file.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.