A prototype is throwaway code that answers one design question. The question decides its shape, and there are two:
"Does this logic feel right?" One HTML file anyone can open by double-clicking, even someone who doesn't code. Buttons push the state through cases that are hard to reason about on paper, and the full state is shown after every click. The logic itself sits in a small, separate module that can later be lifted into the real code.
"What should this look like?" Several radically different versions of a page on one route, switched with a ?variant= setting in the address and a floating bar at the bottom. Preferably on an existing page, next to the real header and data.
Does this logic feel right?
What should this look like?
One HTML file anyone can open by double-clicking
Several radically different versions of a page on one route
Buttons push the state through cases that are hard to reason about on paper
switched with a ?variant= setting in the address and a floating bar at the bottom
a small, separate module that can later be lifted into the real code
Preferably on an existing page, next to the real header and data
The question decides its shape, and there are two
When to use it
Whenever a design question is hard to settle on paper. In the Main flow it's a detour from the interview: grill-with-docs reaches a question that needs a runnable answer, so you step out, answer it with a prototype, and bring the answer back.
Say, whether the waitlist states in your FastAPI booking backend hold up when two people cancel at once, or which of three layouts suits your website's progress page.
When not to use it
The question can be settled by talking: keep going with grill-with-docs.
The answer is in someone else's docs, not in your own design: send research to read the sources.
You're building the real feature. Prototype code has no tests and no polish, and is never promoted straight to production.
What it needs to start
One clear question. The agent writes it down first, at the top of the prototype, because a prototype that answers the wrong question is pure waste. If the question is ambiguous and you're away, it picks the shape that matches the surrounding code (a backend module means logic, a page means UI) and says so at the top.
It must be trivial to start: one command, or one file to open. State lives in memory. If the question really is about the database, it uses a scratch database clearly named for wiping.
What it creates
An answer: the verdict, and the question it settled, recorded in the Issue or a commit.
The decision, folded into the real code. For a logic prototype, the checked logic module moves in as it is.
The prototype itself, kept on a throwaway branch out of main, with a pointer to that branch on the Issue for the real work. It's kept as a primary source: the original thing, not a summary of it. Main keeps only the decision.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's page for the Skill (updated 2026-08-24) names the problem. Some questions can't be settled by talking: "a state machine whose edge cases you can't hold in your head, a screen you can't picture until you see three versions side by side." Grilling sessions grow long on them. "The agent rephrases, you guess, and the scope grows." His way out: "Stop grilling, build the throwaway version, look at it, then answer in one line."
He files it under Shaping on his site, and calls it a "reach-for-it-anytime standalone": you settle one design question, then go back to your work. You can also arrive without choosing to. wayfinder files prototype decision Tickets on its map, and you work each one with this Skill.
How it works underneath
The idea is much older than Matt's Skill. In a 2003 interview with Andy Hunt and Dave Thomas, the authors of The Pragmatic Programmer, Hunt put it in five words: "Prototypes are for your learning." A prototype, Thomas says, is for one specific aspect: an interface, an algorithm or a performance problem. And he is blunt about its fate: "Prototypes are designed to be thrown away." He compares one to a town in a western movie: "It's all facade. There's nothing behind it."
From snapshot/skills/prototype/SKILL.md, line 14: “"Does this logic / state model feel right?" → LOGIC.md. Build a single shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.”
From snapshot/skills/prototype/SKILL.md, line 15: “"What should this look like?" → UI.md. Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.”
Their book describes two techniques: prototypes and tracer bullets. A tracer bullet is a skeleton application: one thin line of execution goes end to end. In Thomas's telling, the prototype is thrown away. In Hunt's, the tracer bullet is grown, one feature at a time. Matt uses both words. to-tickets splits a Spec into "tracer-bullet tickets", while main keeps only a prototype's validated decision.
A prototype
A tracer bullet
one specific aspect: an interface, an algorithm or a performance problem
one thin line of execution goes end to end
In Thomas's telling, the prototype is thrown away.
the tracer bullet is grown, one feature at a time
Their book describes two techniques: prototypes and tracer bullets.
Matt bends the old rule. "Throwaway is a constraint on how the code is written, not a promise to destroy it." So the test for whether you are still prototyping is about how you write, not where the code ends up: "The moment you find yourself hardening one (adding a test, wiring the real database, generalising for a case you might want later), you have stopped prototyping."
A real example
The Skill's own history shows why it keeps the prototype now.
3 July 2026. A product person posted in the Skills repo's Discussions. They had iterated a prototype until it felt right, then went through a Spec and Tickets. The result "kind of ignored the prototype", rebuilt from prose instead. They called the Spec and the Tickets "two steps that are lossy".
9 to 10 July 2026. Matt's PR #488 changed the rule. "Instead of being deleted once it's answered its question, the prototype is kept as runnable evidence on a throwaway branch (prototype/<name>)", never merged. It merged on 10 July.
His reason, on the Skill's page: "A prose summary of a prototype loses the thing that made it convincing."
5 August 2026. Version 1.2 changed the logic branch too. It now produces one HTML file "instead of a terminal app". A terminal app "can only be driven by someone with the repo cloned and a runtime installed", which rules out the designer, the PM and the domain expert.
The sources don't say the post caused the PR. They only show the same problem from two sides, a week apart.
Where it goes wrong
An agent suggests it when you should build. Matt calls this "a known naming problem". An agent that doesn't know the Flow reads the word as "the obvious next step" once Tickets exist. His rule: "If you already know what to build, the next step is /implement, per ticket." See implement.
Prototyping the whole app. "A full-app prototype has no natural stopping point, so it drifts into being the production app". Code written with no tests and no error handling ends up in front of users.
A question that's too big. "If you're still building it a day later, the question was too big; split it." Matt admits it can burn tokens, if you prototype questions you could have answered by talking.
Branches that pile up. Issue #1020 (3 September 2026) points out a cost of keeping prototypes: "A referenced branch can never be deleted without breaking those links". It suggests keeping them on main instead. It was labelled ready-for-human from Matt's account on 7 October 2026, and it was still open on 30 October 2026. The current SKILL.md still says a throwaway branch, out of main, so that rule stands.
/prototype stops working. Issue #1019 (3 September 2026) reports that Claude Code 2.1.221 bundles a hidden, not-yet-enabled built-in "prototype" skill. Typing /prototype fails with "unknown skill", while /mattpocock-skills:prototype still works. It was closed as not planned on 7 October 2026.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), settle one logic question about bookings before you write the booking endpoint.
Open an Issue in the practice project's repo: "Does the waitlist model hold up when a booked student cancels an hour before class?"
In a fresh session, run /prototype with that question. If you installed Matt's Claude Code plugin and it answers "unknown skill", use /mattpocock-skills:prototype.
Check the result against the Skill: one HTML file in api/, next to where the bookings code will go, named so anyone can see it's a prototype, with the question written at the top.
Open it by double-clicking and run every walkthrough tab. Write down each "wait, that shouldn't be possible".
Record the verdict and the question on the Issue. Commit the file to a prototype/waitlist branch, never merge it, and link that branch from the Issue.
The checked logic is JavaScript and your API is Python, so treat it as the reference your Python version must match.
Going deeper's Check questions are asked in Next up.
“Put the actual logic (the bit that's answering the question) in a single <script> block written as a small, pure module that could be lifted out and dropped into the real codebase later.”
From snapshot/skills/ask-matt/SKILL.md, lines 20–23: “If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by /handoff in both directions”
From snapshot/skills/prototype/SKILL.md, line 17: “default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.”
From snapshot/skills/prototype/SKILL.md, line 23: “If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.”
From snapshot/skills/prototype/SKILL.md, line 26: “Fold any validated decision into the real code, then capture the prototype itself as a primary source: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too (the verdict and the question it settled) in the issue or a commit. The main branch keeps only the validated decision.”
From snapshot/web/aihero.dev/skills-prototype.md, line 93: “Reach for it the moment you hit a question you can't settle by talking: a state machine whose edge cases you can't hold in your head, a screen you can't picture until you see three versions side by side.”
From snapshot/web/aihero.dev/skills-prototype.md, line 93: “sessions grow long on these questions. The agent rephrases, you guess, and the scope grows. Stop grilling, build the throwaway version, look at it, then answer in one line.”
From snapshot/web/aihero.dev/skills-prototype.md, line 104: “The moment you find yourself hardening one (adding a test, wiring the real database, generalising for a case you might want later), you have stopped prototyping.”
From snapshot/web/github.com/mattpocock-skills-pull-488.md, line 33: “Instead of being deleted once it's answered its question, the prototype is kept as runnable evidence on a throwaway branch (prototype/<name>) linked from the relevant issue, never merged.”
From snapshot/web/aihero.dev/skills-prototype.md, line 120: “A terminal app can only be driven by someone with the repo cloned and a runtime installed, which rules out the people whose opinion the prototype needs: the designer, the PM, the domain expert”
From snapshot/web/aihero.dev/skills-prototype.md, line 123: “This is a known naming problem. An agent that does not know the flow reads prototype, a generic and appealing word, as "the obvious next step" once tickets exist.”
From snapshot/web/aihero.dev/skills-prototype.md, line 126: “A full-app prototype has no natural stopping point, so it drifts into being the production app: the cleanup pass never happens, and code written under prototype rules (no tests, no error handling) ends up in front of users.”
From snapshot/skills/prototype/SKILL.md, line 21: “Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious, but name it so a casual reader can see it's a prototype, not production.”