← Explore all skills

PLANNING AND DELIVERY / Matt Pocock

Conversation to Specification

Turns an already-discussed change into a repository-aware specification for the configured issue tracker.

“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.”

01 / THE REASONING

Why this made the selection.

  • Uses existing project context, glossary and architecture decisions before synthesizing requirements.
  • Makes scope exclusions, implementation boundaries and test seams explicit instead of treating a discussion transcript as a specification.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • skills/engineering/to-spec/SKILL.md
  • README.md (installation and setup sections; the README has no licence section)
  • LICENSE (MIT, copyright 2026 Matt Pocock)
  • skills/engineering/to-spec/agents/openai.yaml
  • skills/engineering/setup-matt-pocock-skills/SKILL.md
  • skills/engineering/setup-matt-pocock-skills/agents/openai.yaml
  • skills/engineering/setup-matt-pocock-skills/domain.md
  • skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
  • skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
  • skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
  • skills/engineering/setup-matt-pocock-skills/triage-labels.md

Our findings

  • The entry disables implicit invocation and has a matching Codex invocation policy.
  • The setup companion supports GitHub, GitLab and local Markdown; the full companion and its tracker/domain templates were read.
  • Before writing, the agent sketches the test seams, prefers existing seams and the highest one ('the ideal number is one'), and checks them with the user. It then publishes the spec and applies the ready-for-agent label without further triage.
  • The spec template runs from Problem Statement to Further Notes, asks for an extensive numbered list of user stories, and bars file paths and code snippets except a decision-encoding snippet from a prototype.
  • Re-pinned from c55ee46073ed923f86ce59a5eb3b6d895095d1b7 to 49dd158d1076134a641b33efb035946536778336: to-spec/SKILL.md and agents/openai.yaml are unchanged. The setup companion now names GLOSSARY.md instead of CONTEXT.md. At this revision the setup companion also creates any configured triage label the GitHub or GitLab tracker lacks (gh label create / glab label create), when the triage skill is installed.

Not established by this review

  • No upstream definition, helper, installer or generated workload was executed.
  • No end-to-end agent session or effectiveness benchmark was run.
  • Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Add a skill to your workflow.

Upstream setup instructions ↗

DOCUMENTED COMMAND

npx skills add mattpocock/skills --skill to-spec --skill setup-matt-pocock-skills

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

Optional: install the reviewed revision

Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.

npx skills add https://github.com/mattpocock/skills/tree/49dd158d1076134a641b33efb035946536778336 --skill to-spec --skill setup-matt-pocock-skills
  1. Install the complete skill directory, including its references and helpers; select your AI tools and project or global scope.
  2. Run the setup companion once. Inspect its proposed edits to AGENTS.md or CLAUDE.md and docs/agents/ before accepting; it configures GitHub, GitLab or local Markdown tracking. At this revision the setup companion also creates any configured triage label the GitHub or GitLab tracker lacks (gh label create / glab label create), when the triage skill is installed.
  3. Review the instructions before invoking them. The source revision shown here is the one reviewed; the installer was not executed or version-pinned by this review.
  4. For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/mattpocock-to-spec/bundle.zip and extract it into a new directory. It holds SKILL.md and agents/openai.yaml unchanged at revision 49dd158d, the upstream licence and an attribution file.
  5. Place the extracted directory in your host's documented skills directory, named to-spec. Keep SKILL.md and the licence together.

Before you start

  • Node.js/npm and git for the documented Skills installer
  • An agent host that supports the skill format and the tools required by the workflow
  • Configured tracker access: authenticated gh or glab for remote issues, or a writable local Markdown directory

THE COMPLETE REVIEWED DEFINITION

Read it before you reuse it.

Original source bytes, with attribution.
Review the host-specific setup notes above.

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

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.

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

The download contains SKILL.md. Extract the whole bundle; the supporting files are required. Inspect the included MANIFEST.json for file hashes.

By Matt Pocock. Exact upstream source ↗ · Licence · Attribution

SHA-256 43ad9cf318e5e7d3d1fa360253a37021796dc87a0c2e595ad262661a10f85088

Read the applicable licence
MIT License

Copyright (c) 2026 Matt Pocock

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md

    Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access

  2. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/README.md

    Supports: install, compatibility

  3. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/LICENSE

    Supports: license, access.cost

  4. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/agents/openai.yaml

    Supports: review

  5. https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md

    Supports: install

  6. https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts

    Supports: install

  7. https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/source-parser.ts

    Supports: install

  8. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/SKILL.md

    Supports: review, limitations, install, access

  9. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/agents/openai.yaml

    Supports: review

  10. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/domain.md

    Supports: review, limitations, install, access

  11. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md

    Supports: review, limitations, install, access

  12. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md

    Supports: review, limitations, install, access

  13. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md

    Supports: review, limitations, install, access

  14. https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/triage-labels.md

    Supports: review, limitations, install, access

  15. https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md

    Supports: bestFor, review

  16. https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/README.md

    Supports: limitations

Evidence & Ask