Conversation to spec

Turns the current conversation and codebase into a spec with user stories, implementation and testing decisions, and publishes it to the issue tracker as ready-for-agent, without interviewing the user. Use when a discussed feature needs writing up.

DocumentationPack: Matt Pocock's skills75 linesto-spec
Author
Source
mattpocock/skills/skills/engineering/to-spec @ abeeaf9
License
MIT · Copyright (c) 2026 Matt Pocock

About this skill

What it does

To-spec writes up what you and the agent have already discussed as a spec and publishes it to the project's issue tracker. There is no interview: the agent explores the repo, uses the glossary terms, respects ADRs and synthesises. It only checks with you the seams where the feature will be tested: existing ones first, as high as possible, ideally one.

The template is fixed: the problem and the solution from the user's side, a long numbered list of user stories ("As an <actor>, I want…, so that…"), implementation decisions (modules, interfaces, schema changes, API contracts), testing decisions with prior art from the codebase, out of scope and further notes. File paths and code are left out because they go stale, except a prototype snippet that pins a decision, such as a state machine or a type shape, better than prose. The issue gets the ready-for-agent label.

When to use it, and when not

Use it at the end of a design discussion, when the decisions should land in the tracker.

Skip it while the idea is still vague: the skill fills no gaps by asking, so run Grilling a plan first. It also expects the agent to know the tracker and its labels. The author's setup-matt-pocock-skills configures that but is not in our catalog; you can just tell the agent which tracker and label to use.

How to run it

The install command below puts the folder in place: SKILL.md with the template, the licence and the Codex manifest agents/openai.yaml. With disable-model-invocation: true the agent never starts it on its own; call it:

  • Claude Code: only the /to-spec command — naming the skill in a message will not start it.
  • Codex: $to-spec.
  • Cursor: type / in the Agent chat and pick to-spec.

Example: /to-spec Write up what we agreed about CSV export as a GitHub issue.

Next in the author's chain: Spec to tickets splits the spec, Implement a spec builds it. Install all three.

How it differs from similar skills

