全部技能 / 基础工具与工作流 / to-spec
基础工具与工作流 · 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.

风险提醒：黄色 · 留意使用AI 侦查报告
作者 mattpocockGitHub mattpocock/skills ↗Stars 253957许可 MITcommit 3cca18b368
agent 宿主通常会约束 skill 执行权限；风险提醒为 AI 侦查观点，不构成质量或安全保证。第三方 skill 仅作拆解与展示，安装使用风险自负，版权归原作者。

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外部依赖

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

4风险提醒 风险提醒：黄色 · 留意使用

风险提醒：黄色 · 留意使用
  • 脱离装配即失效 — 未跑过 setup-matt-pocock-skills（无 docs/agents/issue-tracker.md / triage-labels.md）时，skill 只能提示用户去配置，无法完成发布——依赖链断裂行为是『报错指引』而非降级可用
  • 发布副作用在用户仓库可见 — 每次运行都会在 tracker 创建 issue（含标签、标题、正文），一旦会话被注入误导内容，会留下用户可见的垃圾/误导 issue；无 dry-run 或草稿模式设计
  • 输出质量依赖会话本身 — 综合质量上限=已讨论内容质量：若此前对话含糊或含误解，spec 会忠实放大，模板无法纠偏；唯一校验点是接缝确认，不覆盖需求语义确认（设计如此：免访谈）
  • 词表漂移风险 — triage 词表与通道在 setup 时固化到 docs/agents/*.md，仓库与工具链演化后若未重跑 setup，发布动作可能打到过期通道
风险提醒：黄色，留意使用。纯指令 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 skill 落盘 docs/agents/*.md）实现多 tracker 适配，避免每仓库硬编码
  • 内容纪律防陈旧：spec 禁文件路径/代码片段，直接提升规格对后续 AFK agent 的可用寿命
  • 测试思考前置且有人工确认点，产出可直接进入 ready-for-agent 队列的规格
    • 适合：适合已跑过 setup-matt-pocock-skills、采用『先规格后实现』的工程团队：开发者与 AI 讨论完方案后，一条命令把讨论固化为规范 spec 并进入 ready-for-agent 队列，供后续 agent 执行；对希望保留『规格即文档、可追溯』工作流、且 issue tracker 成熟的仓库最合适。
    不适合：不适合：无 issue tracker 或不愿先做装配的临时项目；需求尚模糊、需要提问澄清的场景（该 skill 刻意不访谈）；需要产出含具体实现细节/文件路径级规格的团队（模板明确禁止）。
    安装 agent 直装可复制
    ① 本站镜像 更新 2026-09-06
    方式 A · 人下载镜像包下载 to-spec.tar.gz
    sha256: 3a4ea2541cdd9f0b…
    方式 B · JSON 格式安装指南，复制给 agent
    安装指南
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② 上游 GitHub · 原始来源
    能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗
    本页镜像锁定 commit 3cca18b368；上游为实时仓库。
    来源信息 GitHub 原始
    作者 / 仓库mattpocock / mattpocock/skills
    原始 GitHubmattpocock/skills ↗
    Stars253957
    最近推送2026-09-04
    本 skill commit3cca18b368
    许可MIT
    本站信息
    收录日期2026-09-06
    分类基础工具与工作流
    侦查报告2026-09-06 · 2 遍
    本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。