Matt Pocock's Skills:
From Idea to Ship

The problem: a fast agent with no process

Part 1 · The problem

An AI coding agent writes code fast. That speed is the problem, because the agent left alone writes plausible code that quietly rots the codebase.^[1]

A senior engineer does not start with code. They ask questions first. They write a plan, split it into small tasks, build test-first, and review the result. The agent skips all of these steps unless you force it to take them.

You could force it by hand. You could type a long careful prompt for every task, every day. But you would repeat yourself, forget steps, and drift. The fix is to write each good habit down once, as a file the agent reads on demand.

That file is a skill: a small, sharp instruction set that makes the agent follow one process the same way every time.^[1] Matt Pocock, known for Total TypeScript and AI Hero, maintains a set of 25 such skills in one MIT-licensed repo.^[1][2] You install the ones you want, then trigger each one with a slash command such as /grill-me.

The skills form a chain. Each skill's output is the next skill's input, so tuning one step improves the whole workflow.^[1] This tutorial walks the full chain, one group at a time, on a single project.

The project: LinkLoft

Part 2 · The project

To see the skills work, we need one project that runs through the whole tutorial. Ours is LinkLoft: a small TypeScript URL shortener.

LinkLoft does three things. A user pastes a long URL and gets back a short slug (the short code at the end of a short link, like linkloft.dev/x7Kp2). A visitor who opens the short link is redirected to the long URL. The owner sees a count of hits (recorded visits) per link.

"Done" for this tutorial means: LinkLoft has a new "link expiry" feature, a triaged backlog, passing tests, and documentation the agent itself can navigate. Every part below moves the project toward that state, or shows a real situation (a bug, a merge conflict, a fuzzy plan) on the way.

You do not need to build LinkLoft yourself. The project is a lens. Watch what each skill does to it, then apply the same move to your own repo.

Setup: install the skills

Part 3 · Setup

Installation is one command. The installer writes editable skill files into your project.^[1]

npx skills@latest add mattpocock/skills

The installer lets you pick which skills and which agents you use. Later, npx skills update refreshes them.^[1]

If you use Claude Code, there is a second path: install the whole set as a managed plugin from the official marketplace.^[1]

claude plugins install mattpocock-skills

The plugin updates automatically but is read-only. The npx path gives you editable files. Pick the plugin if you want zero maintenance; pick npx if you want to tune the skills to your team.

Naive v1: vibe-prompting a feature

Part 4 · Naive v1

Before the skills, we build the way most people build. We open the agent in the LinkLoft repo and type one prompt.

Add link expiry to LinkLoft. A link can have an expiry date.
Expired links should stop redirecting.

The agent works for four minutes and produces a diff. It adds an expiresAt column, a check in the redirect handler, and a date picker in the UI. The code compiles. The demo works. We merge it.

Celebrate this honestly: v1 works, and it took one prompt. For a throwaway script, this is the right way to build. The failures only appear because LinkLoft is a codebase we must live in.

Where v1 fails

Part 5 · The failures

Two weeks of v1-style building leaves LinkLoft in trouble. The failures are concrete, and each one has a name. Every upgrade in this tutorial exists to remove one of them.^[1][3]

Failure 1: the silent guess. The prompt never said what happens to an expired link's hit count, or whether expiry can be removed. The agent guessed both. It guessed wrong on one. Nobody decided; the code decided.

Failure 2: the vanished plan. The reasoning behind the expiry design lived only in one chat session. The session is gone. A month later, nobody can say why expiresAt is nullable, so the next change re-argues the whole design.

Failure 3: the overflowing window. We tried to plan a bigger feature — team workspaces — in one long chat. Past a certain size, the model's answers got vague and repetitive. The context window filled up, and quality fell before we noticed.^[3]

Failure 4: the confident rot. Each merged diff looked fine alone. Together they drifted: three names for the same concept, logic copied into two places, and no test that fails when the redirect breaks. The codebase is now harder for the agent to navigate, which makes every next diff worse.

Failure 5: the raw backlog. Users filed issues. The issues sit unlabeled and half-specified. Nobody knows which ones an agent could safely pick up.

Hold these five names. The rest of the tutorial removes them one by one.

Upgrade 1 — Getting started: /setup-matt-pocock-skills and /ask-matt

Part 6 · Getting started

The first upgrade does no feature work. It gives the repo a shape the other skills can rely on, and gives you a guide for the moments you forget which skill to use. This group has two skills.^[1]

