Home / All Skills / Workflow & Core Tools / to-spec
English (EN)简体中文 (ZH)日本語 (JA)
Workflow & Core Tools · mattpocock/skills

to-spec

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.

L3 Networked · Declare domain & key scopeV1 Commit-PinnedNetwork AccessDual-pass Audit
Author mattpocockGitHub mattpocock/skills ↗Stars 253957License MITCommit 3cca18b368
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Pure prompt orchestration: All capabilities of the skill come entirely from instruction text given to the model. The directory contains only SKILL.md and an interface declaration file, with zero scripts and zero code. It models the behavior of 'synthesizing discussed content into a spec' into a disciplined writing workflow.

skills/engineering/to-spec/SKILL.md
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 first sentence declares input = session context + codebase comprehension, and the second sentence defines behavioral constraints (no interviewing). The entire file consists of instructions addressed to the model, without any executable code.

Shared runtime contract with in-repo engineering skill families: Issue tracker and triage vocabularies are not embedded within this skill. Instead, they are configured once via setup-matt-pocock-skills and persisted into docs/agents/*.md, which to-spec reads on demand. This enables switching across GitHub, GitLab, and local markdown with zero code inside the skill itself.

skills/engineering/setup-matt-pocock-skills/SKILL.md
Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it. They need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe.
The SKILL.md of setup explicitly designates to-spec as a reader/writer of the issue tracker; the concrete channel (gh issue create, .scratch/ local md, or other workflows) is chosen by the user during setup and written to docs/agents/issue-tracker.md. to-spec makes no assumptions about the channel.

Publishing action and labeling mark the end of the pipeline: After populating the template, it publishes to the tracker and applies the ready-for-agent label. Label strings are resolved via the 'role -> concrete string' mapping in triage-labels.md, supporting custom user vocabularies (such as bug:triage).

skills/engineering/to-spec/SKILL.md
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.
The triage-labels.md seed table maps five canonical roles to concrete label strings: 'When a skill mentions a role ... use the corresponding label string from this table.'—ready-for-agent referenced by to-spec is one of them.

Strict content discipline for the spec body: The spec serves as a vehicle for design decisions rather than a code dump. The template explicitly forbids file paths and code snippets (to prevent staleness), allowing inline inclusions only as an exception for prototype-derived decision fragments that are more precise than prose (state machines, reducers, schemas, type shapes).

skills/engineering/to-spec/SKILL.md
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.
This is a key design distinction from generic 'doc-writing' skills: specs target future AFK agent execution, deliberately pruning fragile, quickly outdated implementation details.

Front-loaded testability: Step 2 of the workflow requires designing test seams before authoring the spec (favoring existing seams, as high up as possible, ideally 1 for the whole repo) and explicitly confirming with the user whether the seam matches expectations—turning 'how to test' into a human confirmation gate before spec generation.

skills/engineering/to-spec/SKILL.md
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.
The 'seams' concept runs throughout the Testing Decisions section of the spec (testing only external behavior), consistent with a test-first engineering philosophy.

2Core Capabilities

01Interview-free spec synthesis: directly synthesize the current conversation into a spec
02Codebase-aware: inspect current repository state before writing the spec, adhering to domain vocabulary and ADRs
03Test seam planning: define testable boundaries upfront, favoring the highest and fewest seams
04Human confirmation gate for seams: verify test seams with the user prior to writing the spec
05Fixed 7-section spec template generation (Problem, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Notes)
06Publish to project issue tracker with the ready-for-agent label applied (eliminating extra triage)
07Staleness-resistant content discipline: omit file paths and code snippets in specs, inlining only prototype decision fragments as exceptions

3External Dependencies

KindDependency / Endpoint
cligh (GitHub CLI)
cliglab 或自定义工作流（GitLab/其他 tracker 场景）
network用户自有的 issue tracker 端点（GitHub 默认：github.com API）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Declare allowed domains and key scope
For Administrators
Least privilege keys, retain request logs
Evidence & Triggers (File Paths & Excerpts)
  • 外部服务: Relies on host network tools or external API retrieval
Audit Notes: Purely instruction-based skill: contains no scripts, no credential access, and no network endpoints within the skill files. However, its core behavior—publishing the spec to an issue tracker—causes an external state mutation on each run: when the tracker is GitHub (setup default), it accesses the network via the official gh CLI to write to the user's repository with predictable destinations; when the tracker is local markdown, it degrades to local writes. It only executes when explicitly triggered by the user (double-guarded by disable-model-invocation and allow_implicit_invocation: false) and will not run autonomously.

5Second-Pass Verification

  • [ok] 文件清单：skills/engineering/to-spec/ 恰为 SKILL.md + agents/openai.yaml 两文件，无隐藏脚本 — gh api 递归树确认；本地工作树 engineering/to-spec/ 同构（本地为 skills/ 子目录内容平铺）
  • [ok] 外部依赖 gh CLI：to-spec 自身不含调用 — to-spec 两文件全文重读，确实零 gh/命令引用；gh 命令只存在于 setup 的 issue-tracker-github.md 种子与 setup 流程产出的 docs/agents/issue-tracker.md——引用关系真实存在（setup SKILL.md: 'Skills like to-tickets, triage, and to-spec read from and write to it'）
  • [ok] ready-for-agent 标签与词表映射 — triage-labels.md 五行词表中 ready-for-agent 存在，映射语义='Fully specified, ready for an AFK agent'，与 to-spec『spec 发布后免额外 triage』自洽
  • [ok] 触发限制声明 — SKILL.md frontmatter disable-model-invocation: true 与 openai.yaml allow_implicit_invocation: false 两份文件均实读确认
  • [ok] 功能声明 vs 实际能力相符性 — 描述称『publish to the project issue tracker』，实际靠 setup 预置文档提供通道，流程第 1 行也明说词表应已提供、缺失则叫用户跑 /setup-matt-pocock-skills——有条件前提但如实声明，无夸大
  • [ok] 网络端点/凭据读取反例搜索 — 两文件内无 URL、无 env/keychain 读取、无文件写入指令；唯一外发是经宿主 CLI 到用户自有 tracker
  • [ok] LICENSE/元数据 — gh api: license MIT（仓库根 LICENSE）、stars 253957（2026-09-06 实时快照值）、pushed_at 2026-09-04T08:45:43Z

6Verdict & Scenarios

  • Ultra-thin interface and single responsibility: models 'conversation -> spec -> publish' as a pure instruction workflow, eliminating code and maintenance overhead
  • Multi-tracker adaptation via shared scaffolding (setup skill writes docs/agents/*.md), avoiding per-repo hardcoding
  • Staleness prevention via content discipline: banning file paths/code snippets directly extends the usable shelf life of specs for subsequent AFK agents
  • Front-loaded testing considerations with human confirmation gates, producing specs immediately ready for the ready-for-agent queue
    • Best for: Ideal for engineering teams that have completed setup-matt-pocock-skills and follow a 'spec-before-implementation' methodology: after developers discuss a solution with AI, a single command turns the discussion into a standard spec and queues it under ready-for-agent for subsequent agent execution. Best suited for repos with mature issue trackers seeking a 'spec as documentation, traceable' workflow.
    Not for: Not suitable for: ad-hoc projects without an issue tracker or unwilling to complete initial setup; scenarios where requirements remain ambiguous and require clarifying questions (this skill deliberately avoids interviewing); teams requiring specs with concrete implementation details or file-path-level instructions (explicitly forbidden by the template).
    Install Agent-Ready
    ① Verified Mirror 2026-09-06
    Option A · Direct DownloadDownload to-spec.tar.gz
    sha256: 3a4ea2541cdd9f0b…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 3cca18b368.