1实现原理 · 为什么它能做到
纯 prompt 编排：skill 全部能力来自给模型的指令文本，目录里只有 SKILL.md 与一个接口声明文件，零脚本零代码。它把「把已讨论内容综合成 spec」这一行为建模成一段受纪律约束的写作流程。
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.
第一句声明输入=会话上下文+代码库理解，第二句是行为约束（禁止访谈）。整份文件都是对模型说话的指令，没有任何可执行代码。
与仓库内工程 skill 家族共享运行时契约：issue tracker 与 triage 词表不内嵌在本 skill，而是由 setup-matt-pocock-skills 一次配置后写入 docs/agents/*.md，to-spec 按需读取。这是它能在 GitHub/GitLab/本地 markdown 之间切换而自身零代码的原因。
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.
setup 的 SKILL.md 明确 to-spec 是 issue tracker 的读写方之一；具体通道（gh issue create / .scratch/ 本地 md / 其他工作流）由用户在 setup 时选定并落盘到 docs/agents/issue-tracker.md。to-spec 自身不假设通道。
发布动作与标签是流程终点：写完模板后发布到 tracker 并打 ready-for-agent 标签，标签字符串经 triage-labels.md 的「角色→实际字符串」映射解析，因此支持用户自定义词表（如 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.
triage-labels.md 种子表把五个规范角色映射到实际 label 串：'When a skill mentions a role ... use the corresponding label string from this table.'——to-spec 提到的 ready-for-agent 即其一。
规格正文有强内容纪律：spec 是设计决策载体而非代码转储，模板明确禁止文件路径/代码片段（防陈旧），只允许原型产出的、比散文更精确的决策片段（状态机/reducer/schema/类型形状）例外内联。
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.
这是该 skill 区别于一般『写文档』skill 的设计要点：spec 面向未来 AFK agent 执行，所以刻意剔除易过时的实现细节。
可测试性前置：流程第 2 步要求在写 spec 前先设计测试接缝（偏好已有接缝、越高越好、全库理想数为 1），且必须与用户核对接缝是否符合预期——把『怎么测』放进规格产出前的人工确认点。
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.
『seams』概念贯穿 spec 的 Testing Decisions 一节（只测外部行为），与测试优先的工程观一致。
2核心能力
01免访谈规格合成：把当前会话直接综合为 spec
02仓库感知：写 spec 前先探索代码库现状，遵循领域词表与 ADR
03测试接缝规划：先定可测边界，偏好最高/最少接缝
04接缝人工确认点：写 spec 前与用户核对接缝
05固定七节规格模板产出（问题/方案/用户故事/实现决策/测试决策/范围外/备注）
06发布到项目 issue tracker 并打 ready-for-agent 标签（免额外 triage）
07反陈旧的内容纪律：spec 不写文件路径/代码片段，原型决策片段例外内联
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | gh (GitHub CLI) |
| cli | glab 或自定义工作流（GitLab/其他 tracker 场景） |
| network | 用户自有的 issue tracker 端点（GitHub 默认：github.com API） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
声明可访问域名与密钥范围
面向管理者
密钥最小权限，保留请求日志
判定依据（文件路径与关键语句摘要）
- 外部服务: 依赖宿主网络工具或外部 API 检索
审计说明： 。纯指令 skill：无脚本、无凭证读取、skill 文件内无网络端点。但其核心行为『发布 spec 到 issue tracker』每次运行都会发生外部状态变更：tracker 为 GitHub（setup 默认）时经官方 gh CLI 走网络写用户自己的仓库，外发对象可预期；tracker 为本地 markdown 时退化为本地写入。仅当用户显式触发时执行（disable-model-invocation + allow_implicit_invocation: false 双保险），不会自发运行。
5第二遍独立确认
- [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
6结论
适合： 适合已跑过 setup-matt-pocock-skills、采用『先规格后实现』的工程团队：开发者与 AI 讨论完方案后，一条命令把讨论固化为规范 spec 并进入 ready-for-agent 队列，供后续 agent 执行；对希望保留『规格即文档、可追溯』工作流、且 issue tracker 成熟的仓库最合适。
不适合： 不适合：无 issue tracker 或不愿先做装配的临时项目；需求尚模糊、需要提问澄清的场景（该 skill 刻意不访谈）；需要产出含具体实现细节/文件路径级规格的团队（模板明确禁止）。
Install Agent-Ready
① Verified Mirror 2026-09-06
Option A · Direct DownloadDownload to-spec.tar.gz
sha256:
Option B · Copy Guide for Agent3a4ea2541cdd9f0b…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 3cca18b368.