/setup-matt-pocock-skills: configure the repo once

The engineering skills assume three things about a repo: where issues live, which triage labels exist, and where the domain documents sit. /setup-matt-pocock-skills scaffolds exactly that, once, before first use.^[4]

You run it in the LinkLoft repo. The skill explores first — it reads the git remotes, any existing AGENTS.md or CLAUDE.md, and the repo root — then presents what it found and confirms with you before writing anything.^[4] For LinkLoft it sets up:

• an issue tracker config: GitHub Issues by default, or plain local Markdown files if the repo has no tracker^[4]
• the label strings that map to the five canonical triage roles (Part 9 uses these)
• the layout for CONTEXT.md and ADRs (Architecture Decision Records: short documents that record a hard-to-reverse decision and its reasons)

Which failure this removes: none yet, directly. It is the foundation the later skills stand on. Skip it and skills like /triage and /to-spec will stop and tell you to run it.^[4][5]

/ask-matt: the router

Twenty-five skills is too many to memorize. /ask-matt is a router: you describe your situation, and it tells you which skill or flow fits.^[3]

The skill's own text contains the map of the whole system: one main flow (the idea→ship spine), on-ramps that merge into it, standalone skills, and a vocabulary layer underneath.^[3] When you are lost, this is the skill to reach for. Part 13 of this tutorial compresses that map into a table.

Upgrade 2 — The main flow: idea → ship

Part 7 · The main flow

This is the spine of the whole system: five skills, run in order, that take an idea to shipped code.^[1][3] We rebuild the expiry feature properly — this time as "expiry v2: editable expiry dates" — to see each step.

