You don't need to memorize every skill, so just ask.
Flow is a path through the skills. Most paths follow one main flow , and two on-ramps merge into it. Everything else is either standalone or a vocabulary layer running underneath.
Main flow: idea -> ship
This is the route for most work: you have an idea and want to build it.
-
/grill-with-docs- refine the idea through interview. When working in working directory , start here: it is stateful and saves what it learns inGLOSSARY.mdand ADRs. (No working directory? Use/grill-me, see "Standalone skills". Both run the same/grillingprimitive;grill-with-docsis the version that leaves a documentation trail, and as long as there is a repo to record in, it is the better of the two.) -
Branch - can everything be resolved in the conversation? If a question needs a runnable answer (state, business logic, or UI that must be seen with your own eyes), take a detour through a prototype and use
/handoffto bridge in both directions (the prototype lives in its own directory, which is exactly what/handoffis for, see "Phase boundaries"):/handoffexport, then open a fresh session based on that file;/prototypeanswer the question with throwaway code;/handoffbring what was learned back and reference it in the original idea thread.
-
Branch - is this a multi-session build?
- Yes ->
/to-spec(turn the thread into a spec), then use/to-ticketsto split it into tracer-bullet tickets, each ticket declaring blocking edges. Then choose one of the following two ways to advance these tickets:- Run
/implementticket by ticket, and use/clearbetween tickets to clear context. The local tracker has one file per ticket under.scratch/<feature>/issues/, handled manually in blockers-first order; the real tracker uses native blocking links, so every ticket whose blockers are complete can be claimed. Each ticket is self-contained, so the context of the last ticket can be discarded. - Use
/implement-specto implement the entire spec in one run. It reads the tickets as task graph, runs implementer subagents in parallel on ready frontier , and lands all results on a single integration branch . Choose it when you would rather orchestrate this build than drive the tickets one by one yourself.
- Run
- No -> run directly in the current context window
/implement。
Either way, the code is built by driving
/tdd(one red-green slice at a time), and wrapped up with/code-review, that is, a Standards + Spec two-axis review of the diff./implementruns both of these on each ticket;/implement-speceach implementer drives/tddseparately, which then runs/code-reviewonce against the integration branch. Use/tddon its own when you just want to build one specific behavior test-first without a full spec; use/code-review。on its own when you want to review a branch or PR at a fixed point. When the work is submitted as a pull request,
/prResponsible for shaping the PR body: show the minimal visual for this change, the before/after evidence that proves it works, plus a judgment call on whether it's a one-way door or a two-way door. It is model-invoked, so the agent reaches for it every time it writes a PR. - Yes ->
-
/retroClose the loop. After a build, especially one that took a detour, it looks back over the whole session and suggests changes to the agent's environment, rather than the code: navigation pointers, automated checks,/code-reviewenforced coding standards, steering files, tooling. Mechanical errors become deterministic checks; judgement calls become coding standards. The next build thus starts from a better environment.
Context hygiene
Steps 1 through /to-tickets must stay in the same uninterrupted context window ; don't compact or clear, so that grilling, spec and tickets build on the same set of thinking. After that, every /implement starts from a fresh session, working only from the corresponding ticket. Before clearing, run /retroin the session being looked back on; after clearing, instead have it read that session's log.
The limit comes from smart zone: within that window (about 150k tokens for the latest models) the model can still maintain sharp reasoning. If the session approaches this range before /to-tickets , don't force it in a degraded state; at the nearest phase boundary use /compact, then continue (see "Phase boundaries").
On-ramp
The starting point generates work, then merges into the main flow.
-
Bugs and requests pile up ->
/triage. It advances issues through triage roles and produces agent-ready issues, which are then picked up by/implement.Triage is only for issues you didn't create : bug reports, incoming feature requests, and anything raw that comes in.
/to-ticketstickets produced are already agent-ready, so don't triage them again. -
Something's broken ->
/diagnosing-bugs. For hard problems: bugs that aren't visible at first glance, intermittent flakes, regressions sandwiched between two known-good states. It refuses to speculate until it has tight feedback loop , that is, a command that can already turn red on this bug; then fix it with a regression test. Once the fix is in place, run/retroin the same session and ask what could have prevented this bug; if the real finding is that there's no good seam to lock the bug down, that's/improve-codebase-architecture's job. -
Huge and vague efforts: greenfield projects or giant feature builds that one session can't hold ->
/wayfinder, this is the most cognitively demanding flow here. When the path from the current position to the destination isn't yet visible, it draws on the issue tracker decision tickets the shared map, resolves them one by one, and produces decisions, not deliverables, until the fog is pushed back and the path is clear./grill-with-docsis for ideas that fit in one session, wayfinder is for ideas that don't; it's slower and denser, so it should only be kept for efforts that genuinely are that, never for a well-scoped feature.Once the map is clear,it hands off rather than builds: first enter
/to-spec, condense the mutually linked decisions in the map into a buildable plan, then use/to-ticketsand as usual/implement. Letting map loop directly into/implementwill skip this convergence and lose the interlinked details; only enter directly once effort later finds it is indeed very small, then go directly into/implement。
Codebase Health
This is not feature work, but maintenance.
/improve-codebase-architecture- Run it when you have time, to keep the codebase suitable for agents to operate on. It will expose deepening opportunities; choosing one of them generates an idea that can be brought into the main flow's/grill-with-docs. It is responsible for finding candidates;/codebase-design(see below) is the workbench you use when designing the chosen candidate.
Underlying Vocabulary
Two model-invoked references run underneath other skills, each being the single source of truth for its own vocabulary. The point iswordsrather than process, use them directly; you can also let the skills above pull them up automatically.
/domain-modeling- Polish the project's domain language: challenge vague terms, resolve overloaded words (for example, one "account" carrying three things), and record hard-to-reverse decisions as ADRs. It is/grill-with-docsthe active discipline used to keep theGLOSSARY.mdglossary clean./codebase-design- deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality), used to design a module's shape: put a large amount of behavior behind a small interface on a clean seam./tddand/improve-codebase-architectureboth use this language.
Phase Boundaries
phase is a stretch of work within a session: grilling, implementation, QA. At the boundary between them you have five options, and across this whole map, which one to choose is the most ambiguous decision:
- Continue - Stay put. It costs nothing and loses nothing.
/clear- Clear the context window, when what is here no longer matters for what comes next./handoff- Write a portable markdown file. The scope is very narrow: only for new harness、new directory、colleague, or for forking a side task midway through the phase . What it buys is portability.- Subagent - Send a tightly-scoped task to its own context window and get back a report.
/compact- Compress this context and seed a fresh session with the summary. It is default, located at the bottom of the tree, rather than the first thing within reach.
For the ordered tree, read PHASE-BOUNDARIES.md: the five questions, the reasoning behind each branch, and why primary-source cost makes Continue the first option to rule out.At boundary, make the decision; midway through a phase, either continue or split the remaining work into subagents.
Standalone Skills
Entirely outside the main flow.
/grill-me- The same continuous interview as/grill-with-docs, but stateless: nothing is saved locally, and noGLOSSARY.mdis built. Use it when you are not in the working directory : polishing a plan, a design, a piece of writing, anything not carried by a repo. If you are in the working directory, use/grill-with-docsinstead: it runs the same interview and leaves a documentation trail, so it is strictly the better choice./grilling- The interview primitive itself: rounds, frontier, facts are the agent's job, decisions are yours./grill-meand/grill-with-docsare the two named entry points,/triage、/wayfinderand/improve-codebase-architectureboth run it internally. Use it directly only when you want an interview without any wrapper./prototype- a small throwaway program used to answer one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer gets folded into the real code, while the prototype itself is kept as primary source on aprototype/<name>branch outside main, pointed to by an implementation issue. It is a detour from step 2 of the main flow, but any design question that is hard to resolve on paper can use it directly./research- delegate the reading work to background agent: it investigates the question against primary sources , then leaves a Markdown file with citations in the repo. You can keep working while it reads. The artifact should be brought into/grill-with-docs's main flow; research provides material for thought, but does not replace thought./to-questionnaire- when what is blocking you is not in your head or in the codebase, but in someone else's head, this skill writes a questionnaire for them to fill out. It is the reverse of/grill-me: it does not interview you about the subject, but interviews you about send(who to send it to, what you need back), and aims the questions at the gap. What comes back is material for/grill-with-docsor/to-spec./wizard- for steps that only human can complete: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes.envand GitHub secrets, so the process no longer requires you to re-explain it to the agent every time. It is model-invoked, so the agent reaches for it as soon as it hits a wall only you can get past. If the agent can do it itself, it should do it itself; this skill is for situations where the human is truly in the loop./wait-what- a correction for messages that did not land. Use it mid-conversation, inside any other skill, and the agent will restate what it just said using the context you were missing, in plain language, withGLOSSARY.mdvocabulary. It works after the fact;/grill-with-docsis the upfront solution, because shared language agreed on early is the root-level way to prevent jargon from appearing./teach- use the current directory as a stateful workspace to learn a concept across multiple sessions./writing-for-agents- a reference for writing docs that agents consume: skills, AGENTS.md, pointed-to docs.
Prerequisites
/setup-matt-pocock-skills - run before the first engineering flow to configure the issue tracker, triage labels, and docs layout that other skills depend on. Custom issue trackers are also fine.