Guide · Agent skill
How to use the to-spec agent skill: turn chat into a spec
Updated · written with AI from the project's own documentation and checked against our catalogue data
The to-spec skill is a reusable instruction set for an AI coding agent. When you invoke it, the agent stops asking questions and turns the planning you have already done in the conversation, along with the codebase it has explored, into a formal spec, then publishes that spec to your project's issue tracker. This guide explains what the skill does, how to install it, how to trigger it, and what it needs before it will work.
Turn Chat into a Specmattpocock/skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the to-spec skill ZIP from the page where you found this guide.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. Alternatively, upload it in the Claude apps under Settings → Capabilities → Skills.
- 3Configure your issue tracker. Run /setup-matt-pocock-skills so the issue tracker and triage label vocabulary are available to the agent.
- 4Plan in chat. Discuss the feature with the agent, including the problem, users and trade-offs, before invoking the skill.
- 5Invoke the skill. Ask the agent in natural language to turn the conversation into a spec and publish it to the issue tracker.
- 6Confirm the test seams. When the agent proposes test seams, check they match your expectations before it writes the spec.
- 7Review the published issue. Check the published spec in your tracker and confirm it carries the ready-for-agent label.
What is an agent skill and what does to-spec do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load and follow when a task matches. The to-spec skill covers one specific job: writing a spec from a conversation you have already had.
Normally a planning session ends with decisions scattered across chat messages. With to-spec, the agent does not interview you. It summarises what has been discussed and what it has explored in the codebase into a spec with a fixed structure.
- Problem Statement and Solution, written from the user's perspective
- A long, numbered list of user stories in the form 'As an <actor>, I want a <feature>, so that <benefit>'
- Implementation Decisions, Testing Decisions and Out of Scope sections
- Further Notes for anything else relevant
- Publishes the spec to the project issue tracker and applies the ready-for-agent triage label
Install the to-spec skill (ZIP download or Claude apps)
Download the ZIP for the skill from the page where you found this guide. Unzip it into one of these locations, depending on whether you want the skill available everywhere or only in one project:
- Personal skills folder: ~/.claude/skills/ (available across your projects)
- Project skills folder: .claude/skills/ inside your project (shared with that project only)
- Claude apps: upload the skill under Settings → Capabilities → Skills
Set up your issue tracker before the first run
The skill publishes to a tracker, so the tracker and its triage label vocabulary must already be configured. The skill expects these to be provided. If they are not, it tells you to run /setup-matt-pocock-skills. Run that setup first, then come back to the skill.
Publishing also needs access: the agent must have whatever credentials or CLI/tool permissions it requires to write to your tracker. The source does not specify what these are, so check your own tracker and agent setup.
/setup-matt-pocock-skillsHow to trigger the skill with a natural request
The skill is set to disable automatic model invocation, so it runs when you ask for it explicitly. Finish your planning in the chat first, because the skill works from what is already in the conversation and from the codebase the agent has explored. The skill's own description is the best guide to the kind of request it answers.
- Turn this conversation into a spec and publish it to the issue tracker.
- Write up what we just discussed as a spec and file it with the ready-for-agent label.
- Use to-spec on the feature we planned: no questions, just the spec.
What happens during a run
The agent first explores the repo if it has not already done so, and uses the project's domain glossary vocabulary and respects any ADRs in the area being changed. It then sketches the test seams for the feature, preferring existing seams and the highest seam possible. It asks you to check that these seams match your expectations before writing. After that it writes the spec and publishes it, applying the ready-for-agent label with no further triage.
- Step 1: explore the codebase and read the relevant glossary and ADRs
- Step 2: propose test seams and ask you to confirm them
- Step 3: write the spec and publish it with the ready-for-agent label
Safety notes: scripts and network access
The skill does not run scripts, according to the source files. It does use the network, because it publishes to your issue tracker. Because publishing happens automatically once the spec is written, review what the agent has discussed before you invoke it, and be aware that it writes to a shared tracker.
Do not use it for quick brainstorming where you do not want an issue created.
- No scripts are run by this skill
- Network use is required to publish to the tracker
- Publishing is automatic; a spec may be based on incomplete understanding because the skill does not ask clarifying questions
Tips for better specs
The spec is only as good as the conversation behind it. Spend your planning time in chat on the problem, the users and the trade-offs before invoking the skill, since it will not ask those questions for you. When the proposed test seams come back, check them carefully; the skill favours as few seams as possible.
- Clarify the problem, users and out-of-scope items in chat before invoking the skill
- Confirm the proposed test seams when asked, since the skill waits for your check
- Keep one feature per conversation so the spec stays focused
What people use it for
- Turn a feature planning session into a tracked issue for the team
- Hand off well-defined work to another agent through the ready-for-agent label
- Capture user stories and implementation decisions from a design discussion
- Record out-of-scope items and testing decisions while the context is fresh
Frequently asked questions
Is the to-spec skill free to use?
The source files are published under the MIT licence. The source does not mention prices, so check the licence terms in the repository for details on reuse.
What does the to-spec skill require?
It requires a configured project issue tracker and triage label vocabulary, set up with /setup-matt-pocock-skills. It also needs access credentials or CLI/tool permissions for the agent to publish, which the source does not specify.
How do I install the to-spec skill?
Download the ZIP from the page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does to-spec ask me questions before writing?
No. The skill explicitly does not interview you and instead synthesises what has already been discussed. It does ask you to confirm the proposed test seams before writing the spec.
Why won't to-spec publish my spec?
The most likely cause is a missing tracker configuration. The skill tells the agent to ask you to run /setup-matt-pocock-skills if the issue tracker and triage label vocabulary have not been provided.
How is to-spec different from asking an agent to plan a feature?
A normal planning chat ends without a tracked artefact. to-spec turns the discussion into a fixed-format spec and publishes it to your issue tracker with the ready-for-agent label, but it skips clarifying questions, so the result depends on how complete the discussion was.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use to-spec if you already run a Matt Pocock-style skills setup with a configured issue tracker and want a tracked, structured spec written straight from a planning conversation. Pick something else if your project has no issue tracker, if you want the agent to ask clarifying questions first, or if you only want to brainstorm without publishing anything.
Download the skill