How do I install the To Spec skill?

Run npx skillmds@latest add blockscout/to-spec in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is To Spec safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with To Spec?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is To Spec free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published To Spec?

blockscout (@blockscout) published this skill. Their other Agent Skills are listed on their SkillMD profile.

To Spec by blockscout — Agent Skill

Name: To Spec
Author: blockscout

File contents

To spec

Turn the finished conversation into a task's spec.md and questions.md. Synthesize what the conversation already settled; do not interview — the decisions and the open questions were made in the session that hands off here. This skill's whole job is writing them down and bootstrapping the draft PR.

This skill runs once per task. The spec is write-once: there is no update or merge mode. What that means, and why answers never rewrite it, is in ../../tasks/concepts.md. Not every task gets a spec — see "Not every task needs a spec" in ../../tasks/README.md.

Step 1 — Write the spec and questions

Derive the task folder from the issue: .agents/tasks/<issue-number>-<slug>/ (layout in ../../tasks/structure.md). Write two files:

spec.md from spec-template.md.
questions.md from questions-template.md.

Keep the spec an index of decisions, not a worklog — what to build and why, pointing at detail (its Slack thread, the code, the PR) rather than copying it. Show the user the two files and get their confirmation of the content — this is the run's one gate.

Step 2 — Branch and draft PR

The content confirmation in Step 1 is the only prompt. Once it's given, run this sequence without asking again — it authorizes the branch, commit, push, and draft PR together:

Branch — issue-<number> off main. Create/switch if needed and record it in the spec header.
Commit — commit spec.md and questions.md as the branch's first commit.
Draft PR — hand off to the create-pr skill (draft-placeholder mode, feature branch → main); it pushes and opens the draft with no further confirmation. Why the draft opens this early is in ../../tasks/README.md.

---name: to-specdescription: Turn the current conversation into a product-task spec and publish it as a draft PR: no interview, just synthesis of what you've already discussed.---# To specTurn the finished conversation into a task's `spec.md` and `questions.md`. **Synthesize what theconversation already settled; do not interview** — the decisions and the open questions were made in thesession that hands off here. This skill's whole job is writing them down and bootstrappingthe draft PR.This skill runs **once** per task. The spec is write-once: there is no update or merge mode. What thatmeans, and why answers never rewrite it, is in [`../../tasks/concepts.md`](../../tasks/concepts.md). Notevery task gets a spec — see "Not every task needs a spec" in[`../../tasks/README.md`](../../tasks/README.md).## Step 1 — Write the spec and questionsDerive the task folder from the issue: `.agents/tasks/<issue-number>-<slug>/` (layout in[`../../tasks/structure.md`](../../tasks/structure.md)). Write two files:- **`spec.md`** from [`spec-template.md`](spec-template.md).- **`questions.md`** from [`questions-template.md`](questions-template.md).Keep the spec an **index of decisions**, not a worklog — what to build and why, pointing at detail (itsSlack thread, the code, the PR) rather than copying it. **Show the user the two files and get theirconfirmation of the content — this is the run's one gate.**## Step 2 — Branch and draft PRThe content confirmation in Step 1 is the only prompt. Once it's given, run this sequence **without askingagain** — it authorizes the branch, commit, push, and draft PR together:1. **Branch** — `issue-<number>` off `main`. Create/switch if needed and record it in the spec header.2. **Commit** — commit `spec.md` and `questions.md` as the branch's first commit.3. **Draft PR** — hand off to the `create-pr` skill (draft-placeholder mode, feature branch → `main`); it pushes and opens the draft with no further confirmation. Why the draft opens this early is in [`../../tasks/README.md`](../../tasks/README.md).

Frequently asked questions

To Spec