Ship with skills, not vibes

It writes throwaway code that answers one question. The question comes first and shapes everything after it; a prototype answering the wrong question is pure waste however good it looks. "Throwaway" constrains how it is written, not whether it must be destroyed. No tests, no error handling beyond making it run, no abstraction, no persistence.

The two branches produce very different things. "Does this logic or state model feel right?" gets you a single shareable HTML file — with a state panel, a free-play button and tabbed walkthroughs, everything labelled in domain language, ready to hand to a designer or a domain expert to try for themselves. The logic behind it is a clean pure module that never touches the DOM, so once validated it lifts straight into production code. "What should this look like?" gets you several radically different UI variants on the same route, switched with a floating bar. The variants have to disagree on structure rather than colour — three lightly tweaked card grids are wallpaper, not a prototype.

The moment you catch yourself hardening it, you have stopped prototyping — adding tests, wiring a real database, generalising for something you might need later.

What to do with the output. The answer — the verdict and the question it settled — goes somewhere durable: a commit message, an ADR, the implementation issue. The prototype itself is not deleted and does not go to main; commit it to prototype/<name> branch, never merged, with a pointer left on the implementation issue.

Pitfalls. Agents suggest prototyping when you should be implementing — a naming problem: to an agent unfamiliar with the flow it reads like the obvious next step after a ticket exists. And do not prototype a whole app: there is no natural stopping point, momentum turns it into the product, and code with no tests and no error handling meets users that way.

It works only from primary sources — official documentation, source code, specifications, first-party APIs — tracing every claim back to whichever one owns the answer. It does not answer you in the conversation; the output is a file, with a link on every claim. The decisive move: the reading runs in a background agent.

Research is legwork you delegated, not thinking you outsourced.

Pitfall. It spawns a second copy of itself (issue 530): the skill tells the caller to start a background agent without constraining the agent type, so what starts is a general-purpose agent holding the same tools and instructions, which starts another. Somebody measured a single research task burning roughly 450k tokens across three overlapping executions, the duplicate finishing half an hour later entirely out of sight. Check the background task list after invoking it and stop the duplicates.

Three more. The inverse failure: if your global instructions forbid further delegation, the background agent politely declines and the skill quietly does nothing. "High-trust source" is the model's own judgement with no allowlist, so your real mitigation is following two or three citations at random — landing on a summary of the thing rather than the thing itself means the run failed. There is no stopping criterion, so scope is your responsibility: one API, one behaviour, one version claim comes back far better than "research X".

A research file is not an ADR. ADRs stay; research files get archived or deleted once used. A stale research file is worse than none — it poisons every later read of the repo.

Six phases: build a repro, minimise it, rank hypotheses, instrument, fix with a regression test, clean up.

It will not let the agent form a theory before a tight feedback loop exists. A named command, already run once, red on this bug, and green once fixed. A coding agent handed a bug report defaults to reading the code and guessing; this skill blocks that.No command that can go red means no phase 2.That gate is the entire value of the skill.

Having a loop is not the goal; a tight one is. Fast — seconds. Deterministic — the same verdict every time. Sharp — asserting your exact symptom, not "it did not crash". And runnable unattended. A thirty-second flaky loop is barely better than none. For an intermittent bug the goal is not a clean repro but a higher reproduction rate: loop the trigger, parallelise, add load, inject sleeps.

It refuses to treat a conflict as a text problem. Before touching a hunk it traces both sides back to primary sources — the commit message, the PR, the originating issue — so it is choosing between two intentions rather than between two blocks of text, and it keeps both wherever they are compatible. Where they genuinely are not, it picks the side matching this merge's stated goal and states the trade-off. It never invents new behaviour to paper over a conflict, and it does not abort: the merge is always carried to a finished commit.

It also finds the repo's own automated checks and runs them before committing — because a merge is the easiest place in git to produce something that satisfies both branches and passes neither one's tests.

