agentleFS
tejastn10tejastn10/workbench/skills/study/flow-diagram/SKILL.md

flow-diagram

Skill1 starsChanged 2 months agoMITView on GitHub

Explain a concept, algorithm, request path or codebase flow as a diagram you step through — pick the one question it answers and the diagram type that fits (flowchart, sequence, state, data-flow), keep it to 5–12 nodes grounded in real code with file:line, then build an interactive HTML page where Next/Prev highlights each step and a side panel narrates what happens there, why, and what can go wrong. Use when the user says "draw me the flow", "how does X flow", "walk me through the request path", "flow diagram of X", "visualise how this works", or a lesson needs a diagram.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write the one question first: "What happens between the click and the row in Postgres?" Then pick the type from what moves through it:

    line 16
  2. Very specific:

    If it's code, read it first.

    line 28
  3. Very specific:

    When the host can publish a page (Claude Code's Artifact tool), publish it and give the link.

    line 63

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

Flow diagram

A diagram for learning, not for docs. A static picture shows every box at once; a learner needs to follow one step at a time and know why each step happens. For a static figure to drop into a README or doc (SVG, PNG, .excalidraw), use visual/diagram. For an idea that's better shown as a working machine, use visual/anatomy.

1. Decide what it answers

Write the one question first: "What happens between the click and the row in Postgres?" Then pick the type from what moves through it:

What you're showingType
Decisions and branches in one processflowchart LR (pipelines) / TD (hierarchies)
Messages between actors over timesequenceDiagram
A thing's lifecycle (order, job, connection)stateDiagram-v2
Data being transformed stage by stageflowchart LR, with the data's shape in the edge labels

2. Ground it

  • If it's code, read it first. Each node names the real function, queue or table, and its panel cites path:line. Don't add boxes the code doesn't have.
  • 5–12 nodes. More than that → split it into an overview diagram plus a zoomed diagram per hop, linked from the overview's node.
  • Short node labels. The detail goes on the edges ("JWT in header", "batch of 100") and in the panel.
  • Show the unhappy path too: the retry, the DLQ, the 401. Draw it as a second route the reader can switch on.

3. Write the steps

An ordered list, one entry per step, each with:

  • target — the node or edge id it highlights.
  • What happens — one or two sentences.
  • Why — the reason the system is built this way.
  • What can go wrong — the failure mode at this hop, if there is one.
  • ref — path:line or the source of the claim.

4. Build the page

A single self-contained .html file (CSS and JS inline). Keep the Mermaid source beside it as <slug>.mmd.

  • Render the diagram with mermaid@12.1.0 from a pinned CDN. After it renders, find the node and edge elements by id and toggle a .active class. Don't redraw the diagram per step.
  • Stepper: Prev / Next buttons and ← → keys. The active element is highlighted, everything before it is dimmed-but-visible, and everything after it is faint.
  • Panel beside the diagram (below it on phones) shows the step's what / why / what-can-go-wrong / ref.
  • Path toggle for the unhappy path; click any node to jump to its step.
  • Light and dark themes from CSS variables. Respect prefers-reduced-motion (no transitions on highlights).

When the host can publish a page (Claude Code's Artifact tool), publish it and give the link. Inside a study/head-first or study/dissect-paper page, embed the same stepper instead of writing a separate file.

Anti-patterns

  • ❌ A diagram of everything — 30 boxes and no question.
  • ❌ Nodes invented for symmetry that don't exist in the code.
  • ❌ Labels that only say "process" or "handle" — name the mechanism.
  • ❌ Only the happy path.
  • ❌ All the explanation in a paragraph under the diagram instead of per step.
  • ❌ Re-rendering the whole diagram on every step (flicker, lost zoom).

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.