之前写过 Superpowers 的使用思考。最近通读了 Matt Pocock（Total TypeScript 作者）的 agent-skills，副标题为「Skills For Real Engineers」。本文记录其设计、代价和适用场景。
仓库结构与定位
agent-skills 是一组面向 Claude Code、Codex 等编程 agent 的 skill 集合，目前包含 20 多个技能。正式发布的目录包括 engineering/（日常代码工作）和 productivity/（非代码工作流）；misc/、personal/、in-progress/、deprecated/ 不随插件发布。
GSD、BMAD、Spec-Kit 等框架定义了自己的阶段和下一步操作。agent-skills 将工作拆分为小型 skill，每个 skill 处理一个具体问题，通过少量明确的调用关系协作，使用者决定采用哪些环节。README 的解释是，流程框架会将流程自身的缺陷纳入排查范围；独立 skill 可以单独阅读、修改和替换。
README 列出的四类问题
仓库 README 将 AI 编程中反复出现的问题分为四类，每类对应一组 skill。
-
Agent 对需求的理解与使用者预期不一致。
grilling要求 agent 逐个提问，每个问题附带推荐答案，覆盖决策树的分支；双方确认理解后再开始实现。对应/grill-me和/grill-with-docs。 -
Agent 重复解释项目中的领域概念。项目有自己的术语，agent 进入项目后需要重新推测其含义。
CONTEXT.md用于记录领域术语，例如将「课程里某一课被物化到文件系统」定义为「materialization cascade」；重要决策记录为 ADR。/grill-with-docs和domain-modeling包含这套维护方式。统一术语会影响命名、代码导航和 token 消耗。 -
产出的代码无法运行。需求对齐后仍可能产生错误代码，常见原因是缺少类型检查、浏览器访问或自动化测试等反馈。
/tdd规定红绿循环，并限制测试只能写在预先与用户确认的 seam 上；/diagnosing-bugs提供复现、最小化、假设、插桩、修复和回归测试的诊断步骤。 -
模块边界持续恶化。agent 会增加代码产出，也会增加软件复杂度。
/to-spec在生成规格前询问涉及的模块；/improve-codebase-architecture定期扫描代码库，寻找「深模块」机会，即以小型公开接口承载较多行为，生成可视化报告，使用者选择方向后再通过 grill 讨论。
这些问题对应的参考书包括《The Pragmatic Programmer》（问题 1 和 3）、《Domain-Driven Design》（问题 2）、《Extreme Programming Explained》和《A Philosophy of Software Design》（问题 4）。仓库将需求对齐、命名、反馈回路和模块设计写成可重复执行的 prompt；模型能力变化不改变这些工程活动的必要性。
Skill 的调用分层
仓库将 skill 分为 user-invoked 和 model-invoked 两类。
- user-invoked 技能带有
disable-model-invocation: true，只能由用户输入斜杠命令触发，主要负责流程编排，例如/implement、/to-spec。其 description 不进入 agent 的每轮上下文，使用者需要自行选择并触发。 - model-invoked 技能保留面向模型的 description，agent 可根据任务自动调用，用于承载可复用的工程步骤，例如
tdd、diagnosing-bugs、research。
user-invoked 技能可以调用 model-invoked 技能，例如 /implement 内部驱动 /tdd；user-invoked 技能之间不互相调用。仓库通过 router skill 处理技能较多时的选择问题：/ask-matt 根据使用者描述的处境推荐 skill。
writing-great-skills 说明了该分层的设计依据：skill 需要使 agent 稳定执行相同的过程，具体结果仍由任务决定。文档还规定，description 的每个触发分支只写一次，步骤需要有可检查的完成标准，参考资料按信息层级放入外部文件并按需加载。这些规则可用于编写其他 skill。
从需求讨论到提交的流程
一次典型改动的串联方式如下图所示：
/setup-matt-pocock-skills 每个仓库执行一次，用于选择 issue tracker（GitHub、GitLab、Linear 或本地 markdown 文件）、triage 标签和文档位置，并将配置写入 docs/agents/。后续流程包括：/grill-with-docs 对齐需求并维护 CONTEXT.md 和 ADR；/to-spec 将已讨论的内容写为规格并发布到 issue tracker；/to-tickets 将规格拆为 tracer-bullet 票据并声明阻塞关系；/implement 按票据实现并在约定的 seam 上驱动 /tdd；/code-review 按 Standards 和 Spec 两个维度各启动一个并行子代理审查 diff，之后提交。
另外几个入口处理特定任务：/wayfinder 面向单个会话无法容纳的大型工程，将决策过程表示为 issue tracker 中的 decision ticket 地图，每张票据处理一个决策；/triage 通过标签状态机推进 issue；/handoff 将当前会话压缩为供下一个 agent 使用的交接文档。
插件与文件拷贝两种分发方式
Claude Code 官方插件市场中的 mattpocock-skills 为订阅式安装：文件只读，随作者发布自动更新。npx skills add mattpocock/skills 则将 skill 文件复制到仓库中，使用者可以修改；需要更新时执行 npx skills update。
仓库 ADR（.agents/adr/0002）解释了 Codex 原生插件推迟发布的原因。Claude Code 的插件清单可以逐个列出 skill 目录，因此只发布正式目录。Codex 的清单只接受单个路径并递归发现文件，无法同时指向 engineering/ 和 productivity/，也不能排除 deprecated/ 等目录；符号链接在安装时会丢失。ADR 将这一分发限制和决策依据保存在仓库内。
使用该仓库可获得什么
- 四类问题各有对应的 skill：需求对齐、术语管理、反馈回路和模块设计可以分别处理，使用时可明确当前处理的问题。
- 每个 skill 由一个 SKILL.md 文件和少量附属文档组成，不包含代码或运行时。
grilling的核心提示词有四段；通过文件拷贝安装后可以直接修改。 - skill 位于 prompt 层，不依赖特定模型或 agent 产品；skills.sh 安装器支持多种 harness。
- 各环节可独立跳过、替换或编辑，排查范围限于当前 skill，而非整个流程框架。
- user-invoked 技能不占用常驻上下文。model-invoked 技能的 description 要求一个触发分支一句话，参考资料放入外部文件按需加载，因此比将完整方法论放入 CLAUDE.md 常驻上下文消耗更少。
使用成本与限制
- user-invoked 技能依赖使用者记忆和手动触发。
/ask-matt可以推荐 skill，但是否使用 grill 或 wayfinder 仍取决于使用者判断。 - skill 是 prompt，无法强制执行。
/tdd定义了红绿循环，但 agent 是否在每轮遵守取决于模型和上下文状态。仓库不提供 hook 或 CI 门禁，执行强度低于 pre-commit 运行测试等工程化约束。 CONTEXT.md、ADR、triage 标签和 issue tracker 配置需要维护。过期术语表可能误导 agent。仓库提供domain-modeling维护术语表，维护工作仍需由使用者完成。- 工程主线需要 issue tracker 保存规格和票据。个人小项目需要采用这项约定，或使用本地 markdown 文件。
- 小任务的流程开销较高。单行配置改动若经过 grill、spec、tickets、implement 和 review，投入可能超过收益。流程深度应随任务规模调整。README 建议每次改动从 grilling 开始，但未定义任务规模与流程深度的对应关系。
- Claude Code 提供原生插件和自动更新；Codex 等其他 harness 使用文件拷贝安装，跟进上游需要手动更新。
适用条件
适合长期维护的项目：项目已有 issue tracker，或愿意建立本地票据约定；团队或个人愿意维护 CONTEXT.md、ADR 等文档；使用者愿意为需求对齐和反馈回路投入交互时间。长期使用可以分摊固定流程成本，术语表和 ADR 也会积累可复用的项目上下文。
一次性脚本、探索性玩具和低复杂度改动通常不需要完整流程。希望人完全退出关键决策的用法也不符合该仓库的前提，因为 grilling 将决策保留给人。拒绝维护文档资产的团队需要评估术语表和 ADR 过期后产生的误导风险。
我的使用方式是在跨模块改动中采用完整流程，在小改动中保留 grilling 和 code-review。即使不安装这套技能，writing-great-skills 的写作规则和两层调用模型也可以作为设计 skill 时的参考。
