Matt Pocock Skills Guide

Written by Claude, reviewed by Ricardo Sendes.

Introduction

Matt Pocock published a set of agent skills that he uses for “real engineering, not vibe coding”. A skill is a small instruction file that tells a coding agent (Claude Code, Codex, Copilot, …) how to do one job: interview you about an idea, write a spec, cut tickets, implement test-first, review code.

The skills are small and composable, which is great, but also means there are a lot of them (~40). The hard part is not using a skill, it’s knowing which one comes next. This guide is my answer to that. It walks through the path from “I have a software idea” to “it’s shipped”, split into two phases:

1. Setup Phase - start a new project from an idea
2. Iterative Phase - keep adding features and fixing bugs on that project

After that come the side workflows (bugs, triage, huge projects, upkeep) and a cheatsheet.

Prerequisites: a coding agent installed (I use Claude Code) and basic git knowledge.

---

Installation

For Claude Code, install the official plugin. It updates itself:

claude plugin install mattpocock-skills@claude-plugins-official

Start a new session afterwards, otherwise the skills are not loaded. Other agents (Codex, Copilot, Gemini) have their own install command in the README.

Pick either the plugin or a manual copy into ~/.claude/skills, not both. Otherwise every skill shows up twice.

Calling a skill

Skills are called with a slash command. Through the plugin they carry a prefix:

/mattpocock-skills:grill-with-docs

In this guide I write the short form, e.g. /grill-with-docs.

Most of the workflow skills can only be started by you (they won’t trigger by themselves). A few, like /tdd, /pr or /diagnosing-bugs, are picked up by the agent automatically when they fit.

Lost? Run /ask-matt <your question>. It knows the whole map of skills and tells you where to go next.

---

The Big Picture

Before going into detail, here is the whole flow at a glance. Everything else in this post is a zoom-in on one of these boxes.

flowchart TD
    A["Idea"] --> B["/grill-with-docs"]
    B -->|"needs a runnable answer"| P["/prototype"]
    P --> B
    B --> C{"Multi-session build?"}
    C -->|"no"| I1["/implement"]
    C -->|"yes"| S["/to-spec"]
    S --> T["/to-tickets"]
    T --> W{"Build how?"}
    W -->|"ticket by ticket"| I2["/implement next ticket"]
    I2 --> L{"Tickets left?"}
    L -->|"yes, /clear first"| I2
    W -->|"all at once"| IS["/implement-spec"]
    I1 --> R["/code-review"]
    L -->|"no"| R
    IS --> R
    R --> RT["/retro"]
    RT -->|"next idea"| B
    linkStyle default stroke:#5b8def,stroke-width:2px

Three words that will come up a lot:

Term	Meaning
Spec	A written plan for a feature: problem, solution, how it gets tested
Ticket	One small, self-contained piece of the spec. Each ticket is a thin “tracer bullet” slice that works end to end
Issue tracker	Where specs and tickets live: GitHub Issues, GitLab Issues or plain markdown files in .scratch/

---

Phase 1: Setup Phase (Idea → First Version)

This is the phase where you start from nothing but an idea. The goal is to think first, build second.

Step 1 - Create the repo

Even an empty folder with git init is enough. The skills write their notes into the repo, so it needs to exist before you start thinking.

Step 2 - /setup-matt-pocock-skills (once per repo)

This skill does not build anything. It asks a few questions and writes small config files that the other skills read:

• docs/agents/issue-tracker.md - where tickets live (GitHub, GitLab, local markdown, or something custom)
• docs/agents/triage-labels.md - label names for /triage
• docs/agents/domain.md - where the glossary and decision records go
• an ## Agent skills section in CLAUDE.md / AGENTS.md pointing to all of that

For a solo project without a remote, pick local markdown. Tickets become files under .scratch/<feature>/ and no CLI login is needed.

Step 3 - /grill-with-docs (sharpen the idea)

The agent interviews you, hard. One round of questions at a time, until every open decision about the idea is settled. Facts it looks up itself, decisions are yours.

While doing that, it keeps a paper trail:

