New to Claude Skills? Learn how to install them →

Get Claude Skills
mattpocock on GitHub

To Spec

Free

Generate project specs from conversation context.

by mattpocock212.7k stars on mattpocock/skills
Updated Aug 6, 2026
Get this skill

Free · Opens the source repo

What To Spec does

To Spec is a skill designed for developers and project managers who need to transform ongoing discussions into actionable specifications without the need for additional interviews. By synthesizing the context of the current conversation and the existing understanding of the codebase, this skill streamlines the process of documenting project requirements. This is particularly useful in agile environments where clarity and speed are paramount.

The skill operates by first exploring the repository to grasp the current state of the codebase. It utilizes the project's domain vocabulary and adheres to any architectural decision records (ADRs) relevant to the feature being discussed. This ensures that the generated specifications are not only relevant but also maintain consistency with the project's standards.

Once the context is established, To Spec sketches out the seams at which the new feature will be tested, preferring existing seams to minimize disruption. It then composes a detailed specification using a structured template that includes problem statements, solutions, user stories, implementation decisions, testing strategies, and notes on scope. The final spec is published directly to the project issue tracker with the appropriate triage label, streamlining the workflow and reducing overhead.

This skill is ideal for teams looking to enhance their documentation processes and improve communication efficiency. By automating the synthesis of discussions into formal specifications, developers can focus more on coding and less on administrative tasks.

When to use it

Use this skill when you have ongoing discussions about a feature and need to quickly document the specifications without additional interviews.

When not to use it

This skill may not be suitable for projects where detailed user feedback is essential for specification or where the conversation context is insufficient to create a comprehensive spec.

What you can build with it

Documenting Feature Requests

When a team discusses new feature requests, To Spec can quickly generate a spec that captures all discussed points.

Streamlining Agile Sprints

During sprint planning, this skill helps convert team discussions into actionable specifications, enabling faster development cycles.

Clarifying User Stories

If user stories are discussed but not documented, To Spec synthesizes those conversations into a structured format for easy reference.

How to install To Spec

View source

1. Install with the skills CLI

npx skills add mattpocock/skills/to-spec --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by mattpocock

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 — run /setup-matt-pocock-skills if not.

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>

Frequently asked questions about To Spec

Similar skills

Markdown to HTML Conversion

Efficiently convert Markdown documents to HTML.

Code Tour

Create structured walkthroughs for codebases.

Acquire Codebase Knowledge

Streamline onboarding with comprehensive codebase documentation.

Documentation & Modernization

Streamline codebase documentation and modernization planning.

Azure Resource Visualizer

Generate architecture diagrams for Azure resources.

CLAUDE.md Improver

Optimize your CLAUDE.md files for better project context.