Skills mattpocock skills Engineering workflow

to-spec

Use it when:: You've already talked a feature through and want it written up as a spec.
It does:: Turns the conversation and the code into a spec, without interviewing you, and files it on your issue tracker.
You get:: An issue an agent can pick up directly: problem, solution, a long list of user stories, implementation and testing decisions, out of scope.
Needs:: An issue tracker set up by setup-matt-pocock-skills.
Runs:: Only when you call it.

Skill 12 of 24 in the Engineering workflow bundle, after chief-of-staff and before to-tickets.

Only works inside its bundle: Publishes to the issue tracker, with the ready-for-agent label, that setup-matt-pocock-skills configures. Install Engineering workflow instead.

TL;DR

It writes up what you've already discussed rather than asking more. The agent reads the repo if it hasn't yet, and uses the project's glossary terms and recorded decisions. It checks one thing with you first: where in the code the feature's tests will plug in, preferring existing places and as few of them as possible. The spec then gives an extensive numbered list of user stories ("As a…, I want…, so that…"), the modules and interfaces to build or change, schema and API decisions, and what makes a good test here. It leaves out file paths and code, which go stale, except a snippet from an earlier prototype that pins down a decision better than prose. The issue is labelled ready-for-agent, so it skips triage. It usually follows an interview such as grill-with-docs, and comes before to-tickets, which splits the spec into tickets that agents build one at a time.

Summarizes the skill at 5beb35b.

npx skills add https://github.com/mattpocock/skills --skill to-spec

skills.sh page Source on GitHub All skills from mattpocock/skills

Total Downloads: 785,209 on skills.sh, Nov 9, 2026
Repo stars: 318,714 mattpocock/skills
First seen: Jul 2, 2026 on skills.sh

Weekly Downloads

31.2K

-21% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	39,678
Sep 28	35,125
Oct 5	35,555
Oct 12	45,629
Oct 19	38,781
Oct 26	34,900
Nov 2	32,683
Nov 9	31,231

Category	category:planning category:software-engineering Make the agent question you and write the plan down before it writes code. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:command A one-shot action you invoke by name, such as turning the conversation into a PRD.
Effect	effect:remote Its own steps change something outside your machine: post, send, deploy, provision, file issues, drive a website, or upload data to a service.
Needs	needs:issue-tracker Reads or writes an issue tracker, GitHub Issues by default.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	requirements issue-tracking

SKILL.md

From mattpocock/skills at 5beb35b. Checked daily, last changed Oct 20, 2026.

Frontmatter

name: to-spec
description: "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."
disable-model-invocation: true

This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.

The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run /setup-matt-pocock-skills.

Process

Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

Check with the user that these seams match their expectations.

Write the spec using the template below, then publish it to the project issue tracker. Apply the ready-for-agent triage label - no need for additional triage.

<spec-template>

Problem Statement

The problem that the user is facing, from the user's perspective.

Solution

The solution to the problem, from the user's perspective.

User Stories

A LONG, numbered list of user stories. Each user story should be in the format of:

As an <actor>, I want a <feature>, so that <benefit>

<user-story-example>

As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending </user-story-example>

This list of user stories should be extremely extensive and cover all aspects of the feature.

Implementation Decisions

A list of implementation decisions that were made. This can include:

The modules that will be built/modified
The interfaces of those modules that will be modified
Technical clarifications from the developer
Architectural decisions
Schema changes
API contracts
Specific interactions

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

Testing Decisions

A list of testing decisions that were made. Include:

A description of what makes a good test (only test external behavior, not implementation details)
Which modules will be tested
Prior art for the tests (i.e. similar types of tests in the codebase)

Out of Scope

A description of the things that are out of scope for this spec.

Further Notes

Any further notes about the feature.

</spec-template>