setup-matt-pocock-skills

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 14 处。

Entry SHA-256: f148858ffb7f63c03c06fca06e6fdb1d91a35c6b293244b8fdfacd5f4cc028c4

2. Why This Skill Is Clever

一句话核心机制

先读取仓库现状，用“推荐默认值 + 只在真正分叉处提问”完成三个配置决策，再经用户预览确认后，以幂等、差量方式写入一组供其他工程 skills 消费的长期契约。

触发与边界

直接来源： frontmatter 的 disable-model-invocation: true 与 “Run once before first use” 把它限定为用户显式触发的一次性初始化 skill；它配置 issue tracker、triage 标签与领域文档布局，不处理具体 issue，也不执行后续工程任务。

直接来源： “This is a prompt-driven skill, not a deterministic script” 明确拒绝把仓库配置压成无条件脚本。探索、展示、确认、写入是硬顺序，用户选择仍然保留在有意义的分叉点。

解读： 它最适合首次接入这套工程 skills，或确实要切换问题跟踪器、重置配置时运行。日常使用不应重复执行；文末明确说普通修改可直接编辑 docs/agents/*.md。

信息架构 / 执行顺序

1. 探索现状。 检查远程仓库、agent 指令文件、术语表、ADR、旧输出、本地 issue 约定、triage 可用性与 monorepo 信号。
2. 按证据裁剪问题。 Issue tracker 总是处理；未安装 triage 就跳过标签问题；没有 monorepo 信号就直接采用 single-context，不制造多余选择。
3. 推荐优先。 每节先给推荐答案，只有执行路径真正分叉时才补一行解释。
4. 先预览再写入。 展示 ## Agent skills 块和三个配置文件草稿，允许用户编辑。
5. 幂等落盘。 复用已有 CLAUDE.md / AGENTS.md，原位更新受管块，只创建跟踪器缺少的标签，并从种子模板生成配置文档。
6. 交代消费方。 完成后说明哪些工程 skills 会读取这些文件，以及何时才需要再次运行。

最巧妙的设计点

1. “Read whatever exists; don't assume” — 把环境探测设为所有决策的前置条件。
   直接来源： 探索清单逐项覆盖远程、指令文件、领域文档、既有输出与仓库形态。
   解读： 配置型 skill 最大的风险不是“不会写”，而是覆盖已有约定；先读现状能把破坏性假设变成可验证事实。

2. “skip the section entirely when exploration already settled it” — 用证据消灭伪选择。
   直接来源： 未安装 triage 时跳过 B 节，没有 monorepo 时跳过 C 节。
   解读： 它不是把每个参数都丢给用户，而是让探索结果直接收缩对话；这同时降低用户负担和配置组合数。

3. “Lead each section with the recommended answer” — 把默认值做成可快速接受的决策界面。
   直接来源： 用户应能 “accept it in a word”，只有真正分叉才需要解释。
   解读： 好的交互式 skill 不是问题清单，而是带依据的建议；用户保留否决权，却不必承担从零设计配置的成本。

4. “Let them edit before writing” — 把可逆预览放在副作用之前。
   直接来源： 第 3 步要求展示指令块和所有配置文件草稿，再进入第 4 步写入。
   解读： 这是一道事务门：把理解偏差暴露在廉价的文本审阅阶段，而不是等文件、标签已经改变后再回滚。

5. “update its contents in-place rather than appending a duplicate” — 为重复运行设计幂等语义。
   直接来源： 已有 ## Agent skills 块必须原位更新，周边用户编辑不可覆盖；CLAUDE.md 与 AGENTS.md 也不能并存式复制。
   解读： skill 明确区分“自己管理的 seam”和“用户拥有的周边内容”，因此既能更新，又不会持续制造重复和漂移。

6. “create each configured label the tracker lacks” — 把外部副作用收敛成差量操作。
   直接来源： 仅在 B 节运行且使用 GitHub/GitLab 时，创建尚缺的标签。
   解读： 先比较再创建避免重复失败，也让自定义标签映射与既有 tracker 共存。此次上游更新补上了这条执行闭环：不只写标签文档，还让真实跟踪器状态与契约一致。

防失败机制与 trade-off

原文明确的不变量： 不猜测仓库现状；每次只处理一个小节和一个回答；已由探索确定的分支不再询问；写入前必须展示草稿；已有 agent 文件优先原位编辑；不可同时新建另一种 agent 文件；已有受管块不得重复追加；只在安装 triage 时写标签配置；只创建跟踪器缺失的标签。

防失败价值： 这些规则分别防止错误平台假设、过度提问、重复配置、覆盖用户编辑、标签命名冲突，以及“文档写了但外部 tracker 没配置”的半完成状态。

权衡与可移植性风险：

• disable-model-invocation、Skill 工具和可用 skills 探测依赖具体 agent harness，迁移时需要重写触发与能力发现。
• gh label create / glab label create 是外部副作用；源文件要求创建缺失标签，但没有明确写出认证失败、权限不足或部分成功后的回滚策略。
• “如果两种指令文件都不存在就询问用户”是必要分叉，因此该 skill 不适合无人值守地直接执行。
• monorepo 识别使用有限信号，非 Node.js 多包仓库可能被判断为 single-context；它是务实默认值，不是完备分类器。
• 种子模板承担具体文件结构，入口 source 只描述选择规则；移植时必须同时带走这些 companion files，但它们不属于本报告展示的选中原文。
• 上游此次把领域术语从 CONTEXT.md 统一为 GLOSSARY.md，说明持久化契约会演进；消费方必须与配置生产方共享同一命名版本。

可迁移原则

1. 配置前先盘点存量。 探测结果应直接参与决策，而不是只做背景信息。
2. 只把真正的分叉交给用户。 能由证据或安全默认值确定的内容，就不要制造问卷。
3. 副作用前提供完整预览。 把确认门放在写文件、建标签、调用外部 API 之前。
4. 明确受管 seam。 原位更新自己拥有的块，保护周边用户内容，并让重复运行保持幂等。
5. 让文档契约与真实系统状态一起闭环。 既写配置，也以差量方式补齐外部资源；两者缺一不可。

今日实践题

如果你要为自己的项目写一个初始化 skill，哪些信息可以通过仓库探索自动确定，哪些选择会真正改变后续执行路径而必须询问用户？请各列两项，并指出写入前要展示哪些草稿。

Evidence note

• 直接来源： 本报告完整展示的 skills/engineering/setup-matt-pocock-skills/SKILL.md，用于所有步骤、约束、默认值与执行顺序。
• 支撑上下文： 源文件链接的 issue-tracker、triage-labels 与 domain 种子模板只用于确认这些文件是配套配置资产；它们没有被冒充为选中原文。
• 解读： 关于不确定性收缩、事务门、幂等 seam、差量副作用与可移植性风险的判断，是基于上述直接证据的工程分析。