mattpocock skills README 摘要
文档概览
这份 README 把 mattpocock/skills 描述为作者“每天都会使用的 agent skills”，目标是做“真实工程”，而不是只做气氛式编码。文档强调，这套 skills 不是试图完全接管开发流程，而是用一组较小、容易调整、可互相组合的技能，来修复 Claude Code、Codex 等 coding agents 的常见失败模式。
文档原意是：很多方法论试图通过“拥有整个流程”来帮你，但代价是拿走控制权，而且流程本身一旦出 bug 很难修；这套 skills 则更轻量，强调可组合与可定制。
README 先给出一个“30 秒安装”流程，然后用四类典型问题解释这些 skills 为什么存在：
- 代理没有做出用户真正想要的东西
- 代理太冗长
- 代码能写出来但不工作
- 最终把系统做成一团泥球（ball of mud）
在最后的 Reference 中，文档给出完整的技能目录，并用一条明确规则把技能分成 User-invoked skills 与 model-invoked 两类。
快速开始
README 给出的安装与初始化过程分为 4 步：
- 运行安装命令：
npx skills@latest add mattpocock/skills - 选择想安装的 skills，以及要安装到哪些 coding agents 上；README 特别强调务必选择
/setup-matt-pocock-skills - 在 agent 中运行
/setup-matt-pocock-skills - 完成后即可开始使用
其中 /setup-matt-pocock-skills 的初始化职责在 README 中写得很具体，会继续追问三类配置：
- 你想使用哪个 issue tracker：GitHub、Linear，或本地文件
- 你在分诊（
/triage）时会给 tickets 打什么 labels - 之后创建的文档要保存到哪里
这些细节说明，这个仓库的 skills 不只是孤立命令，而是会在仓库层面建立约定，例如 issue tracker、triage label 和文档落盘位置。
这些 skills 试图修复的失败模式
README 用四个问题解释设计动机。
1. 代理没做出我想要的东西
文档认为最常见的失败模式是 misalignment（不对齐）。你以为开发者或代理理解了需求，但最后产出的东西并不是你真正想要的。README 认为这在 AI 时代仍然成立，本质上是用户与 agent 之间存在沟通鸿沟。
对应修复方式是进行一场 grilling session：让代理针对要做的事情持续提出细致问题，直到关键分支被澄清。README 在这里推荐两个 skills：
- grill-me：用于非代码场景
grill-with-docs：和grill-me类似，但额外带文档与领域建模能力
README 还明确给出操作建议：每次要做改动时都应该使用它们，目的是在真正开始之前，先把人与代理的理解对齐。
2. 代理太冗长
README 把“代理过于冗长”单独列为一个需要修复的问题。它指出，在项目初期，开发者与领域专家通常并不说同一种语言；代理被直接扔进项目后，也只能边做边猜术语，于是“本来 1 个词能说清的事情，它会用 20 个词来说”。
文档提出的修复方式是建立 共享语言，也就是一份帮助 agent 解码项目内部术语的文档。README 用 CONTEXT.md 的例子说明这种共享语言如何把长描述压缩成团队内部的精确术语。
README 对共享语言给出几个额外收益：
- 变量、函数、文件名会更一致
- 代码库更容易导航
- 代理在思考时会花更少 token，因为它能使用更精炼的语言
这套能力被整合进 grill-with-docs。README 说它不只是 grilling，还会帮助你建立 domain model，并把难解释的决策写入 ADR。就本页必须覆盖的事实而言，README 明确把这类设计提出为修复代理“过于冗长”的办法。
3. 代码写出来但不工作
README 认为，如果需求已经对齐，代理仍然产出糟糕代码，通常应该回头检查反馈回路。没有运行期反馈、类型反馈和测试反馈时，代理就像“蒙着眼睛飞”。
文档提出的反馈回路包括：
- 静态类型
- 浏览器访问能力
- 自动化测试
其中测试部分特别强调 red-green-refactor 循环，因此 README 推荐 tdd skill，并说明它鼓励代理先写失败测试、再修复测试，以更稳定地获得反馈。
此外，README 还给出一个诊断难 bug 的 skill：diagnosing-bugs，把最佳调试实践包装成一个简单循环。
4. 我们把系统做成了一团泥球
README 指出，agents 能显著加速编码，但也会同时加速软件熵增，让代码库以前所未有的速度变复杂、变难改。
文档给出的修复方式不是继续堆流程，而是“认真对待代码设计”。README 说这种设计关注被内建到所有这些 skills 的各层里，例如：
to-spec会在创建 spec 前追问你改动涉及哪些模块improve-codebase-architecture会帮助你挽救已经变成 ball of mud 的代码库
README 对后者还给出使用频率建议：建议每隔几天就在代码库上跑一次。
关键事实：Reference 中的调用模型
README 的一个核心部分是对技能调用权限的明确划分。它说这些 skills 是“沿着一个轴拆分”的，这个轴就是：谁可以调用它们。
User-invoked skills 的定义
README 明确指出：User-invoked skills 只有在你输入它们时才能触达，例如 /grill-me。
这不是宽泛的建议，而是访问条件：只有用户显式输入时，user-invoked skill 才会进入可达状态。
README 还明确给出这类 skill 的职责：它们的工作是 orchestrate（编排）。也就是说，这类技能主要负责组织流程、路由任务、把步骤串起来，而不是承载底层可复用纪律本身。
Model-invoked skills 的定义
README 进一步说明：Model-invoked skills 既可以被用户调用，也可以在任务匹配时被代理自动触达。文档把它们描述为承载可复用 discipline 的地方。
这意味着 README 中的两类技能并不是按主题划分，而是按“触发权限 + 责任边界”划分：
- user-invoked：显式入口、负责编排
- model-invoked：可复用执行单元、可由模型自动选择
调用约束
README 对两类技能之间的调用关系给出一条很硬的规则：
- user-invoked skill 可以调用 model-invoked skills
- user-invoked skill 不能调用另一个 user-invoked skill
这条规则是本页必须保留的重要边界条件。它限制了编排层之间互相套娃，确保用户入口之间不会形成彼此调用的复杂网状结构。
Productivity 分类
README 在 Reference 中列出一个明确分类：Productivity。
该分类的标题就是 Productivity，描述原文为：General workflow tools, not code-specific。也就是“通用工作流工具，而不是特定于代码的工具”。
README 还明确说明，这个分类与 Engineering 一样，继续分为 User-invoked 与 Model-invoked 两组。这说明它并不是一组平铺命令清单，而是同样遵守“谁可以调用”的总规则。
Productivity 下的 User-invoked
README 在 Productivity 分类下列出的 user-invoked skills 包括：
- grill-me：围绕计划或设计持续发问，直到决策树的每个分支都被解决
handoff：把当前对话压缩成一个 handoff 文档，以便另一个 agent 接手teach：跨多个 session 教用户掌握新技能或概念，并把当前目录作为有状态教学工作区writing-great-skills：撰写与编辑 skills 的参考，强调让 skill 可预测的词汇与原则
其中 grill-me 既是 README 前文高频推荐的入口，也是 Reference 中明确举的例子，用来说明 user-invoked skills 只能在用户输入时触达。
Productivity 下的 Model-invoked
README 在 Productivity 分类下列出的 model-invoked skill 是：
grilling：围绕计划或设计持续采访用户，直到决策树每个分支都被解决；它被明确描述为grill-me和grill-with-docs背后的可复用循环
这恰好体现了 README 的分层思路：
grill-me是用户入口，属于 orchestrate 层grilling是可复用的底层 discipline，属于 model-invoked 层
重要细节
编排层与可复用层的职责拆分
README 没有把所有 skill 都设计成一个级别。它刻意把“入口技能”和“复用技能”拆开：用户输入某个入口型命令后，由入口负责组织流程，再去触发更底层的 model-invoked skills。
这也是为什么 README 要强调 user-invoked 的职责是 orchestrate，而真正可复用的方法论沉淀在 model-invoked skills 里。
grill-me 与 grilling 的关系
结合 README 前后文，可以看出 grill-me 不是“提问循环本身”，而是一个用户可见入口；真正可复用的 relentless interview loop 是 grilling。这也解释了为什么 README 会在 Productivity 分类中同时保留两者。
与工程技能的衔接
虽然本页重点是 Productivity 和调用模型，但 README 其实把这套系统串成了完整工程路径：
- 用
grill-me或grill-with-docs做前期对齐 - 用共享语言减少冗长并改善命名、导航与 token 使用
- 用 tdd 做 red-green-refactor
- 在实现后用 code-review 做双轴审查
- 当系统腐化时用
improve-codebase-architecture做结构恢复
implement 这个 engineering user-invoked skill 的描述尤其能体现这种串联：它会围绕 spec 或 tickets 实施工作，在预先约定的接缝处驱动 /tdd，并在提交前用 /code-review 收尾。