Extra practical knowledge. Do not partition files between parallel tasks to avoid conflicts — it costs more than it saves. The one discipline worth keeping is large refactors first. When working in parallel worktrees, the merge back is best done by the session that wrote the change, because only that session knows the intent. Batching everyone's conflicts onto the last agent throws away exactly what this skill works to reconstruct.

It scans the codebase for deepening opportunities — places where a shallow module, whose interface is nearly as complex as what it hides, could become a deep one — writes them up as an HTML report, and then grills whichever candidate you pick.

It never changes code. A whole run produces one HTML file and one conversation. The refactor itself happens later, in another session, through the normal build flow. That is what makes it a survey rather than a refactoring tool, and why it is worth running against a codebase you are not ready to touch yet.

Two filters. The deletion test: imagine removing this module — does complexity concentrate behind a smaller interface, or disperse across the callers? Only concentrating cases get a card. Unless you name a region it also reads recent commit history first and biases the scan towards paths that are changing — a deepening in code nobody touches is a refactor you will never cash in.

Three strength labels. Strong — the deletion test passes cleanly and the friction is real; take it seriously. Worth exploring — it makes sense, but the payoff depends on where the code goes next. Speculative — listed for completeness, and mostly safe to ignore.

Only for issues you did not create. Raw bug reports, feature requests from outside, an external PR that appeared overnight. to-tickets produces tickets that are agent-ready by construction, so running triage on them is wasted effort at best. It recommends and waits: it gives you its category and status judgement with reasons, and applies nothing until you say so.

Everything triaged ends up with exactly one category role and one status role. Two categories: bug and enhancement. Five statuses: needs-triage (you need to assess it), needs-info (waiting on the reporter; back to needs-triage once they reply), ready-for-agent (fully specified, with an agent brief), ready-for-human (the same brief plus why it cannot be delegated), wontfix (closed, with the reason recorded).

wontfix comes in three kinds, and the difference matters because only one of them gets written into the knowledge base. Already implemented: leave a comment pointing at where it lives, and do not file it in out-of-scope — that is a built feature, not a rejected one, and filing it there pollutes the deduplication check. A rejected bug: explain politely and close. A rejected enhancement: write a file in the out-of-scope directory and link to it from the closing comment. That directory holds one markdown file per rejected concept rather than one per issue — and triage reads the whole directory before assessing anything, matching by concept rather than keyword.

Verify before writing the brief. For a bug, follow the reporter's steps; for a PR, check it out and run the relevant tests. Then report one of three outcomes: confirmed with a code path, could not reproduce, or not enough detail to try — which is itself the strongest needs-info signal there is. All of it exists to make the agent brief good, and that brief is written to be durable rather than precise: types, signatures and behavioural contracts, and never file paths or line numbers, because an issue may sit for weeks while the code beneath it moves.

Pitfalls. Labels are not created for you. Five statuses are not enough is the most-cited gap — blocked, deferred and implemented have all been asked for and none shipped. And do not turn it loose on a whole backlog at once — the "show me what needs attention" pass is a cheap list meant for picking from, and across twenty issues an agent quietly treats it as the evidence base — while it returns issue bodies and not comments.

It takes on work too large for one agent session — where you can name the destination but cannot yet see the route — and draws it as a shared map on the tracker, made of decision tickets, then resolves them one at a time until the route is clear.

It plans; it does not execute. Each ticket holds a question that produces a decision when resolved, rather than a slice of build work. The map is finished when nothing remains to be decided before somebody builds the thing. This is the rule agents break most break.

The boundary against grill-with-docs is session count, not project size. Fits in one conversation: use grilling, which is cheaper and better. Does not fit: wayfinder. Reaching forwayfinder on a well-scoped feature is a common mistake.

Four things on a map. Destination — what the end looks like, named before any ticket exists. Decisions so far — one line per closed ticket, each linking to where the detail actually lives. Not yet specified, the fog of war — decisions you can see coming but cannot yet state precisely. The test is whether you can state the question precisely right now, not whether you can answer it. Out of scope — work judged outside the destination, closed and never graduated. The map is an index, not storage; a decision lives only in its own ticket.