• GLOSSARY.md - the words of your project and what exactly they mean (“user” vs “account” vs “member”)
• ADRs (Architecture Decision Records) - short notes on decisions that are hard to reverse

This pays off later: every following skill uses the same vocabulary, so the agent and you stop talking past each other.

There is also /grill-me. Same interview, but it saves nothing. Use it for things without a repo (a plan, a text, a decision). Inside a repo, /grill-with-docs is always the better choice.

Step 4 (optional) - Prototype detour

Some questions can’t be answered by talking: “does this data model feel right?”, “what should this screen look like?”. Then you take a detour:

1. /handoff - writes the current conversation into a markdown file
2. open a fresh session and run /prototype - throwaway code that answers one question
3. /handoff back what you learned, and continue the grilling

The prototype is kept on a prototype/<name> branch as a reference, not merged.

Step 5 - /to-spec

Turns the conversation into a spec and puts it into the issue tracker. It does not interview you again, it just writes down what was already discussed. It will check with you where the tests should hook into the code (“seams”).

Step 6 - /to-tickets

Splits the spec into tickets. Each ticket is a vertical slice (a bit of UI, logic and data, working end to end) and lists which other tickets block it.

Keep steps 3 to 6 in one unbroken session. Don’t clear or compact before /to-tickets is done, so the spec and tickets are built on the same thinking.

Step 7 - Build

Two ways to work through the tickets:

Option	How	When
/implement <ticket>	One ticket at a time, /clear between tickets	You want to watch and steer every step
/implement-spec	Whole spec at once, subagents work on unblocked tickets in parallel, one integration branch	You’d rather orchestrate than drive

Both build test-first with /tdd (red → green → refactor, one small slice at a time), run /code-review at the end and commit.

Step 8 - /retro

Run it in the same session, before clearing. It looks back at what went wrong or slow and suggests changes to the environment, not the code:

• mechanical mistakes → a linter rule, pre-commit hook or CI check
• judgement calls → a rule in the coding standards that /code-review enforces
• the agent searched forever → a pointer in CLAUDE.md

Every project after that starts from a better setup.

Setup Phase in short

create repo → /setup-matt-pocock-skills → /grill-with-docs → (/prototype)
            → /to-spec → /to-tickets → /implement (loop) → /retro

---

Phase 2: Iterative Phase (Working on an existing project)

Once the first version is out, the setup step is done. Every new piece of work runs through a shorter version of the same loop. The only question is: what kind of work is it?

flowchart TD
    N["New work"] --> Q{"What is it?"}
    Q -->|"feature idea"| G["/grill-with-docs"]
    Q -->|"small, concrete behaviour"| TDD["/tdd"]
    Q -->|"something is broken"| D["/diagnosing-bugs"]
    Q -->|"issues from others"| TR["/triage"]
    G --> SZ{"Fits in one session?"}
    SZ -->|"yes"| IM["/implement"]
    SZ -->|"no"| SP["/to-spec → /to-tickets"]
    SP --> IL["/implement next ticket"]
    IL --> LT{"Tickets left?"}
    LT -->|"yes, /clear first"| IL
    LT -->|"no"| RT
    TR --> IM
    TDD --> CR["/code-review"]
    D --> RT["/retro"]
    IM --> RT
    linkStyle default stroke:#5b8def,stroke-width:2px

New feature

Start at /grill-with-docs again. The difference to the Setup Phase: the glossary and ADRs already exist, so the interview builds on them instead of starting from zero.

• Small feature (fits in one session): /implement right in the same session
• Big feature: /to-spec → /to-tickets → /implement per ticket, exactly like the Setup Phase

Small, concrete change

If you already know exactly what behaviour you want (“the export button should also offer CSV”), skip the grilling. Run /tdd directly, then /code-review.

Pull requests

When the agent opens a PR, /pr shapes the description: a small visual of the change, before/after proof that it works, and whether the change is easy to undo. The agent uses it automatically.

Iterative Phase in short

feature  → /grill-with-docs → /implement (or spec → tickets → implement (loop)) → /retro
change   → /tdd → /code-review
bug      → /diagnosing-bugs → /retro

---

Other Workflows

