A field guide to mattpocock/skills

Stop prompting. Start a daily loop with your agent.

Matt Pocock's skills are “for real engineers, straight from his .agents directory.” Each one does a single job. This page shows the order to use them through a normal workday, with example sessions for the four situations you'll hit most.

claude plugin install mattpocock-skills@claude-plugins-official
npx skills@latest add mattpocock/skills -a cursor
Pick one install per agent, otherwise you get every skill twice. Then run /setup-matt-pocock-skills once in each repo.
The big picture

One loop, five stops

Every change goes round the same loop. You trigger the main skills yourself with a slash command. Helper skills join in automatically when the agent needs them.

1 · Align

Get grilled

The agent asks you questions one at a time until every design decision is settled. Matt does this before every change.

/grill-with-docs/grill-me
2 · Plan

Write it down

Turn the conversation into a spec, then split it into thin tracer-bullet tickets with blocking edges.

/to-spec/to-tickets/wayfinder
3 · Build

Implement

Build the tickets test-first at the seams you agreed on, and finish with a two-axis review.

/implement/implement-spec
4 · Ship

Open the PR

A PR body with a summary, before/after evidence and a call on how risky the merge is.

pr
5 · Reflect

Tune the setup

Ask what slowed the session down and fix your environment, starting with the worst problem.

/retro/handoff
Next change? Back to stop 1.

Helpers that join in on their own

These are model-invoked. You don't type them. The agent loads them when the work calls for it, though you can also name them directly.

tddRed-green-refactor, one vertical slice at a time.
code-reviewStandards and Spec reviews of the diff, in parallel.
diagnosing-bugsReproduce, minimise, hypothesise, instrument, fix, regression-test.
domain-modelingSharpens terminology and keeps GLOSSARY.md and ADRs current.
codebase-designShared vocabulary for deep modules with small interfaces.
prototypeA throwaway prototype to answer a design question.
researchPrimary-source research saved as a cited Markdown file.
Where the work goes

The day as a branching map

Drawn like a git-flow diagram. Time runs down, and each lane is a place work lives: your conversation, the docs, the tracker, branches and main. Dots are skill runs or files written. Arrows show what feeds what.

time → 09:0010:1511:0014:3016:0017:30You + agentDocsTrackerfeature/*mainfix/*v1.3.0start of the day/grill-with-docsone question at a timeGLOSSARY.md + Saved SearchADR 0007: store filter IDs/to-specspec #142/to-tickets#143 → #146 with blocking edges/implementticket #143tddred → green → refactortddnext slice: #146diagnosing-bugscheckout total 1p offtddregression test staysv1.3.1prmerge danger: mediumcode-reviewstandards + specv1.4.0prsummary · evidence · danger: low/retroworst problem firstCLAUDE.md: fast test command/handoffHANDOFF.md for tomorrow

Scroll sideways to see all six lanes.

Hour by hour

What a normal day looks like

An example day building one feature. The times are only illustrative. The order is the part that matters.

Day 0once per repo

Set up the repo /setup-matt-pocock-skills

Tell it where issues live, which triage labels you use and where docs go. Every other skill reads these answers, so you only do this once.

09:00align

Coffee and a grilling /grill-with-docs

Describe the change in one sentence. The agent asks one question at a time, each with a recommended answer. New terms go into the glossary, and hard decisions become ADRs. For non-code plans, use /grill-me.

GLOSSARY.mddocs/adr/0007-*.md
10:15plan

Spec, then tickets /to-spec/to-tickets

The whole conversation becomes a spec in your issue tracker. Then it gets cut into tracer-bullet tickets. Each ticket is a thin slice through every layer, and the blocking edges show which ones can start now.

issue #142 spec#143 → #144 → #145
11:00build

Build ticket by ticket /implement

The agent works test-first at the seams you agreed on (tdd), then reviews its own diff against your coding standards and against the spec (code-review). You review the result, not every keystroke.

tddcode-review
14:30uh-oh

Something weird breaks diagnosing-bugs

Say “diagnose this”. Instead of guessing at fixes, the agent works through gates: reproduce, shrink the case, rank hypotheses, add instrumentation, fix, then lock it in with a regression test.

16:00ship

Open the pull request pr

The body has a summary, before/after evidence and an explicit merge-danger call, so your reviewer knows how carefully to look.

17:30reflect

Retro, or hand off for tomorrow /retro/handoff

/retro suggests fixes to your environment, worst problem first: a slow test command, a missing glossary term, a vague CLAUDE.md rule. If the work isn't finished, /handoff compacts the session into a document a fresh agent can continue from.

Frievery few days

Survey the codebase /improve-codebase-architecture

It scans for deepening opportunities, shows an HTML report, then grills you on the one you pick. Matt calls it “a survey, not a rescue.”

See it happen

Four example sessions

Pick a situation. On the left is the chain of skills. On the right is a shortened conversation showing how the session goes.

~/project · saved searches for a recipe app
you
/grill-with-docs Users should be able to save a search and get told when new recipes match it.
grill-with-docsloaded · reading GLOSSARY.md
claude
Q1. Is a saved search only the query text, or the text plus filters like “vegan” or “under 30 min”?→ Recommended: text + filters, stored as one Saved Search.
you
Text plus filters. Only dietary filters for now.
claude
Q2. Where should someone find out about a new match: in the app, by email, or both?→ Recommended: in-app badge first. Email adds scheduling and unsubscribe work.
you
In-app only. Email can wait.
claude
Q3. If a dietary filter is renamed later, should old saved searches follow the rename?→ Recommended: yes. Store filter IDs, not labels.
you
Yes, IDs.
wroteGLOSSARY.md + Saved Search, + Matchdocs/adr/0007-saved-searches-store-filter-ids.md
plan
you
/to-spec
claude
Published the spec “Saved searches with in-app alerts” as issue #142.
you
/to-tickets
claude
Four tracer-bullet tickets:
  1. #143 Save a search end to end (UI → API → DB)
  2. #144 Match new recipes against saved searches (blocked by #143)
  3. #145 In-app alert badge (blocked by #144)
  4. #146 Rename and delete saved searches (blocked by #143)
build
you
/implement #143
tddred: “saving a search keeps its filter IDs” fails → green → refactor
code-reviewstandards ✓ · spec: empty query was allowed, now rejected
claude
#143 is done: 6 tests, all green. #144 and #146 are unblocked.
ship
you
/pr
claude
PR body drafted:
  • Summary: users can save a search with dietary filters
  • Before/after: screenshots of the search page
  • Merge danger: low. New table, no changes to existing data

These are illustrative sessions, shortened to show the shape. Real skill output is longer and depends on your repo.

Stuck?

Which skill do I need right now?

Choose what's happening. If none of these fit, /ask-matt routes you to the right skill.

Reach for
/grill-with-docs

Get interviewed until every decision is made. New terms and decisions are written into GLOSSARY.md and ADRs as you go.

Usually followed by /to-spec/to-tickets
Cheat sheet

All 27 skills on one page

User-invoked skills are the ones you type. They orchestrate. Model-invoked skills are tools the agent picks up when they fit.

Grill before every change

The questions are cheap. Fixing wrong assumptions after the code exists costs far more.

Keep the glossary alive

When you and the agent use the same words, misunderstandings drop. /wait-what re-explains a confusing reply using those words.

Fix the environment, not the prompt

When something goes wrong, /retro turns it into a permanent fix in CLAUDE.md, tests or tooling.