The frontier is the set of tickets that are open, unblocked and unclaimed. A session claims one by assigning it to itself before doing any work, so the assignee is the claim. Tickets are referred to by name throughout, never a bare number — a wall of issue numbers is unreadable in prose.

It compresses the current conversation into a handoff document — a markdown file written to the OS temp directory rather than the workspace, so a fresh agent can read it and pick up.

What it buys is portability, not compression. That makes it much narrower than it sounds: you only need the file when work has to move. Four triggers: switching harness, moving to another directory or repo, handing work to a colleague, and forking off a side thread found mid-phase.

The most-skipped use is the fork. You stay in your own session and hand a copy of the accumulated context to a second agent working in parallel. The prototype branch works exactly this way: you are deep in a design conversation, hit something only running code can settle, and do not want to spend a hard-won thread on looking it up. Hand off to a prototype session, get the answer, bring it back, and cite it in the original thread.Two crossings, one live conversation, nothing re-explained.

What travels: the live thread — what is in flight, why, and what is next — plus a suggested set of skills. Secrets are masked before writing. It deliberately carries none of what is already written down: spec, plan, ADR, issue, commit, diff are referenced by path or URL, never copied.

Pitfalls. The file lives in a temp directory with a long path that differs per OS — ask for the path and write it down before moving on. Some environments clear temp between sessions, so if the next one will not start soon, copy it somewhere durable. Hand it to the next agent by pointing at the path. Do not paste a summary into a shell command — one containing special characters gets mangled, and the typical failure is silent truncation; "It captures the what and not the why" is fair criticism, so pass what the next session is for as a parameter, and watch for unverified beliefs written down as facts.

It turns a decision you cannot make alone into a questionnaire for whoever holds the piece you are missing.

It grills the sending, not the subject. Interviewing you about the subject would be pointless — not knowing the subject is why you are writing to somebody else. So it asks only the two things you can always answer: who it is for — their role, expertise and relation to you, which fixes the register and how much context the document has to carry — and what you need back — the specific decision or fact you cannot settle alone, which becomes the checklist the result is measured against. Everything after that is drafting.

The shape of the document: one line of purpose, a short paragraph of context for somebody who has never been inside your head, questions most important first and grouped by topic, one idea per question and never compound, and explicit permission to answer "I do not know" — flagged uncertainty is useful, a confident guess that reads as fact is not. It ends with a catch-all.

It deliberately does not branch and does not take multiple recipients. Three people holding three pieces means running it three times. The commonest use is a grilling that has stalled: run it in the same conversation — it has no ingest t stage, and it works after a grilling purely because that session is already in the context.

The agent re-pitches what it just said: supplying the context you were missing, in plain words, using the vocabulary from your project's CONTEXT.md.

This skill is three lines long, and that is the design rather than an unfinished draft. A skill against verbosity fails by growing: four hundred lines telling a model to be concise still produces verbosity, because what the model reads is the volume, not the plea.

The name is the mechanism. The leading word is wait. "Be more concise" is an instruction about the agent's output, and a model complies by cutting words — leaving you more lost. Wait is about your state: it says understanding failed here. An agent told to be shorter writes a telegram; an agent told "wait, you lost me" will go back and re-pitch. Every popular alternative names the output, and the model overcorrects into a register that is shorter without being clearer. Naming the listener asks for both halves: fewer words and the premise you were missing.

It also says re-pitch that rather than "the last message" — what lost you is usually bigger than one paragraph, and how far back to go is the agent's call. The real cure is establishing shared language in advance; wait-what repairs the one that already went wrong.

It turns the directory you run it in into a standing teaching workspace, and teaches a subject across multiple sessions through a series of short, self-styled HTML lessons.

