Skip to content
Skills Library
Design & UX · Conversion & formats

decompose-prototype

/decompose-prototype

Turns a UI prototype -- a live web app you can browse, a Claude Design project link, a local prototype source file on disk, or screenshots/images you share -- into a dated documentation folder with two markdown deliverables built from real screenshots of the actual prototype (or, when no live render is available, careful analysis of the source itself) -- user-flow.md (a happy-path-plus-edge-cases diagram and step-by-step narrative) and mockups.md (each main screen's real screenshot, or a clearly-flagged source-only writeup, next to its requirements). Use this whenever the user wants to documen

Author
vadeg ↗
Licence
MIT
Last repository change
10.08.2026

Assessment and security

87/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability17 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Turns a UI prototype -- a live web app you can browse, a Claude Design project link, a local prototype source file on disk, or screenshots/images you share -- into a dated documentation folder with two markdown deliverables built from real screenshots of the actual prototype (or, when no live render is available, careful analysis of the source itself) -- user-flow.md (a happy-path-plus-edge-cases diagram and step-by-step narrative) and mockups.md (each main screen's real screenshot, or a clearly-flagged source-only writeup, next to its requirements). Use this whenever the user wants to documen

Original author description

Turns a UI prototype -- a live web app you can browse, a Claude Design project link, a local prototype source file on disk, or screenshots/images you share -- into a dated documentation folder with two markdown deliverables built from real screenshots of the actual prototype (or, when no live render is available, careful analysis of the source itself) -- user-flow.md (a happy-path-plus-edge-cases diagram and step-by-step narrative) and mockups.md (each main screen's real screenshot, or a clearly-flagged source-only writeup, next to its requirements). Use this whenever the user wants to documen

How it works

  1. Step 1: Get the actual prototype in front of you
  2. Step 2: Scope it before you build everything
  3. Step 3: Identify the happy path and the real edge cases
  4. Step 4: Set up the output folder
  5. Step 5: Give every screen a stable ID and capture its screenshot(s)
  6. Step 6: Write mockups.md
  7. Step 7: Write user-flow.md
  8. Step 8: Hand off
Original SKILL.md headings · 97 lines, 2,061 words
SKILL.md preview
---
name: decompose-prototype
description: Turns a UI prototype -- a live web app you can browse, a Claude Design project link, a local prototype source file on disk, or screenshots/images you share -- into a dated documentation folder with two markdown deliverables built from real screenshots of the actual prototype (or, when no live render is available, careful analysis of the source itself) -- user-flow.md (a happy-path-plus-edge-cases diagram and step-by-step narrative) and mockups.md (each main screen's real screenshot, or a clearly-flagged source-only writeup, next to its requirements). Use this whenever the user wants to document, formalize, or hand off a prototype's flow or screens -- phrases like "map out the user flow," "document the happy path and edge cases," "turn this prototype into mockups," "what are the requirements for this screen," or "I need something to hand to design/PM/eng" all point here, even if the user doesn't say "artifact," "screenshot," or name this skill directly, and even if all they've handed you is a local prototype file rather than a running app.
---

# Decompose a UI Prototype into Flow + Mockup Docs

This skill produces two markdown files from an existing prototype, saved together with the screenshots they reference: **user-flow.md** (diagram + narrative, happy path and edge cases) and **mockups.md** (each main screen's real screenshot next to its requirements). They serve different audiences — the flow doc is for anyone reasoning about behavior and branching, the mockups doc is for anyone building or reviewing the screens themselves — so keep them as two files rather than merging them, unless the user asks for one combined document.

The whole point of this skill is that the mockups show the *actual* prototype, not a redrawn approximation of it. Never hand-build an HTML/CSS rendition of a screen as a substitute for a screenshot — if you can't get a real screenshot of something, say so and leave a gap rather than fabricating a stand-in that looks plausible but isn't real.

## Step 1: Get the actual prototype in front of you

Don't work from a description of the prototype if the real thing is available — a flow or mockup built from what you assume a screen looks like will miss the actual states, copy, and edge cases that make the deliverable useful. There are four possible sources; figure out which one you actually have before doing anything else.

**A live web app.** Use the `chrome-devtools` browser tools to navigate it yourself: load the entry point, take a snapshot, then click through the primary path a real user would take. Deliberately go looking for the states that don't show up if you only click the happy path once — submit a form with invalid input, trigger an empty state (empty search results, empty cart), let something load, try to go back or cancel mid-flow, hit a boundary (e.g. a field's max length). These are exactly the edge cases the deliverable needs, and they're easy to miss if you only look at the "success" screen of each step. Since it's someone's running prototype, avoid anything destructive or hard to undo — don't submit real payments, delete real records, or send real emails/messages if the app is wired up to anything live; if you're unsure whether an action is safe to try, ask first. Before capturing anything, resize the page to one consistent viewport (e.g. 1280×800) so every screenshot in the deliverable shares the same frame — a mockups doc where every screen is a different size reads as sloppy even when the content is right.

**A Claude Design project link.** If the user gives you a `claude.ai/design/p/<id>` URL, or says the prototype lives in Claude Design, use the `claude-design` MCP tools instead of treating the link as an ordinary web page: `get_project` to confirm it, `list_files` to find the entry HTML file, and `render_preview` on that file to get a `serve_url`. Open that `serve_url` in `chrome-devtools` and drive it exactly like a live web app above — navigate, click through states, resize to a fixed viewport, screenshot. `serve_url` is a short-lived token-bearing link meant only for your own browser tooling; never put it in the deliverable, in chat, or in any file you write — the durable link you may reference back to the user is the project's `open_url`.

**A local prototype source file with no live render.** Sometimes what you're handed is a source export sitting on disk — e.g. a standalone HTML file — that references assets (a `support.js`, a `_ds/<design-system>` bundle, an API) that aren't actually present locally, so there's nothing to open in a browser and get a real render from. Don't silently guess whether a live version exists somewhere — ask the user whether they have a live URL or a Claude Design link they'd rather you use instead, so you get real screenshots. If they confirm there isn't one, work from the source alone: read the markup and logic carefully enough to reconstruct screens, states, and behavior — conditional-render blocks, state fields, disabled/validation logic, event handlers — with the same rigor Step 3 asks for, just derived from code instead of observed by clicking. Say explicitly in the output that these screens have no real screenshot (see Steps 5 and 6) rather than hand-building an HTML/CSS approximation to stand in for one — that would violate the whole point of this skill.

**Screenshots or images shared by the user.** Read each image and work from what's actually shown. If the sequence between screens isn't obvious from filenames or content — which screen leads to which — ask the user to confirm the order rather than guessing; a wrong sequence quietly corrupts both deliverables. If the images only show the happy path with no error/empty/loading states visible, say so explicitly in the output rather than inventing edge-case screens that were never shown to you (see Step 3). These are already real screenshots — Step 5 copies them into place rather than capturing new ones.

If it's unclear which of these you actually have, or whether a local file has a live counterpart worth using instead, ask before doing anything else — don't silently auto-detect or assume one.

## Step 2: Scope it before you build everything

If the prototype has more than a handful of screens or flows, don't silently try to document all of it — check with the user which flow(s) and which screens actually matter for this deliverable. Exhaustive coverage of a large app is a lot of wasted work if only one flow was actually in scope, and it's cheap to ask up front.

## Step 3: Identify the happy path and the real edge cases

For the flow you're documenting, work out:
- **The happy path** — the single sequence of steps a user takes when everything goes right.
- **The edge cases actually present in the prototype** — validation errors, empty states, loading/pending states, timeouts, permission/auth boundaries, cancel/back navigation, retries. Base these on what you actually observed in Step 1, not on generic "what edge cases does every app have" boilerplate.
- **Gaps** — places where the prototype doesn't define behavior (e.g., no visible error state for a failed submission). Don't invent one to fill the gap. Flag it as an open design question in the output instead — that's more useful to whoever receives this than a fabricated screen that doesn't reflect any real design decision.

## Step 4: Set up the output folder

Ask the user where this documentation should live, unless they've already told you (e.g. "save it under docs/prototypes") — don't guess a location silently, since a dated folder is the kind of thing that's annoying to find later if it lands somewhere unexpected.

Once you have a destination, create:

```
<destination>/YYYY-MM-DD-<short_feature_name>/
├── user-flow.md
├── mockups.md
└── screenshots/
```

- **Date** is today's date, `YYYY-MM-DD`.
- **short_feature_name** is a 2–4 word snake_case slug for what the prototype does (e.g. `accounts_management`, `checkout_flow`), drawn from the app's own name, title, or main heading — not from generic words like "app" or "prototype". If nothing in the prototype suggests an obvious name, ask rather than guess something that might not match how the user thinks about this feature.

## Step 5: Give every screen a stable ID and capture its screenshot(s)

Assign each main interface a short, stable ID (Screen 01, Screen 02, ...) before writing either file — both files reference the same IDs, so decide them once, up front, rather than inventing labels independently in each one.

For each screen, get a real screenshot into `screenshots/`, named `NN-slug.png` (e.g. `01-accounts.png`, `02-add-account.png`). If a screen has more than one meaningfully different state (default vs. validation error, empty vs. populated, disabled vs. enabled), capture each state as its own file with a state suffix — `03-transfer-money.png` and `03-transfer-money-error.png` — the same way Step 3 asked you to find those states in the first place. Don't screenshot every trivial variant (e.g. a button's hover color); capture states that change what the screen *communicates*.

- **Live web app:** use the `chrome-devtools` screenshot tool at the viewport size you fixed in Step 1, once per screen/state, right at the moment that state is showing (e.g. after submitting invalid input, before it's dismissed).
- **Claude Design project:** same as a live web app — capture through `chrome-devtools` against the `render_preview` `serve_url`, once per screen/state.
- **Shared images:** copy the user's original image files into `screenshots/`, renamed to the `NN-slug[-state].png` convention. Copy the original bytes — don't re-export, recompress, or redraw them.
- **Local prototype source with no live render:** don't create a screenshot file for these screens — there's nothing real to put there. Leave the slot empty and say so explicitly in mockups.md (Step 6) instead of substituting a hand-built stand-in.

## Step 6: Write mockups.md

One section per screen, in ID order:

```markdown
## Screen 0N: <Screen name>

*Used in: [Flow 0N](user-flow.md#flow-0n), step(s) ...*

![<Screen name>](screenshots/0N-slug.png)

**Functional requirements**
- ...

**States**
- ...
```

If Step 1 determined a screen has no real screenshot (source-only analysis), replace the `![...](screenshots/...)` line with a plain note instead — `*No screenshot available — analyzed from source only.*` — never point that line at a file that doesn't exist or a fabricated substitute.

Ground every requirement in what Step 1 actually showed. Tag anything you didn't directly observe as *(inferred)* — e.g. a loading state that must exist logically but never appeared during your walkthrough — so the reader can tell confirmed behavior from your best guess. For a source-only screen, ground requirements in what the code actually implements — state fields, conditional-render blocks, handler and validation logic — and still mark anything beyond that (e.g. behavior implied by a name but not actually implemented) as *(inferred)*. If a screen has multiple state screenshots, embed each with a one-line caption identifying which state it is, rather than only showing the default and describing the rest in prose.

Heading text becomes the link anchor other files use to reference this screen, following the standard slug rule: lowercase, spaces become hyphens, punctuation other than hyphens/underscores is dropped. `## Screen 01: Accounts` → `#screen-01-accounts`. Keep headings in exactly this `Screen 0N: Name` shape so the anchor is predictable when you write the links in Step 7.

## Step 7: Write user-flow.md

One flowchart per major flow (or one combined diagram if the flows share a hub screen and stay legible together), each as a fenced ` ```mermaid ` block, plus a numbered step-by-step narrative:

- **Diagram**: happy path as the main line, edge-case branches visibly distinguished with their own `classDef` (fill/stroke/text color all set, not just line style). Set an explicit `%%{init: {"theme": "base", "themeVariables": {...}}}%%` block defining `primaryTextColor`, `lineColor`, `textColor`, and `edgeLabelBackground` — markdown viewers (GitHub, editors, this CLI) render in both light and dark themes, and mermaid's default theme can land on illegible text/background pairings depending on which one is active. Pick your own colors for every text/background pair rather than trusting the default.
- **Narrative**: for each step, what the user sees, what action moves them to the next step, and — at each branch point — the condition that causes the branch and how the UI responds. Cover edge cases with the same level of detail as the happy path; hand-waving the error states defeats the purpose. Link every screen a step's prose names back to its `mockups.md` anchor, written as `[Accounts screen (Screen 01)](mockups.md#screen-01-accounts)` — include the screen number in the visible text itself, not just the link target, so a reader skimming the narrative knows which screen they'd land on without clicking through. This includes the shared starting screen: if every flow begins "from the Accounts screen...", link it every time it's named, the same as any dialog a step opens.
- **Open questions**: a short section at the end listing every gap Step 3 turned up, rather than burying them inline as if they were resolved behavior.

Because both files live in the same folder, links between them are plain relative paths (`mockups.md#screen-01-accounts`, `user-flow.md#flow-01-...`) — no publishing step or URL to wait on, so write the cross-links in whichever order is convenient and double check them once both files exist.

## Step 8: Hand off

Tell the user where the folder is, what each file covers, and point specifically at the open questions/gaps section so they know what's fully documented versus what still needs a design decision.

Versions

The database has no other skills named decompose-prototype.

Database snapshot: 13.11.2026 · package version b86e424da041 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100prototype
    Build a throwaway prototype to answer a design question via UI variations or a state walkthrough. Use for /prototype, the plan-canvas design flow or brainstorm.
  • 82prototype
    Build a throwaway UI prototype for the user to react to before any real code. Read this skill when the user asks for a mockup or a prototype of a UI. Use it when a design decision depends on look, feel, or flow that text cannot settle.
  • 100ai-prototype
    Build a single-file, clickable HTML prototype of a UI screen or flow, following the design directions given in the request. Use when the user asks to prototype, mock up, or sketch a UI (e.g. "/ai-prototype order list, dense, neutral palette", "mock up the settings page").
  • 90wire-prototype
    Document a prototype or user flow — screens, states, transitions, and annotations. Use when asked to "document this prototype", "map the screens and states", or "annotate this flow".
  • 90polished-web-prototype
    Use when /polished-web-prototype runs or a user builds an artifact from a mockup, design plan, or brief. Not for variant galleries: use design-variants. Not for live audits: use web-design-review.
  • 100design-share
    Publish a runnable prototype and return a shareable link. Prepares the prototype to run, starts/serves it (or deploys), and hands back a URL plus run instructions for review. Use when the user says "share the prototype", "give me a link", "publish this", "let the team see it",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.