These don’t belong to a phase. You reach for them when a specific situation comes up.

Hard bugs: /diagnosing-bugs

For the bugs that don’t show themselves at first glance: intermittent failures, performance regressions, “it worked last week”. The rule here: no guessing. First it builds one command that reliably shows the bug (red), only then it fixes it and adds a regression test. Afterwards run /retro in the same session and ask what would have prevented this bug.

Incoming issues: /triage

For bug reports and feature requests that other people wrote. It sorts them by role (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix), asks follow-up questions and turns good ones into agent-ready briefs that /implement can pick up.

Don’t triage tickets that /to-tickets created. Those are already agent-ready.

Huge, foggy projects: /wayfinder

When the idea is so big that you can’t even see the path to the goal (a greenfield product, a huge rewrite). Instead of building, it creates a map of decision tickets in the issue tracker and resolves them one by one over many sessions. It produces decisions, not code. When the map is clear, hand off to /to-spec and continue with the normal flow.

Only use this when /grill-with-docs can’t hold the idea in one session. For a well-scoped feature it is overkill.

Codebase upkeep: /improve-codebase-architecture

Run it when you have some spare time. It scans the code for “deepening opportunities” (places where a lot of logic could hide behind a smaller, cleaner interface) and shows them in a report. Pick one and it becomes a new idea for /grill-with-docs.

Helpers you can use anytime

Skill	Use it when
/research	You need facts from docs/APIs. A background agent reads primary sources and writes a cited markdown file into the repo
/to-questionnaire	The missing information is in someone else’s head. Writes a questionnaire for them
/wizard	A step only a human can do (credentials, dashboards, secrets). Generates an interactive bash script for it
/wait-what	The agent’s last message made no sense. It explains again in plain words
/handoff	Moving work to another folder, tool or colleague
/teach	Learning a topic over several sessions

---

Context Management (When to Start Fresh)

This section is not about a skill, it’s about the agent’s memory. It explains the “/clear between tickets” and “one unbroken session” advice from above.

Why it matters

The agent only remembers what is in the current conversation, its context window. Every message, file it read and command output fills it up. The fuller it gets, the worse the agent reasons: it forgets early decisions and gets sloppy. Matt calls the part where it still thinks sharply the smart zone, roughly the first 150k tokens (a long session of reading code gets there).

So whenever you finish one chunk of work (the grilling, a ticket, a bug fix) and start the next, ask yourself: should the agent take what it knows into the next chunk, or start fresh?

Your options

Only /handoff is one of Matt’s skills. /clear and /compact are built into Claude Code, and the other two aren’t commands at all.

Option	What it is	Use it when
Just keep going	Nothing to do, keep typing in the same session	The next step builds on this conversation. Example: grilling → /to-spec → /to-tickets
/clear	Claude Code command, wipes the conversation	Nothing in it matters anymore. Example: between two tickets, since each ticket explains itself
/compact	Claude Code command, replaces the conversation with a summary	You need to carry on but the session is getting long
/handoff	Matt’s skill, writes the conversation into a markdown file	The work moves somewhere else: another folder (a prototype), another tool or a colleague
Subagent	Ask the agent to give a small side task to a subagent	You only need the result, not all the searching that leads to it. Your main session stays clean

Rule of thumb: keep going while the next step needs the current conversation, /clear when it doesn’t, and /compact when it does but the session is getting too long.

---

Cheatsheet

Situation	Skill
New repo, first time	/setup-matt-pocock-skills
Have an idea	/grill-with-docs
Idea needs a quick experiment	/prototype
Write it down as a plan	/to-spec
Split the plan into work	/to-tickets
Build one ticket	/implement
Build the whole spec	/implement-spec
Build one behaviour test-first	/tdd
Review a branch	/code-review
Look back and improve the setup	/retro
Something is broken	/diagnosing-bugs
Sort incoming issues	/triage
Project too big to see the path	/wayfinder
Clean up the codebase	/improve-codebase-architecture
Not sure what’s next	/ask-matt

Resources

• mattpocock/skills on GitHub
• skills.sh page
• Smart Zone explained (AI Hero)