Flow Brief: Explain Systems to Non-Technical Readers

Where this fits

A product manager asks you to "explain the new sync flow to my boss" before next week's review. You have a diagram in your head, but no audience-friendly format. flow-brief turns that vague request into a single self-contained HTML swimlane walkthrough: no build step, no external assets, just a file you can double-click and share. It is built for the moment when the reader is outside your team and the format is not named.

Why agents benefit

• Agents can infer the intended format from vague phrases like "draw how the data moves" and generate a swimlane brief without asking for more clarification.
• The skill produces one .html file with inline styling, so the agent can write it to disk and hand the user a directly openable artifact.
• Reader-facing text is localized to the request language (e.g., Chinese request -> Chinese page), while identifiers and paths stay verbatim, making the output useful for both local and cross-team contexts.
• Provenance badges distinguish measured facts from intended behavior, so the agent can mark source-of-truth claims differently from assumptions or roadmap items.
• The concise single-file format is easy for an agent to validate, regenerate, or iterate on after codebase changes.

Practical scenarios

Onboarding a new hire

When a new engineer joins, they need the shape of the system before they read source files. A flow brief walks them through module boundaries and data flow in order, with badges showing which parts are implemented today versus planned.

Presenting to non-technical stakeholders

Your manager asks for "a few slides on how billing works." Instead of a dense architecture doc, the agent produces a swimlane page that explains each actor and step in plain language. The reader can scroll at their own pace, and the provenance badges tell them whether a behavior is live or still in design.

Design review for a feature not yet built

For an upcoming feature, there is no runtime data to measure. The agent can still build a flow brief using intended behavior, clearly annotating assumptions. That makes design-review handouts honest: readers see what is decided and what is still being evaluated.

Add it to your agent workflow

Install the skill with:

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

Then ask your agent in natural language:

Explain how the inventory reservation works to our support lead. Make a flow-brief.

The agent should inspect the relevant code or spec, then emit a single HTML file with swimlanes and provenance badges. If you need a different audience or language, say so in the same request.

Compare before adopting

Before committing, compare flow-brief against other diagram or research skills on: output quality on your own codebase; whether the maintainer is responsive; how often the skill is updated; and whether the generated HTML matches your team's sharing habits. A 14-star skill can still be the right fit if the output format is exactly what your workflow lacks.

Why it is worth tracking

The signal here is not star count; it is the design opinion baked into the skill: make one file, respect the reader's language, and separate measured facts from intentions. That opinion aligns with a common agent failure mode—producing verbose, jargon-heavy artifacts for non-specialists. As more teams ask agents for "something the new hire can read," skills like this become a reusable default. You can also track this skill on OpenAgentSkill at https://www.openagentskill.com/skills/shaokeyibb-flow-brief and evaluate it again when your agent needs to produce onboarding or review materials.