flowchart LR
    A["/grill-with-docs
sharpen the idea"] --> B["/to-spec
write the spec"]
    B --> C["/to-tickets
split into tickets"]
    C --> D["/implement
build test-first"]
    D --> E["/code-review
review the diff"]
          

Step 1 — /grill-with-docs: get interviewed, leave a paper trail

You start with the idea, not with code. /grill-with-docs runs a relentless interview that stress-tests the plan, and records what it learns into CONTEXT.md and ADRs as you go.^[6]

For LinkLoft, the interview surfaces the exact questions v1 guessed at: What happens to hits when a link expires? Can an owner un-expire a link? Is expiry checked at redirect time or by a cleanup job? You answer; the agent records. The silent guess (Failure 1) dies here, and because the decisions land in ADRs, the vanished plan (Failure 2) dies with it.

Under the hood, /grill-with-docs is thin: it calls two other skills, /grilling (the interview engine) and /domain-modeling (the recording discipline).^[6] Part 11 covers both.

Step 2 — /to-spec: freeze the conversation into a spec

When the interview settles every question, /to-spec turns the conversation into a written spec (a structured document stating the problem and the agreed solution) and publishes it to the issue tracker.^[5] It does not interview you again; it only synthesizes what the thread already agreed.^[5]

One detail matters most: before writing, the skill sketches the seams — the public interfaces where the feature will be tested — and confirms them with you. It prefers existing seams, and the fewer the better.^[5] For expiry v2, the seam is the redirect handler's public interface, not the database row.

Step 3 — /to-tickets: split the spec into tracer bullets

A spec too big for one session must be split. /to-tickets breaks the spec into tracer-bullet tickets: small vertical slices that each cut through the whole stack, with each ticket declaring which tickets block it.^[7]

On a real tracker the blocking edges become native links; on a local tracker they are text in one file per ticket.^[7] Either way, any ticket whose blockers are done is safe to grab. Expiry v2 becomes three tickets: the schema change, the redirect check, and the edit UI.

Step 4 — /implement: build one ticket, test-first

/implement takes one finished ticket and builds it.^[8] It drives /tdd internally at the pre-agreed seams, runs typechecking and single test files as it goes, and runs the full suite once at the end.^[8] The confident rot (Failure 4) starts dying here, because every behavior now has a test that fails when it breaks.

The critical habit sits between tickets: clear the context window before each /implement run.^[3] Each ticket is self-contained, so the last ticket's context is disposable. This is the first blow against the overflowing window (Failure 3); Part 12 finishes it.

Step 5 — /code-review: two axes, in parallel

Before merging, /code-review reviews the diff since a fixed point (a branch, commit, or tag) along two separate axes:^[9]

• Standards: does the code follow this repo's documented coding standards?
• Spec: does the code faithfully implement the originating spec or issue?

The two reviews run as parallel sub-agents so they do not pollute each other's context, then the skill merges their findings into one report.^[9] /implement calls this automatically at the end, and you can also run it alone on any branch or PR.^[8][3]

Upgrade 3 — Shaping: when talk is not enough

Part 8 · Shaping

Some questions cannot be settled in conversation. The answer needs running code, a primary source, or a map bigger than one session. The three shaping skills exist for exactly these situations, and each one feeds its answer back into the main flow.^[1]

/wayfinder: chart a huge, foggy effort

LinkLoft's next idea is big: team workspaces, with members, roles, and shared links. It is too big for one agent session, and the path from here to there is not visible yet. That is the exact trigger for /wayfinder.^[10]

Wayfinder charts the effort as a shared map: a set of decision tickets on the issue tracker, where each ticket is a question whose resolution is a decision, not a slice of build work.^[10] You resolve the tickets one at a time — each resolution is a small grilling session — until nothing is left to decide. Wayfinder plans; it does not build.^[10]

When the map is clear, it hands off to the main flow at /to-spec, which collapses the linked decisions into a buildable plan.^[3] Wayfinder is the most cognitively demanding flow in the set, so save it for genuinely foggy efforts, never a well-scoped feature.^[3]

/prototype: answer a design question with throwaway code

One workspace question resists talk: does the proposed role-permission state model actually feel right? /prototype answers a design question with code you then throw away.^[11]

The skill first picks a branch based on the question:^[11]

• "Does this logic feel right?" → a single shareable HTML file with buttons and guided walkthroughs, so even a non-developer can push the state machine through hard cases.
• "What should this look like?" → several radically different UI variations on one route, switchable by a URL parameter.

The rules are strict: throwaway from day one and clearly named as such, trivial to run, no persistence, no polish, and the full state visible after every action.^[11] The answer folds into the real code; the prototype itself is kept out of main as a primary source, pointed at from the implementation issue.^[3]

/research: get a cited answer from primary sources

A third workspace question is factual: what exactly does our auth provider's API allow for organization invites? /research spins up a background agent to investigate the question against primary sources — official docs, source code, specs — never a blog post about them.^[12]

The background agent writes its findings to one Markdown file in the repo, citing each claim's source, while you keep working.^[12] The file then feeds the grilling or the spec.

Upgrade 4 — Upkeep: bugs, backlog, and rot

Part 9 · Upkeep

Feature work is half the job. The other half is keeping the codebase and the issue list healthy. The five upkeep skills handle the situations that generate work for the main flow.^[1]

/triage: sort the raw backlog

LinkLoft's issue tracker holds the raw backlog from Failure 5. /triage moves those issues through a small state machine of roles.^[13] Every issue gets exactly one category role — bug or enhancement — and one state role:^[13]

During triage the skill checks the codebase for an existing implementation of the request, checks past rejections, and writes an agent brief for issues that reach ready-for-agent.^[13] External pull requests ride the same machine — a PR is treated as an issue with attached code.^[13] Every comment the skill posts starts with a disclaimer that AI generated it during triage.^[13]

Triage is only for issues you did not create. Tickets from /to-tickets are already agent-ready, so never triage them.^[3]

/diagnosing-bugs: the feedback-loop discipline

A user reports that some expired links still redirect, but only sometimes. This is a hard bug, so we reach for /diagnosing-bugs.^[14]

The skill's core belief: the feedback loop is the skill; everything else is mechanical.^[14] Phase 1 builds a tight pass/fail signal — one command that goes red on this exact bug — before any theorising. With that loop in hand, bisection, hypothesis-testing, and instrumentation all just consume it.^[14] The skill also demands redaction: every secret in shown output becomes <REDACTED>.^[14] The fix lands with a regression test, and if the post-mortem finds there was no good seam to lock the bug down, it hands off to /improve-codebase-architecture.^[3]

/resolving-merge-conflicts: resolve by intent

Two long-running LinkLoft branches collide. /resolving-merge-conflicts finishes the in-progress merge or rebase hunk by hunk.^[15] For each conflict it traces both sides back to their primary sources — commit messages, PRs, original tickets — and resolves by intent, preserving both where possible.^[15] It never invents new behavior and never runs --abort; it resolves, runs the project's checks, and completes the operation.^[15]

/improve-codebase-architecture: find what is worth deepening

With no urgent work, we spend an hour on health. /improve-codebase-architecture scans the codebase for deepening opportunities: refactors that turn shallow modules into deep ones, for testability and AI-navigability.^[16]

It scopes before it scans — recent commit history pulls attention to the hot spots — and presents its findings as a visual HTML report.^[16] Picking one opportunity generates an idea, and that idea enters the main flow at /grill-with-docs like any other.^[3] This is the skill that finally kills the confident rot (Failure 4) at the codebase level.

/wizard: script the steps only a human can do

Deploying LinkLoft needs API keys from three dashboards. An agent cannot click those consoles, and re-explaining the steps every time is tedious. /wizard generates an interactive bash script that walks a human through the procedure: it opens each URL, says what to click and copy, captures the values, writes them to .env or GitHub secrets, and shows progress stage by stage.^[17]

The delightful parts — confirmation gates, hidden secret entry, cross-platform URL opening — live in a fixed template library the skill never edits; your wizard only authors the stages.^[17] A wizard is ephemeral by default: built for one run, deleted after, committed only if the team wants a repeatable setup path.^[17]

Upgrade 5 — Productivity: the human-facing skills

Part 10 · Productivity

The last group is not about code. These six skills serve the human workflows around the work: aligning on ideas, moving context between sessions and people, and learning.^[1]

/grill-me: the interview, anywhere

/grill-me runs the same relentless interview as /grill-with-docs, but stateless: it saves nothing and builds no CONTEXT.md.^[18][3] Reach for it when there is no repo under the idea — a blog post outline, a hiring plan, a conference talk. Inside a working directory, prefer /grill-with-docs, because the same interview then leaves a paper trail.^[3]

/handoff: move a session's context somewhere else

A LinkLoft session grows long, and a colleague must continue the work tomorrow. /handoff compacts the conversation into a portable Markdown document a fresh agent can pick up.^[19] It saves outside the workspace, redacts secrets, references existing artifacts (specs, ADRs, commits) by path instead of duplicating them, and names which skills the next agent should load.^[19] Use it narrowly: a new harness, a new directory, a colleague, or forking a side task mid-phase.^[3]

/to-questionnaire: pull knowledge out of someone else

One expiry question — the legal retention period for hit data — only the company's lawyer can answer. /to-questionnaire turns it into a Markdown questionnaire the lawyer fills in async.^[20] The skill grills you only about the send — who receives it, and what you need back — then writes questions aimed at the gap between what they know and what you need, most-important-first.^[20]

/teach: learn a topic across sessions

You realize you do not really understand HTTP caching, which LinkLoft's redirects depend on. /teach turns the current directory into a stateful teaching workspace: a mission file for why you are learning, gathered resources, self-contained HTML lessons, and learning records that track what stuck.^[21] It refuses to trust the model's parametric memory; it grounds lessons in gathered high-trust resources first.^[21] The tutorial you are reading now follows an adapted version of this skill's philosophy.

/wait-what: say that again, plainly

Sometimes the agent's last message is a wall of dense prose. /wait-what is the smallest skill in the set: it tells the agent to stop and re-pitch the last message with context, in Simplified Technical English, using the project's own vocabulary from CONTEXT.md.^[22] One command, instant clarity.

/writing-for-agents: write documents agents can follow

When your team starts editing the installed skills — or writing an AGENTS.md — /writing-for-agents is the reference for doing it well.^[23] Its core ideas: a context pointer (a line in context that names out-of-context material and states when to reach it) must be worded sharply, because the wording decides whether the agent ever loads the material.^[23] Every document spends one of two budgets — context load on the agent's window, or cognitive load on the human — and progressive disclosure (pushing reference material behind pointers) is how you keep the top of a document legible.^[23]

The reference layer underneath

Part 11 · Reference skills

Four skills rarely start a session. They are the vocabulary and rule layer the other skills invoke, and the agent can pull them in by itself when the situation matches their descriptions.^[1][2] Knowing them explains how the system holds together.

flowchart TD
    GWD["/grill-with-docs"] --> G["/grilling
the interview engine"]
    GWD --> DM["/domain-modeling
glossary + ADRs"]
    GM["/grill-me"] --> G
    TR["/triage"] --> G
    WF["/wayfinder"] --> G
    IMP["/implement"] --> TDD["/tdd
red–green rules"]
    ICA["/improve-codebase-architecture"] --> CD["/codebase-design
deep-module vocabulary"]
    TDD --> CD
          

/grilling: the interview engine

/grilling is the primitive behind every interview in the system.^[24] It maps a plan as a design tree — every decision branches into the decisions that hang off it — and works the tree in rounds. Each round asks the whole frontier: every question whose prerequisites are already settled, numbered, each with the agent's recommended answer.^[24]

Two rules give the interview its character. Facts are the agent's job: when a question needs a fact from the environment, it dispatches a sub-agent to look it up rather than asking you.^[24] Decisions are yours: every real choice is put to you, and the session ends only when the frontier is empty and nothing is silently assumed.^[24] /grill-me and /grill-with-docs are the two named ways in; /triage, /wayfinder, and /improve-codebase-architecture all run it internally.^[3]

/tdd: the rules of red–green–refactor

/tdd is the reference /implement drives.^[8][25] Its center: a good test verifies behavior through a public interface, reads like a specification, and survives refactors because it never touches internals.^[25] Tests live only at seams — the public boundaries where behavior is observable — and only at seams agreed with you before any test is written.^[25] Agreeing the seams up front is how testing effort lands on critical paths instead of every edge case.^[25]

/codebase-design: the deep-module vocabulary

/codebase-design is a glossary the design skills speak, and it insists on exact words.^[26] A module is anything with an interface and an implementation, at any scale. An interface is everything a caller must know — types, invariants, error modes — not just the signature. Depth is leverage: how much behavior a caller gets per unit of interface learned. A seam is the place where you can alter behavior without editing in that place, and an adapter is a concrete thing that fills a seam.^[26] The skill bans the fuzzy substitutes — "component", "service", "API", "boundary" — because consistent language is the whole point.^[26] /tdd and /improve-codebase-architecture both speak this vocabulary.^[3]

/domain-modeling: sharpen the project's words

/codebase-design covers the shape of code; /domain-modeling covers the language of the domain.^[27] It is the active discipline of challenging fuzzy terms, resolving overloaded words ("account" doing three jobs), and writing the results down the moment they crystallise: the glossary into CONTEXT.md, hard-to-reverse decisions into ADRs.^[27] Merely reading CONTEXT.md is not this skill; this skill fires when the model is being changed.^[27] For LinkLoft it is why "slug" and "hit" mean exactly one thing everywhere.

Context hygiene and phase boundaries

Part 12 · Context hygiene

Failure 3 — the overflowing window — deserves its own part, because the skills encode a precise discipline for it.^[3]

The limit is the smart zone: the window, roughly 150k tokens on state-of-the-art models, inside which the model still reasons sharply.^[3][28] Push past it and quality degrades before you notice. The discipline has two halves.

First, the main flow's rule from Part 7: keep grilling → spec → tickets in one unbroken session, then start each /implement fresh.^[3]

Second, at every phase boundary — the joint between two chunks of work, like the end of a grilling or the end of a build — you choose between five options:^[3]

1. Continue in the same window. Costs nothing, loses nothing; rule it out first, not last.
2. Clear the window, when nothing here matters to what is next.
3. /handoff, only for a new harness, a new directory, a colleague, or a mid-phase fork.
4. Sub-agent: send one tightly-scoped task to its own window and get a report back.
5. Compact: compress this context into a fresh session. The default, at the bottom of the tree.

Make this choice at a boundary, never in the middle of a phase.^[3] If a session nears the smart zone before /to-tickets, do not push on degraded; compact at the nearest boundary and carry on.^[3]

Situation → skill: the quick map

Part 13 · The map

This table compresses /ask-matt into one glance.^[3] All 25 skills appear.

Checklist and where to go next

Part 14 · Conclusion

Your workflow runs on the skills when all of this is true:

• The skills are installed, by npx skills or the Claude Code plugin.^[1]
• Each repo you work in has run /setup-matt-pocock-skills once.^[4]
• New features enter through /grill-with-docs, not through a raw prompt.^[3]
• Grilling, spec, and tickets share one session; each /implement starts clean.^[3]
• Every diff gets a two-axis /code-review before merge.^[9]
• Foggy efforts go to /wayfinder; runnable questions to /prototype; factual ones to /research.^[3]
• The backlog moves through /triage, and hard bugs start from a red feedback loop.^[13][14]
• Decisions live in ADRs and CONTEXT.md, and one concept has one name.^[27]
• At phase boundaries, you consciously pick continue, clear, handoff, sub-agent, or compact.^[3]

Read next, in this order:

1. The skills homepage, for install options and the free seven-lesson email course.^[1]
2. The mattpocock/skills repo itself — every skill is a short, readable SKILL.md.^[2]
3. "5 agent skills I use every day", for which skills to adopt first.^[29]