Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 24 October 2026
What is the to-spec skill?
The to-spec skill turns the conversation you just had with your agent into a written spec and publishes it to your issue tracker as one issue. It does not ask new questions: it records the decisions you already made, so a fresh session can build from them after you clear the context.
It comes from mattpocock/skills, which Matt Pocock describes in the README as "My agent skills that I use every day to do real engineering - not vibe coding." The skill's description reads: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed."
It used to be called to-prd. As of 24 October 2026, its skills.sh page listed about 715,000 installs (snapshot, 24 October 2026).
What does it do?
The SKILL.md opens with "Do NOT interview the user; just synthesize what you already know." Its process has three steps:
- Explore the repo if it hasn't already, using the project's glossary vocabulary and respecting ADRs in the area.
- Sketch the test seams. Prefer existing seams, use the highest one possible, and propose as few as possible: "the ideal number is one." It checks the seams with you.
- Write the spec and publish it to the tracker with the
ready-for-agenttriage label.
The spec template has seven sections:
| Section | What goes in it |
|---|---|
| Problem Statement | The problem, from the user's perspective |
| Solution | The solution, from the user's perspective |
| User Stories | "A LONG, numbered list" in the form As an <actor>, I want a <feature>, so that <benefit> |
| Implementation Decisions | Modules, interfaces, architecture, schema changes, API contracts |
| Testing Decisions | What makes a good test, which modules get tested, prior art |
| Out of Scope | What this spec excludes |
| Further Notes | Anything else |
The template bans file paths and code snippets, since "They may end up being outdated very quickly." The one exception is a prototype snippet that encodes a decision more precisely than prose, such as a state machine or type shape, trimmed to the important bits.
The repo's docs for to-spec explain why seams come first: the tdd skill only tests at seams agreed in advance, and code-review checks the diff against the spec, so an unagreed seam shows up as a review finding.
How do you install it?
The README gives a plugin route and an editable-files route, and says to pick one per agent so you don't get every skill twice.
Claude Code plugin (whole set, updates itself). The collection is listed in Anthropic's official plugin marketplace:
claude plugin install mattpocock-skills@claude-plugins-official
Plugin skills are namespaced, so it appears as /mattpocock-skills:to-spec.
Codex plugin. From the README:
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Editable files with the skills CLI. The command on skills.sh:
npx skills add https://github.com/mattpocock/skills --skill to-spec
The SKILL.md tells the agent to have you run /setup-matt-pocock-skills if no tracker and label vocabulary are configured. The skills CLI accepts --skill more than once, so you can take its neighbors in the chain too:
npx skills add https://github.com/mattpocock/skills --skill to-spec --skill to-tickets --skill setup-matt-pocock-skills
Add -g for all projects. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills. For the tracker step, see the setup skill page.
How do you use it?
Run it at the end of a planning conversation, usually right after grill-with-docs, in the same context window. The skill sets disable-model-invocation: true, which per the Claude Code skills docs means "Claude can't invoke the skill on its own," so you type /to-spec.
The docs give one trigger: the build is too big for one agent session.
| Where you are | What to run |
|---|---|
| Nothing decided yet | grill-with-docs first |
| Decided, fits one context window | implement, skip the spec |
| Decided, spans several sessions | /to-spec, then to-tickets |
| A wayfinder map has cleared | /to-spec #<map_issue> |
Example prompts (suggestions, not quotes from the repo):
/to-spec/to-spec Keep the seams to the public API of the export module; we agreed on that earlier./to-spec #310(pointing at a cleared wayfinder map issue)/to-spec This is a refactor, so keep user stories short and put the weight in implementation and testing decisions.
Before you move on, the docs suggest reading two parts closely: the seams and the out-of-scope section, where a wrong decision is cheapest to catch. Then run /to-tickets in the same window. The docs explain why: a very large spec may not come back in full from the tracker, and staying in one window means to-tickets never has to fetch it.
The repo's main chain, from the docs:
grill-with-docs → to-spec → to-tickets → implement → code-review → retro
Tips and limits
From the repo's docs, not from testing:
- The label can trigger unattended builds.
ready-for-agentmarks the spec as complete input, but agents that poll for it may try to build the whole spec at once. The docs call this the most-reported problem. - It invents nothing, ideally. "If the spec states something you never said, that is a defect." A spec that surprises you usually means the grilling was too shallow.
- The spec goes stale. Nothing keeps it in sync after implementation starts. Lasting knowledge belongs in
GLOSSARY.mdand ADRs. - User stories fit refactors badly. For architecture work, lean on the implementation and testing decision sections.
- No duplicate check. It does not search the tracker for overlapping issues and does not link the ADRs it follows.
- Skip it on small work. On a single-session change it adds a step where the model can drift.
As of 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk. The skill runs no scripts; it creates one issue on your tracker. It is MIT licensed, so you can copy and change it, including the spec template, as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. If your team wants a different spec template, edit your copy there; changes to an installed copy get overwritten by npx skills update, per the docs. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Matt Pocock or mattpocock/skills.
Similar skills
- Grill with docs skill: makes the decisions that
to-specrecords. - Wayfinder skill: multi-session planning that hands off to
to-spec. - Implement skill: builds the tickets cut from the spec, one per session.
- Implement spec skill: builds every ticket of the spec in one parallel run.
- Spec-driven development skill: a different take on writing a spec before code.