Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

flow-brief

Produce a single-file HTML swimlane brief that walks a system, module, or upcoming feature past a non-specialist reader, with provenance badges that separate what is measured from what is merely intended. Use this whenever someone needs to explain how something works to people outside the team — a flow diagram, an architecture walkthrough, an onboarding page, a design-review handout, a 介绍图 or 泳道图 — and especially when they describe the need without naming a format: "explain this to my boss", "draw how the data moves", "something the new hire can read", "I have to present this next week".

shaokeyibb · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add shaokeyibb/flow-brief --skill flow-brief

About this skill


name: flow-brief description: 'Produce a single-file HTML swimlane brief that walks a system, module, or upcoming feature past a non-specialist reader, with provenance badges that separate what is measured from what is merely intended. Use this whenever someone needs to explain how something works to people outside the team — a flow diagram, an architecture walkthrough, an onboarding page, a design-review handout, a 介绍图 or 泳道图 — and especially when they describe the need without naming a format: "explain this to my boss", "draw how the data moves", "something the new hire can read", "I have to present this next week".'

Flow Brief

Produce one self-contained .html file: a swimlane walkthrough that explains a system, a module, or an upcoming feature to someone who does not work inside it. No build step, no assets beyond one Google Fonts link, opens by double-click.

Match every reader-facing string to the language of the user's request (a Chinese request gets a Chinese page). Keep identifiers, file paths, commands, and error codes verbatim.

The reader is not your peer. A flow brief a fellow engineer enjoys is usually one a director abandons after three lines. Everything below exists to prevent that.

Fast path

  1. Frame it. From the one-line request pin three things: the subject boundary, the reader (default: competent, but does not work in this module), and the spine (where the flow enters, where it exits). Pick a row from the Scenario router.
  2. Count the modes — see Rule 1. Most subjects have one; decide before drafting.
  3. Collect by walking the call chain, not by reading docs. Code first, documents last: documents lag behind implementations, and the gap between them is often the most interesting thing you will put on the page. Details in references/collecting.md.
  4. Draft the artifact before polishing anything. Copy templates/skeleton.html and fill bands. Do not redesign the layout. The template owns geometry, color, theming, and responsiveness — that is what makes output stable across models and agents.
  5. Self-check: python <skill>/scripts/check_flow_brief.py <out.html>, then fix in the order the diagnostics list.

Do not read references/components.md before you have a draft — consult it when you need a component you have not used yet. Do not invent CSS classes: every visual affordance you need already exists in the template.

Scenario router

ScenarioHow to find the spineHow to apply the evidence ladder
Shipped system or moduleWalk the call chain from the entry pointMostly measured + code facts; illustrative only for sample payloads
Upcoming feature (no code yet)Walk the existing upstream and downstream, then splice the design in betweenExisting parts are measured/code facts; new parts are to build. The page then shows at a glance what already exists versus what must be built — exactly what a reviewer wants to know
Mixed (adding to a live system)Spine follows the live path; new steps splice inBoth, visually separated. The gap color is reserved for unbuilt things

For the upcoming-feature scenario the collection order reverses: read the design document first, then find the existing upstream/downstream in code, then mark the seam between them.

The five rules

Each rule exists because of a specific failure. Keep the failure in mind — it is how you tell whether you actually applied the rule.

Rule 1 · Separate the modes

Ask how many ways this flow can run. Most flows have exactly one. When that is the case, say so in a sentence and draw one mode — do not invent a second one to make the page look richer.

When there really is more than one, look for the split along one of these axes:

Split axisTypical shape
First time vs afterwardscold start vs cache hit; index build vs query
Full vs incrementalbulk import vs delta sync
Build vs consumeindex build vs query; compile vs run
Normal vs degradedhappy path vs fallback, retry, circuit-breaker
Sync vs asyncanswered inline vs queued for later
By actorwhat an admin traverses vs what an end user does

The test: if the two ways do different things at the same step, they are separate modes and each gets its own swimlane section. If one merely skips steps the other takes, it is not a mode — it is a branch, and it belongs inline as a .band alt.

Failure it prevents: merging two genuinely different runs into one linear flow. The reader can then never tell which steps happen every time and which happen only once — and that distinction usually drives every question they ask next.

Rule 2 · Node triad

Every step band ends with a .dflow strip answering exactly three questions: what upstream handed me / what I produced this round / who picks it up. All three, every band. "See above" is not an answer.

Failure it prevents: the most common swimlane failure — boxes and arrows everywhere, but no way to see how the data actually changes shape.

Rule 3 · Evidence ladder

Every factual claim on the page carries a provenance badge. Four rungs:

RungBadgeRequired backing
Measuredreal pillA run identifier, test case, or artifact path
Code factinline codeA file:line
Illustrativeplan pillShape is right, values invented — must be labeled
To buildgap pillNot implemented yet — must be labeled

Failure it prevents: the single most damaging failure in a brief written for leadership — drawing an intention as if it were the current state.

The point of forced labeling is not that the reader will verify you. It is that you cannot fool yourself: every cell demands a rung, and being unable to pick one is the signal that you have not collected enough. Go back to step 3.

Rule 4 · Three reading depths

On

Read the complete source ↗