Spec-first kickoff starts from a raw idea, asks up to five questions with defaults and writes a one-page spec with a short plan, saved as SPEC.md if you agree. Spec-driven development also asks and lists assumptions, covers commands, structure, code style and boundaries, and keeps the spec in the repo. To-spec comes later: the questions are behind you, the output is an issue, and the weight is on user stories and test seams. Document co-authoring workflow builds a document with you from the start: numbered questions, options for each section, then a test on a subagent that sees only the text; nothing goes to a tracker.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/to-spec/SKILL.md https://anymodel.org/en/skills/matt-pocock/to-spec/SKILL.md -o ~/.claude/skills/to-spec/LICENSE https://anymodel.org/en/skills/matt-pocock/to-spec/LICENSE -o ~/.claude/skills/to-spec/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/to-spec/agents/openai.yaml
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/to-spec/SKILL.md https://anymodel.org/en/skills/matt-pocock/to-spec/SKILL.md -o ~/.agents/skills/to-spec/LICENSE https://anymodel.org/en/skills/matt-pocock/to-spec/LICENSE -o ~/.agents/skills/to-spec/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/to-spec/agents/openai.yaml
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml') { $p = Join-Path "$HOME\.claude\skills\to-spec" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/to-spec/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml') { $p = Join-Path "$HOME\.agents\skills\to-spec" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/to-spec/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/matt-pocock/to-spec/SKILL.md

SKILL.md

Raw

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

  1. 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.

  2. 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.

  1. 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:

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

<user-story-example>

  1. 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>

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Matt Pocock's skills

Code review against standards and spec

Reviews the diff since a commit, branch or tag on two axes in parallel subagents: the repo's written standards plus a baseline of Fowler code smells, and the originating spec or issue. Use when a branch or PR needs checking against its spec.

Deep module design

Fixes a shared vocabulary for deep modules (interface, seam, adapter, depth, leverage), with the deletion test, dependency categories and a design-it-twice pattern on parallel subagents. Use when designing a module's interface or deciding where a seam goes.

Diagnosing hard bugs

Diagnoses hard bugs and slowdowns by first building a fast, deterministic command that reproduces the exact symptom, then minimising it, ranking falsifiable hypotheses and adding a regression test at a real seam. Use when something fails, throws or got slow.

Domain modeling

Sharpens a project's domain language during design: challenges fuzzy or conflicting terms, writes resolved ones to GLOSSARY.md at once and offers a short ADR only for hard-to-reverse trade-offs. Use when discussing terminology or recording an ADR.

Implement a spec

Implements a spec and its tickets on one integration branch: a fresh implementer subagent per ticket in its own worktree, run in parallel along the blocking graph, then a code review and one fix pass. Use when the tickets from to-tickets are ready.

Improve codebase architecture

Finds shallow modules worth deepening, starting from the code that changes most, shows the candidates in an HTML report with before/after diagrams and grills the chosen one with you. Use when a codebase has grown hard to test or navigate.

Throwaway prototype

Builds throwaway code to answer one design question: a single-file clickable HTML demo for a state model, or several structurally different UI variants on one route switched by a URL param. Use when checking whether logic holds or how a page should look.

Coding session retrospective

Reviews a finished coding session from its logs and proposes changes to the agent's environment: navigation pointers, lint rules, pre-commit and CI checks, reviewer standards, tool use. Use when an agent session went slowly or made avoidable mistakes.

TDD with integration tests

Drives test-first work through public interfaces: agrees the seams to test with the user, runs one red-green cycle per test, mocks only at system boundaries and leaves refactoring to review. Use when building a feature or fixing a bug test-first.

Spec to tickets

Splits a spec, plan or conversation into tracer-bullet tickets, vertical slices that each fit one agent session, with blocking edges, and publishes them as local files or tracker issues. Use when work is too big for one session and needs a task graph.

Issue and PR triage

Triages issues and external PRs on the tracker: gives each a category and a state, checks for existing code and past rejections, reproduces bugs and writes agent briefs for ready work. Use when a maintainer works through incoming issues and PRs.

Wayfinder for huge work

Charts work too big for one agent session as a map issue with child decision tickets on the tracker, then resolves one ticket per session until the route to the goal is clear. Use when a large effort has open questions that block a spec or plan.

Bash wizard for manual steps

Generates an interactive bash script that walks a person through manual steps such as dashboard setup, API keys and CI secrets, opening each URL and saving values to .env and GitHub secrets. Use when setup or a migration needs steps only a human can take.

Git guardrails for Claude Code

Installs a Claude Code PreToolUse hook that stops the usual forms of git push, reset --hard, clean -f, branch -D and checkout or restore of the whole tree, for one project or all, then tests it. Use when you want a safety net against an agent pushing or discarding work on its own.

Migrate tests to shoehorn

Replaces as and as unknown as casts in TypeScript tests with fromPartial and fromAny from @total-typescript/shoehorn, adds the imports and runs the type check. Use when tests fake whole objects or cast partial test data to satisfy the compiler.

Pre-commit hooks setup

Sets up Husky and lint-staged in a Node repo so each commit runs Prettier on staged files, then the typecheck and test scripts, matched to the lockfile, and makes the first commit through the hook. Use when a repo has no commit-time checks.

Grilling a plan

Questions the user about a plan or decision in rounds of numbered questions with recommended answers, looks facts up itself through subagents and stops only when no decision is left assumed. Use when a plan needs stress-testing before work starts.

Teach me a topic

Runs a multi-session course in the current folder: a mission, trusted sources, short HTML lessons with quizzes, reference sheets and learning records that set the next lesson. Use when the user wants to learn a topic over time, not get one answer.

Decision questionnaire

Writes a Markdown questionnaire for someone who holds knowledge the user lacks, after asking only who it goes to and what answers are needed, with the most important questions first. Use when a decision depends on facts from another person.

Writing for agents

Gives the rules for writing text agents read: skill descriptions as context pointers, what to keep inline and what to move to a separate file, completion criteria, leading words and pruning. Use when creating or editing a skill, AGENTS.md or CLAUDE.md.