It does not teach from what the model already knows. Parametric knowledge is treated as untrustworthy: before teaching it finds high-trust sources, records them, and cites them in every lesson. It is stateful — mission, resources, lessons and learning records all live in the directory as files:

The central idea is storage strength — long-term retention — rather than fluency, the sense of recall in the moment that feels like mastery while reading and is gone a week later. It builds the first with desirable difficulty. Knowledge comes first, and difficulty is the enemy there — it consumes the working memory you need to understand. Skill is drilled afterwards through tight feedback loops, where difficulty becomes the tool.Lessons are rarely reread; reference documents are — so a lesson's compressed essence belongs in the reference directory rather than buried in the lesson that introduced it.

Pitfalls. Files can land in the wrong place (issue 377 — somebody's lessons were written into the global skills directory), so name the directory explicitly at the start. The correct quiz answer is always the first option (confirmed across models, unfixed, and one contributor measured 33 out of 33 across nine lessons). There is no assessment step, so state your existing knowledge and your gaps in the first message. There is no spaced-repetition schedule — ask for revision yourself.

Not only for code — the non-code uses outnumber the code ones in the record. Within code, the strongest use is not learning a language from scratch but finding your bearings in an unfamiliar codebase or a new team's stack. The author suggested a neat combination: when a grilling reaches something you do not understand, do not stop the grilling to learn it — handoff to a teaching workspace, learn it there, and come back.

It generates an interactive bash script that walks a human through a manual procedure step by step — wiring up a third-party service, running a one-off migration, moving a project from state A to state B.

The agent writes the script and never runs it. You run it on your own machine. So a wizard is not instructions you follow — it is a program that drives the process and holds the state, and your part is clicking, pasting and pressing Enter.Stage is one focused task on one screen, and the script clears the terminal between stages.

Scoping comes before the script. It reads your repo rather than asking cold — environment files, compose files, framework config, and every secret and variable reference in the CI configuration. Each of those is a value the wizard must produce. Then it gives you an ordered stage list to confirm, and only afterwards maps each stage to the exact path a human walks. Where it does not know what the current UI looks like, it asks you or checks the documentation rather than inventing the clicks.

The template has already solved the UX: progress, confirmation gates, opening URLs across platforms, hidden input for secrets, idempotent writes to the environment file, writing CI secrets, and a closing summary of what it had to skip. The fixed library half is identical in every wizard and never hand-edited — consistency is the point. The agent writing a wizard never runs it end to end, using static validation instead. The first run is yours, and that run is the test.

Pitfalls. There is no going back a step — a typo at stage three means interrupting and rerunning, which is cheap because values already written to the environment file come back as defaults. Arrow keys are broken in the prompts (issue 741); backspace works. It does not check the state of third-party services. API key never enters the model's context — but a key you pasted into the chat during scoping is in the context like any other pasted text.

It builds and sharpens the project's ubiquitous language while you design — challenging words that conflict with the glossary, forcing a precise term when you reach for a vague one, and stress-testing a relationship with concrete scenarios until the boundaries are exact.

It is an active discipline, not a passive one. Reading CONTEXT.md to borrow vocabulary is a one-line habit any skill can have; this one is for when you are changing the model. Which is why it interrupts you: it writes into CONTEXT.md — mid-conversation, at the moment a term is settled — because the batched version is a session's summary, and the live version is that session's actual output.

Two artefacts, two standards. CONTEXT.md holds terms — what a thing is, in a sentence or two. The threshold for writing is a vague word becoming a formal term; the timing is immediate; and it never holds implementation detail, spec, scratch notes or general programming concepts. An ADR holds one decision in one to three sentences — context, choice, reason — and the threshold is all three at once: hard to reverse, surprising without context, the result of a real trade-off. And it is offered, never assumed.

The rule to actually remember is the CONTEXT.md one, because it is the one that breaks in practice: it is a glossary and only a glossary. Left unattended, a model reads "write it into CONTEXT.md" as permission to persist every answer you gave, and the file becomes a running spec. This is the most reported problem with the skill, across several models.

The move that makes this skill worth having. When you state how something works, it checks the code and lays the contradiction out: "your code cancels the whole Order, but you just said partial cancellation is possible — which is it?" Language and code are forced to agree out loud, before either is changed. Limits: it cross-references only the code and what is already committed, and does not search your issue tracker — so a naming conflict argued out and deliberately settled months ago in a closed issue gets raised again as new.

Pitfalls. CONTEXT.md grows past 500 lines — size is the symptom, not the disease. Tell it directly to make the file concise and strip the implementation detail. Only once the file is genuinely lean and still spans two domains no reader wants in their head at once should you consider splitting it, because splitting a bloated file just gives you several bloated files. Automatic invocation is its weakest point: a grilling that finishes with CONTEXT.md untouched is this happening — name the skill explicitly. An agent-written glossary nobody reviewed is worse than none: it becomes confident-sounding folklore that later sessions treat as truth.

Skills, instruction files, specs, runtime prompts, READMEs — anything an agent reads. Different wrappers, same craft.

Its default move is deletion, not explanation. Ask an agent to write instructions for another agent and most of the words go on explaining what the model already knows — every one of those lines is a no-op: paid for in context, changing nothing. This reference is the lens for finding them, which is why it earns as much on documents you already have as on a blank file.

Two kinds of load. Context load is what permanently loaded material costs in the agent's window: a line in the instruction file, a skill description, anything present every turn whether or not it is ever triggered. Cognitive load is the cost on you: which documents exist and when to reach for which. You are the index. That is not a cost to minimise — it is the price of human control. Once those two are clear, most writing decisions become the same trade-off made in different places.

Five levers. Context pointer — a reference that sits in context, names material outside it, and encodes when to go and fetch it. How reliably an agent reaches through it is decided by the pointer's wording, not its target. Information hierarchy — the ladder from in-file steps, to in-file reference, to reference behind a pointer. Completion criteria — the defence against premature completion. Leading words — compressed concepts already in the model's pre-training, anchored twice: in the body for execution, in the pointer for triggering. Pruning — single source of truth, relevance, and the no-op test applied sentence by sentence.

The no-op test is behavioural, not aesthetic. Delete the line and ask whether the agent's behaviour changed. A sentence that fails it gets deleted whole rather than reworded. When people disagree about one, run the document to settle it rather than arguing. The tests: the document gets better as it gets shorter, and you will be surprised how little is left. Nothing is said twice — repetition is the most reliable sign a document has never been tested.

It interviews you about a loose idea until you can commit to it. You do not need a worked-out plan to start — producing that plan is what the session is for. It is stateless: no files, no workspace. What remains is the sharper version in your head. The subject need not be code and you need no repo.

Turn plan mode off. It pushes the agent to produce a plan quickly, which is the opposite of staying in the question.

What it looks like when it is working. You disagree with something — a session you never pushed back in is a session you did not need. Questions arrive in a few rounds rather than a long drip, and later rounds visibly build on what you said earlier. You end up somewhere you did not expect, because a question turned over a decision you had been making implicitly. And by the end you can defend every choice to somebody who was not in the room.

Count rounds, not questions. Forty-six questions across four rounds is an ordinary session. Two hundred means the scope is too large — and a very long session drifts into the dumb zone, where the context window is full enough that question quality drops. Once the grilling is done and you are committed, do not start a new session — that conversation's context is the value.

It recommends, then stops. No grilling, no spec, no files opened, and it will not launch the skill it just named — what you get is what to type next, and then you type it. The unit it thinks in is a flow: a path through skills rather than a single skill.

Honest limits worth knowing. It is a hand-written map, it lags the repo, and it only knows this pack's skills. It will tell you half the skills are not installed — known and unfixed: most of what it routes to is user-invoked, the harness leaves those out of the list it injects, and the agent treats that list as complete and reports them missing.They are installed.

It can also describe another skill's behaviour wrongly, answering from its own one-line summary rather than from the skill. One detailed report traced three instances in a single session, including advice to skip to-spec — that SKILL.md was never opened, and the cost was a missed seam check and tickets that underestimated the work. When it makes a load-bearing claim about another skill, have it open that SKILL.md.

Where it sits. ask-matt is a secondary source above the pack. When the router and a SKILL.md disagree, the SKILL.md is right.

The situation. A customer reports that submitting sometimes returns a 500, and you cannot reproduce it.

1. Somebody else reported it, so take the on-ramp: /triage. Can you reproduce it from their steps? If not, needs-info — or decide to chase it now.
2. Chasing it now means a fresh session: /diagnosing-bugs, and say explicitly "build me a loop that goes red first".

The rest is mechanical: minimise, with every remaining element justified as load-bearing; three to five ranked falsifiable hypotheses, which is the only human checkpoint; tagged probes; the regression test before the fix; clean up; and the hypothesis that turned out right written into the commit message.

One branch to know about. When there is no correct seam for that regression test, it should say so rather than write a shallow test that gives false comfort — "there is no seam" is itself the finding, and it goes to improve-codebase-architecture.

The situation. You have joined an eight-year-old project, or inherited a vibe-coded repo. No ADRs, no domain language, no design principles.

1. Day one. /setup-matt-pocock-skills for the tracker and document layout.
2. Day one. /grill-with-docs, asking it to build up this existing repo through CONTEXT.md. Expect a long interview — some report more than fifty questions before the file took shape — and steer it actively. It reads the code and asks you what it found, and which of the words already in the code are the right words is yours to decide.
3. Day two. /improve-codebase-architecture, opening with "do not grill me, give me the report first". An all-Speculative report means it found nothing; pick a Strong candidate.
4. Day two. One candidate at a time: let it grill that candidate, and the output is a decision rather than a diff. Then on to to-spec, to-tickets, implement.
5. Afterwards. Rerun the architecture survey every few days as maintenance.

Honest expectations. On genuinely out-of-control projects, people report it "helped a bit and was not enough"; on an eight-year-old legacy codebase somebody watched the model circle in place, while the same skill produces a clean map on a tidy repo. There is currently no skill dedicated to this case.

The situation. A new product module from nothing, with no clear route, and obviously more than one conversation can settle.

1. Make sure the five wayfinder: labels exist — gh fails outright on one that does not.
2. /wayfinder. The first act is naming the destination. It is asking for the destination of the whole map, not of this session; scope it to one bounded epic rather than "implement V1".
3. It runs one breadth-first grilling and draws the Destination, Decisions so far, the fog, and Out of scope. The test between fog and ticket is whether you can state the question precisely right now. If the opening grill finds no fog at all, it should stop and say this is too small to need a map.
4. Research tickets are launched while the map is being drawn and burn in parallel; the rest go one at a time, claimed by assigning them to yourself.
5. For each one resolved: post the resolution comment, close the ticket, leave a line on the map, and then stop. Clearing fog ahead of it graduates whatever is now stateable into new tickets.
6. Once the map is empty: /to-spec #<map_issue> — pass the map itself, not an individual decision ticket — then /to-tickets, /implement.

The three fatal pitfalls are listed under wayfinder in section 06: the agent starts writing production code, do not skip to-spec, do not run grilling tickets in parallel.

The situation. A business decision — whether to start a product line, how to price a proposal, the argument structure of an article.

1. Start a clean conversation — you do not need to be in a repo — turn plan mode off, and run /grill-me.
2. Answer round by round, numbered, in one go. Push back on questions pitched too shallow; say so when the scope is drifting; "I do not know" is a real answer.
3. A question you can only answer once you see something is ungrillable. Outside code that usually means: sketch a page, build a spreadsheet, or ask one customer.
4. When the answer is in somebody else's head, run /to-questionnaire in the same conversation, send it, and start the next round when the answers come back.
5. It is stateless: no files, no workspace. What it leaves is the sharper version in your head.