核验范围：本文以 mattpocock/skills 官方仓库 的 main 分支为主要来源，阅读了 README.md、.claude-plugin/plugin.json、ADR-0002、grilling、writing-great-skills，并核对了 implement 的流程说明。main 中 Claude 插件版本为 v1.2.0；GitHub Releases 显示的正式发布版本可能与此不同。本文不把仓库的说明写成性能测评，也没有独立运行它来比较模型表现。不同 Agent 对 Skill 的发现、自动触发、子 Agent 和插件的支持不完全一样，下面凡是涉及跨平台的地方都会单独说明。

如果你第一次使用 AI 编程，常见的体验大概是这样的：你说“加一个导出 CSV 的功能”，它很快写出一堆代码；你一试才发现，导出的字段不对、没有权限控制、中文乱码、空数据时还会下载一个奇怪的文件。你让它改，它再写一轮。最后功能也许能跑，但你说不清它到底满足了什么，也不知道下次该怎样避免同一种返工。

Matt Pocock Skills 把资深工程师反复做的几个动作写成可调用的工作说明：把不能猜的决定问清楚，写出可验收的规格，把改动拆小，让测试给实现提供反馈，再从两个角度审查结果。它关心的是模型写得很快之后，怎样避免它顺着一个错误假设一路跑偏。

这篇文章想回答三个具体问题：Skill 到底是什么；为什么有些 Skill 要你手动输入、有些可以让 Agent 自己选择；以及一个初学者怎样把它用于真实需求，而不把流程当成新的负担。读完后，你不需要记住仓库里全部 Skill。你应该能判断一项任务该从澄清、测试还是评审开始，也能看出一个 Skill 的说明写得是否靠谱。

先给结论：四个比命令更有用的习惯

这个仓库里有许多命令，第一次看很容易把注意力放到命令名上。其实最值得带走的是下面四个习惯。

1. 能在项目里查到的事实，别让 AI 来问你。它应当自己读代码、配置和文档。
2. 影响产品取舍的决定，别让 AI 替你猜。它应当一次只问一个问题，并给出推荐方案。
3. 每次代码改动都要接上反馈。类型检查、单测、浏览器验证都可以，关键是让“看起来合理”变成“可以证明没有明显错”。
4. 评审要把“代码写得像不像本项目”和“功能做没做对”分开看。两件事混在一起时，人和模型都容易漏项。

所以我建议初学者不要一上来安装全部流程。先跑通 grill-with-docs、tdd、code-review 这三个点，拿一个中等复杂度的小功能做一遍。它们分别对应需求、实现和交付，足够暴露你当前真正缺的是哪一环。

一、先把几个词说清楚

Skill 不是提示词合集

在 Claude Code、Codex 等带有 Skill 机制的工具里，Skill 通常是一份 Markdown 指令文件，文件名常为 SKILL.md。它告诉 Agent 三件事：什么时候该使用它、按什么步骤做、做到什么程度才算完成。它也可以链接到其他文档，例如术语表、测试规范或团队约定。

因此 Skill 和“把一段提示词存起来”有重叠，但不完全相同。一段普通提示词可能只说“请帮我审查代码”；一个好 Skill 会继续规定审查范围、信息来源、输出格式和结束条件。它的目标不是让每次结果一字不差，而是让 Agent 每次经过相近、可预测的过程。writing-great-skills 把这种过程稳定性称为 predictability，这个定义很准确。writing-great-skills

这里有一个边界必须先说清：Skill 不负责权限控制，也不会天然阻止模型犯错；它不会自动替你接入 CI、任务系统或代码托管平台。它把“这件事应该怎样做”放进 Agent 能使用的上下文。最终能否触发、能否访问文件、能否创建工单，仍然由你使用的 Agent 和环境决定。

Harness 是什么，为什么它会影响体验

本文会用到 harness 这个词。它指承载模型并给模型提供文件读写、终端、浏览器、插件、Skill 发现等能力的那层工具，例如 Claude Code 或 Codex。相同的一份 SKILL.md 放进不同 harness 后，文本当然能被阅读，但下面这些行为不一定相同：

所以“仓库说支持 Codex”不等于“Claude Code 里某个命令的体验会原样复制过来”。Skill 可以移植的是工作说明，跨平台一致的功能按钮则需要各个 harness 自己实现。

两类触发方式：把决定权放在合适的位置

仓库用一条轴来划分 Skill：谁可以触发它。官方 README 给出的规则很简洁。

在这个仓库中，frontmatter 里的 disable-model-invocation: true 会把 Skill 设为仅供用户显式调用。它的 description 不再承担“让模型发现它”的职责。没有这个字段的 Skill 可以保留面向模型的触发描述，模型在任务匹配时才有机会选择它。writing-great-skills 还规定，手动 Skill 可以调用自动 Skill，但不能再调用另一个手动 Skill。原文

语法背后是责任分工。假如 Agent 自己决定了“导出 CSV 时应该省略敏感字段”，那是替你做产品决定；假如它在写导出逻辑时主动先写失败测试，则是在执行工程纪律。前者应让人来确认，后者可以鼓励模型主动做。

二、上下文成本和认知成本，究竟在取舍什么

初学者听到“上下文工程”容易以为只是省 token。更实用的理解是：注意力和信息窗口都有限，放在哪里都要付钱。

对于 model-invoked Skill，为了让 Agent 在每一轮都知道“什么时候该用我”，它的 description 会进入可发现范围。仓库把这叫 context load。Skill 越多、描述越长、触发词越重复，模型越难区分应该选哪个，真正重要的任务信息也会被挤到后面。

反过来，user-invoked Skill 不需要一直暴露给模型，几乎不消耗这部分上下文；代价是你得记得它存在，知道什么时候输入它。仓库把这叫 cognitive load。把十几个只能手动启动的命令塞给新人，确实省了模型上下文，却把导航工作全丢给了人。

ask-matt 之类的路由 Skill 正好解决这个矛盾：保留一个人能记住的手动入口，由它根据问题推荐后续流程。一个入口替你承担了一堆分散命令带来的记忆负担。

可以用下面这张表做判断。

有两个误区值得避开。

第一，不要把每一条团队规范都做成 model-invoked Skill。比如“提交信息使用中文”这种单一规则，放在项目说明里通常更合适。Skill 的 description 需要成为一个独立的触发信号，而不是另一个存放杂项的抽屉。

第二，自动触发不是承诺。模型可能没有看见、没有理解 description，也可能在当前 harness 中根本不支持自动选择。所以关键流程仍要有显式入口和验收手段。你不能因为装了 tdd 就假设每一次修改都有测试，仍然要看测试是否真的先失败、是否真的运行过。

三、这套仓库想修复的四种问题

README 按四类开发失败组织 Skills。把它们翻译成初学者会遇到的场景，理解会更具体。

1. Agent 做的不是你想要的东西

这通常不是模型“笨”，而是需求里同时混着事实、偏好和未说出口的限制。以“加 CSV 导出”为例：现有用户表有哪些字段，这是事实，Agent 应该读 schema 和接口；导出给管理员还是所有用户，这是决策，Agent 不该从代码风格里猜。

grilling 的规则正是沿着这条线划分：能从文件、工具和环境中查到的事实，应当自行查；需要权衡的决定，逐个问用户，并在形成共识前不要行动。grilling Skill

“逐个问”并不是故意拖慢。一次抛十个问题时，后一个问题往往依赖前一个答案，用户很容易只答一半，模型再用猜测补齐。一个好的提问还应给出推荐，例如：“我看到普通成员能看到自己的邮箱，但不能看全体成员。建议只有管理员能导出，是否确认？”这比“权限怎么做？”更容易回答，也留下了判断依据。

2. Agent 太啰嗦，术语却不稳定

很多项目都有自己的词：订单的“取消”到底是退款还是关闭？“成员”是否包含被邀请但未激活的人？人类会在几次讨论后默认理解，模型每次新会话却可能重新猜一次。

仓库给出的办法是共享语言，也就是 CONTEXT.md、术语表和 ADR。它们把反复解释的一段话压缩成一个有定义的词。README 的例子把一长串“课程中的某一课被赋予文件系统位置”的描述收束为 materialization cascade。README

对自己的项目，先从十行开始就够了。例如：

1
2
3
4
5

## 导出任务

- export job：由管理员发起、异步生成 CSV 的后台任务。
- 成员：已加入组织且未被软删除的账号；受邀未激活账号不算成员。
- 脱敏导出：手机号和邮箱按权限规则处理后的 CSV。

这份小文档的价值不在“减少模型说话字数”，而在于接口、变量、测试名和讨论能使用同一个词。当它们指向同一个概念时，维护代码的人也更容易读懂。

ADR 是另一种更窄的文档，记录一个已经做出的架构或产品决定，以及当时为什么这样选。比如“CSV 在服务端生成，链接 24 小时后失效”，以后有人问为什么不用浏览器直接拼字符串，就不必从 Git 历史里考古。不要把 ADR 写成会议纪要。一个问题、一项决定、主要理由和后果，通常就够了。

3. 代码生成得很快，却没有可靠反馈

模型最危险的时刻往往不是报错，而是代码看起来很顺。它会补全类型、写出漂亮函数名，甚至顺手通过 lint，但业务分支仍可能反了。没有反馈时，Agent 和人都只能凭感觉判断。

README 提到三类反馈：静态类型、浏览器访问和自动化测试。它把红、绿、重构的 TDD 循环放在测试部分：README。TDD 很容易被用成“所有代码都必须先测”的仪式。更准确的用法是在风险集中的接缝处先写一条能说明行为的失败测试，再写最少的代码让它变绿，最后整理结构。

所谓接缝，指容易单独验证、又容易出错的边界。例如权限判断、日期转换、CSV 转义、调用第三方 API 的适配层。UI 颜色微调这类事情，截图和人工验收可能比单元测试更合适。implement Skill 的原文也没有要求全盘 TDD，它说的是“在事先约定的接缝处，尽可能使用 /tdd”。implement Skill

4. 功能越加越多，代码库变成一团泥

AI 降低了写文件和复制模式的门槛，也降低了“先这样放着”的心理阻力。结果常常是一个页面组件既拉数据、又做权限、又生成文件，还夹着格式化规则。每个局部都能工作，组合起来却越来越难改。

仓库的 to-spec、to-tickets、codebase-design 和 improve-codebase-architecture 都在处理这个问题。它们并不保证产出好架构，但至少会逼你先回答：这次修改碰到了哪个模块？公共接口是什么？哪些依赖不应被带进来？README 特别强调 deep module，也就是把较多行为藏在较小、清晰的接口后面。README

对新人而言，一个朴素判断就很有用：如果为了改一个导出字段，你必须同时理解页面、权限、数据库、队列和文件存储，那不是“项目复杂所以没办法”，而是边界可能需要重画。先找一个能被测试的接口，把格式化或权限判断从页面里拿出来，往往比大规模重构可靠。

四、从零走一遍：给成员列表增加 CSV 导出

接下来不用抽象地谈流程。假设你维护一个组织成员后台，现在要加一个“导出成员 CSV”功能。以下不是仓库运行后的真实日志，而是按各 Skill 的公开规则整理的一次合理执行路径。你可以把它当成第一次练习的脚本。

第 0 步：先判断它值不值得走完整流程

不是每一处改动都要创建规格、工单和多轮评审。先用三个问题筛选。

三个答案中有两个为“是”，就值得至少做澄清、测试和评审。如果只是把按钮文案从“导出”改成“下载”，直接修改、手动验证即可，不必把简单事做重。

第 1 步：安装和验证，不要跳过这一小步

官方 README 给出的通用安装入口是：

1

npx skills@latest add mattpocock/skills

安装器会让你挑选要安装的 Skill 和目标 Agent。第一次使用时，官方建议一并选择并执行 /setup-matt-pocock-skills。它会询问你使用 GitHub、Linear 还是本地文件做 issue tracker，现有标签是什么，以及把生成文档放到哪里。Quickstart

如果你用 Claude Code，也可以把它作为原生插件安装；官方 README 给出了 marketplace 和 shell 两种方式。插件是托管且随发布更新的包，skills.sh 则把可编辑副本复制到项目中。安装说明

两种方式没有谁绝对更好。想读、改、删里面的指令，选可编辑副本；只想使用维护者持续更新的整套流程，选插件。无论选哪个，安装后都做一次很短的验证：让 Agent 列出已发现的相关 Skill，打开其中一个 SKILL.md 看看内容，再显式运行 setup。不要只看到安装命令没有报错就开始依赖它。

还要养成一个安全习惯：第三方 Skill 本质上是给 Agent 的指令。尤其当它涉及终端、Git 提交、外部服务或删除文件时，先读一遍实际内容，确认它会做什么。这个仓库的 implement 最后会要求提交当前分支；如果你的团队不允许 Agent 自动 commit，就应在使用前修改本地副本或明确限制它。implement Skill

第 2 步：先 grilling，分开“事实”和“决定”

你可以在 Agent 中这样开始：

1
2

/grill-with-docs
我们要在组织成员后台增加 CSV 导出。先检查现有成员模型、权限和导出能力；需要产品决定的地方一次问我一个问题，确认前不要改代码。

一个合格的 Agent 不会马上问“成员有哪些字段”。它应先搜索 schema、API、现有权限中间件和类似下载功能。假设它查到成员有 name、email、role、joinedAt、phone，并发现普通管理员只能查看自己所在组织，它接下来应该问的是决策，而不是可查事实。

下面是你希望看到的问答节奏：

Agent：当前列表接口已按组织过滤，但没有导出权限。建议只有 org_admin 和 owner 可以发起导出，其他角色返回 403。是否确认？

你：确认。

Agent：手机号和邮箱都属于个人信息。建议 CSV 包含姓名、角色、加入日期；邮箱只对 owner 显示，手机号不导出。是否需要改动？

你：邮箱对 org_admin 也显示，手机号不导出。

Agent：成员数超过 10 万时同步生成可能超时。当前项目已有队列服务。建议复用队列，生成完成后给管理员一个 24 小时有效的下载链接。是否接受异步方式？

你：接受，但首版先不做邮件提醒，在页面轮询状态。

注意这里每个问题都包含它从项目中查到的依据和一个建议。这样你不是在填空，而是在做清楚的取舍。若 Agent 一开始就问“字段、权限、格式、错误提示、性能、文件名都是什么”，你可以要求它先检查仓库，并改为单题推进。

这一步结束时，至少应得到三类产物：一份更新后的术语说明、一条或几条 ADR，以及一段已确认的需求摘要。它们不必很长，但以后任何人和任何新会话都能从这里知道“导出任务”究竟指什么。

第 3 步：把聊天记录变成可以验收的规格

确认需求后调用 /to-spec。README 对它的定位很明确：把当前对话合成为规格并发布到 issue tracker，它本身不再进行一次访谈。Skills 清单

一份对初学者有用的规格，应该是一组能被测试或人工检查的约束。“实现 CSV 导出”这种标题加几段空话还不够。这个案例的核心部分可以写成：

1
2
3
4
5
6
7
8

## 验收条件

1. `owner` 和 `org_admin` 可在本组织成员页创建导出任务；其他角色得到 403。
2. 导出只包含当前组织、未软删除的成员，并遵从页面提交的筛选条件。
3. `owner` 和 `org_admin` 的 CSV 都有姓名、邮箱、角色、加入日期；CSV 不包含手机号。
4. 包含逗号、引号或换行的字段按 RFC 4180 规则转义；空成员列表也生成含表头的文件。
5. 成员数超过 10 万时走已有队列。任务完成后页面可取得下载链接，链接 24 小时后失效。
6. 创建、失败和完成状态在页面上可辨认；失败信息不泄露存储凭据或内部堆栈。

这里有一个很实用的检查法：把每一条前面加上“如何证明？”如果你答不上来，它多半还是愿望，不是验收条件。比如第 4 条可以用单测证明；第 1 条可以通过不同角色的 API 测试证明；第 5 条需要集成测试或队列的替身加页面验证。规格不是用来装饰工单，它决定后面的测试和评审到底在核对什么。

第 4 步：复杂任务再拆 ticket，简单任务不要硬拆

to-tickets 会把计划、规格或对话拆成 tracer-bullet tickets，并标出阻塞关系。所谓 tracer bullet，不是一次把所有层做完，而是让一个很薄的可运行切片先穿过系统，再逐步加厚。仓库支持把这些关系写入本地文件，或映射到真实任务系统的阻塞链接。README

这个 CSV 案例可以拆成下面四张，而不是十几张颗粒过细的任务：

  flowchart LR
  A["A. 定义导出领域接口和权限"] --> B["B. 同步生成与 CSV 转义"]
  A --> C["C. 队列任务、存储与状态"]
  B --> D["D. 页面交互、集成验证与交付"]
  C --> D
  

• A 的完成条件是：调用者可以通过一个明确接口创建导出请求，权限拒绝有测试。
• B 的完成条件是：给定成员和筛选条件，能产生符合规格的 CSV，边界字符有测试。
• C 的完成条件是：大导出不会在请求线程中生成，任务有状态并能获得受时限保护的下载地址。
• D 的完成条件是：页面可以创建并查看任务，端到端验证覆盖成功和失败状态。

如果项目还没有队列，首版也许应该把“异步任务”从本次需求中删掉，并在规格里明确限制最大成员数。这让产品范围和技术前提保持一致。Skill 的价值在于暴露这种依赖，而不是强迫你假装所有基础设施都已经存在。

第 5 步：在接缝处做 TDD，让模型有地方停下来

到 /implement 时，Agent 已经不该重新发明需求。它应按规格和 ticket 实现，在事先约定的接缝处使用 /tdd，经常跑类型检查和单个测试，最后再跑完整测试和代码评审。implement Skill

以 CSV 转义函数为例，红、绿、重构可以很小：

1
2
3
4

// red: 先写能表达规则的测试
expect(toCsvCell('A,B')).toBe('"A,B"')
expect(toCsvCell('say "hi"')).toBe('"say ""hi"""')
expect(toCsvCell('first\nsecond')).toBe('"first\nsecond"')

此时测试应当失败，因为函数还不存在或行为不对。接着只写到足以通过测试的实现：

1
2
3
4

export function toCsvCell(value: string): string {
  if (!/[",\n\r]/.test(value)) return value
  return `"${value.replaceAll('"', '""')}"`
}

测试变绿后，再看是否需要处理 null、日期格式或复用通用库。重构不是“为了优雅改一改”，而是在行为已被锁住后消除重复、改善命名。这个顺序很适合 Agent：它先获得一个明确的失败信号，修改范围不会无限扩张。

TDD 也有不适合的地方。浏览器布局、下载文件名的视觉呈现、第三方存储服务的真实权限，可能更需要 Playwright、集成环境或人工验证。不要为了遵守一个名字而写出只验证 mock 的空测试。反馈形式应该服务风险，而不是服务流程。

第 6 步：用两条独立问题线做评审

code-review 的特别之处是把审查分成 Standards 和 Spec 两个轴，并建议并行执行，避免一条判断污染另一条。前者看是否遵从项目规范和常见代码坏味道，后者回到原始 issue 或 PRD，看功能是否忠实实现。README

把它落在 CSV 功能上，两个审查者会问不同问题：

如果你只有一个人，也可以按这个顺序自己检查两遍，第二遍强制打开规格逐条打勾。不要把“测试全绿”当成规格已实现的证明，测试可能从一开始就没覆盖被遗漏的条件。

五、这条流程可以怎样裁剪

完整路径是“澄清 → 规格 → tickets → 实现与反馈 → 双轴评审”。它适合跨模块、有业务取舍、需要交接的工作，但不是每次都应当照搬。

  flowchart TD
  Q{"有未确认的业务决定吗？"}
  Q -->|有| G["grill-with-docs"]
  Q -->|没有| R{"是否跨模块或需要交接？"}
  G --> S["to-spec"]
  R -->|是| S
  R -->|否| I["直接实现，在风险接缝处测试"]
  S --> T{"能拆成独立可验证的切片吗？"}
  T -->|能| K["to-tickets"]
  T -->|不能或任务很小| I
  K --> I
  I --> C["code-review 与验证"]
  

下面是一个更易执行的选择表。

很多人把流程用坏，是因为他们把“每个 Skill 都用上”当成目标。实际目标是降低返工和不确定性。某一步没有在降低风险，就删掉它；某个风险还没有反馈方式，就补一条最便宜的验证。

六、如何从这个仓库学会写自己的 Skill

writing-great-skills 值得单独读，因为它不是在教“写得更像提示词”，而是在教怎样管理 Agent 的注意力。

description 只负责触发，不负责讲完全部流程

model-invoked Skill 的 description 有两件事：说明它是什么，列出真正不同的触发分支。每多一个词都增加 context load，所以不要把正文又抄一遍。原文建议把 leading word 放在前面，并让每个分支只保留一个触发信号。writing-great-skills

例如下面这段 description 看似完整，实际上很难触发稳定：

1

description: 当用户要写功能、修 bug、加测试、重构、排查问题、优化性能、改善代码质量时，认真分析需求并遵循最佳实践。

它把许多不同动作塞在一起，也没有说明何时应该进入。更好的做法是拆开，或者先承认它只是一份项目总规范。例如调试 Skill 可以写：

1

description: 诊断难复现的 bug 或性能回退。先复现并最小化问题，再提出可证伪的假设、补充观测、修复并添加回归测试。

这里的“难复现 bug”“性能回退”“先复现”“回归测试”都在帮模型识别它是否适用。若你无法为一个新 Skill 说出独立的触发信号，它可能还不该拆出来。

每一步要有完成条件

“分析代码后给出建议”不是一个可完成的步骤，因为模型不知道分析到哪里算完。writing-great-skills 建议在步骤末尾写可检查、必要时穷尽式的 completion criterion，防止 premature completion，也就是模型过早宣布完成。原文

对比一下：

可检查不等于啰嗦。它只需要让 Agent 和人能区分“已完成”和“还差什么”。

把不总是需要的资料放到外部引用

Skill 正文里的信息越多，不代表越可靠。仓库把信息放在一个层级里：每次都要执行的步骤留在 SKILL.md；按需查阅的规则可以在同文件的参考区；只在某些分支用到的大资料移到单独文件，并用明确的 context pointer 指向它。writing-great-skills

例如代码评审 Skill 无需在正文复制全部安全规范。可以写“当 diff 涉及认证、授权、个人数据、支付或外部输入时，读取 references/security-review.md”，并让那个文件专门维护安全检查项。指针的文字比链接文件名更重要，因为模型靠那句话决定要不要加载。

这叫 progressive disclosure，渐进披露。它不只是为了少占上下文，也是为了让正文保持可读。新成员打开 Skill 时先知道流程，真的碰到支付或权限时再看细则。

什么时候拆 Skill，什么时候别拆

原文给出两个合理拆分点：一个动作有独立的 leading word，或需要被其他 Skill 调用时，可以按触发拆；一串步骤中，后面的步骤会诱使 Agent 跳过当前步骤时，可以按顺序拆。writing-great-skills

比如“先复现，再缩小，再假设，再观测，再修复，再加回归测试”是一条强顺序链。若你把“修复”放在开头，模型会急着动手，前面的诊断变成形式。把它写成调试循环，或者明确每一步的完成条件，比拆成六个命令好。

相反，“生成变更日志”和“诊断性能回退”通常有不同触发词和不同输出，应当是两个 Skill。粒度的本质不是文件大小，而是你愿意付 context load 还是 cognitive load，以及这个代价是否换来了更稳定的行为。

七、安装、平台与安全：原文里容易被一笔带过的部分

官方仓库提供两条分发路径。skills.sh 通过 npx skills@latest add mattpocock/skills 把 Skills 安装为可编辑的副本，README 表示它可用于 Codex 和其他兼容 Agent-Skills 目录约定的 harness。Claude Code 另有原生插件，适合想订阅维护者版本、不想手动维护副本的用户。README

仓库的 ADR-0002 解释了为什么目前没有原生 Codex 插件。Claude 的插件清单可以显式列出多条 Skill 目录，仓库因而只发布已经推广的 engineering 和 productivity Skills；当时 Codex 的插件清单只能给出一个路径，并会递归发现其下所有 SKILL.md，这会把草稿、弃用和个人目录一并发布。把目录重排或复制一份扁平目录都意味着额外维护成本，所以作者选择暂缓原生 Codex 插件。ADR-0002

这段 ADR 很值得初学者读，因为它展示了一个常见工程现实：产品能力不只是“能不能解析 Markdown”。目录结构、打包格式、更新策略和缓存行为都会改变最终体验。看见“跨模型可用”时，最好继续问四件事：怎么安装？模型会不会自动发现？是否可以改？有外部服务时权限从哪里来？

另一个不能忽略的问题是信任边界。Skill 可以要求 Agent 执行命令、读取项目内容、调用外部工具，甚至 commit。安装第三方 Skill 前，至少检查：

• 它是否要求执行你不理解的 shell 命令。
• 它是否会修改 Git 历史、创建远程 issue 或发送数据到外部服务。
• 它的完成步骤是否符合团队的测试、审查和提交规则。
• 更新后是否还保留了你依赖的行为。

这不是对这个仓库的特殊怀疑，而是把第三方自动化当作代码审查。方便的东西越能动你的项目，越应该先读。

八、常见失败方式，以及怎样修正

失败一：把 grilling 当成“让 AI 多问一点”

症状是 Agent 问了很多可从代码里查出的事实，用户被迫充当搜索引擎，最后仍没有确认关键取舍。

修正方式是先明确边界：让它先读相关代码和文档；只有存在多种合理答案、且答案会改变范围、成本或风险时才问人。每题只问一个决策，附带依据和建议。若你发现问题已经开始重复，先要求它总结当前共识，再继续。

失败二：把规格写成愿景文案

“导出要快、体验要好、数据要安全”听起来正确，测试却无从下手。这样的规格会把所有实现细节重新留给模型猜。

修正方式是补充对象、条件和可观察结果：谁在什么前提下做什么，系统返回什么，失败时怎样表现。也要写清不做什么。CSV 首版不支持 Excel 模板、不发邮件提醒、不导出手机号，这些边界会阻止需求在实现中悄悄变大。

失败三：让 model-invoked Skill 背负全部责任

自动触发很舒服，但它受 description、模型、当前上下文和 harness 能力共同影响。关键的安全扫描、数据迁移、发布检查不能只靠“模型应该会想到”。

修正方式是为高风险动作设置明确入口和外部闸门。例如发布仍由 CI 和人工审批控制，数据库迁移仍由迁移检查清单和备份策略控制。Skill 可以帮助执行检查，不能替代系统性的防线。

失败四：为所有事创建 Skill

Skill 多到几十个后，模型描述互相抢触发，人也记不住手动入口。最后团队又回到“直接说一句帮我做”。

修正方式是先记录重复出现且代价高的失败。一个流程至少重复几次，且你能说清它的输入、步骤、产物和完成条件，再把它固化成 Skill。其余规则留在项目文档中即可。定期删掉无人使用或与其他 Skill 重复的条目。

失败五：把测试当作完成证明

绿色测试只说明“现有测试期望的行为没有被破坏”。如果测试没覆盖权限、数据范围或下载链接过期，功能仍然可能不符合规格。

修正方式是把验证分层：单测锁住纯逻辑，集成测试验证边界，浏览器或手工验收检查用户路径，最后再用规格逐条核对。每层解决不同问题，没有一层能替代其他层。

失败六：忽略长流程的中断和交接

实际任务会跨会话、跨人甚至跨天。只靠聊天上下文，下一次打开时很容易重新调查一遍，或者误以为某项决定尚未确认。

修正方式是把已确认的术语、ADR、规格、ticket 和验证结果写回项目。仓库也有 handoff 与 wayfinder 一类能力用于交接和长期探索，但新人不必先学它们。先保证一项中等任务的决定和验收条件有落点，已经能减少大量重复劳动。

九、一个适合初学者的四周引入计划

不必把整个团队流程一次换掉。下面的节奏更容易看出它是否真的减少返工。

你可以简单记录四个数字：需求确认后发生了几次重大返工；测试或审查发现了几项问题；为了走流程多花了多少时间；下次接手同类任务是否更快。不要试图精确衡量“AI 提升了多少百分比生产力”，那很容易陷入无意义统计。只需要判断它是否让你的项目更少猜测、更容易验证、更方便交接。

十、读完后可以用这份清单自测

如果下面大部分问题你都能回答，说明你已经掌握了本文真正想讲的东西，而不是只记住几个命令。

• 你能解释为什么“谁可以导出数据”应由人确认，而“先跑受影响测试”可以由 Agent 主动做。
• 你知道 model-invoked Skill 的 description 过长会带来什么代价，也知道手动 Skill 太多时为什么需要路由入口。
• 给你一个新功能时，你能先区分项目可查事实和需要产品决定的问题。
• 你能把“做一个 CSV 导出”改写成至少三条可验收、可验证的行为。
• 你明白 TDD 最适合放在什么样的接缝处，也不会强迫所有改动都使用它。
• 你能分别从 Standards 和 Spec 两个角度审查一份 diff。
• 你知道安装成功不等于自动触发可用，更不等于第三方 Skill 的行为已经被信任。

答不上来的地方，不需要重读全文。回到 CSV 案例，自己选一个熟悉的小功能，写出“事实、决策、验收条件、反馈方式”四列。那张小表比背下十个命令更有用。

结语

Matt Pocock Skills 让我认可的是，它把 AI 编程里常被跳过的工程动作重新摆到台面上：需求要确认，术语要统一，行为要有反馈，交付要回到规格检查。

它也有边界。Skill 不会消除模型的不确定性，不会自动理解你的业务，不会让测试缺失的项目突然可靠。它能做的是给人和 Agent 一套更清楚的分工。涉及目标和取舍时，人保持控制；涉及重复、可验证的工程纪律时，让 Agent 帮忙坚持。

先用一个小闭环验证它。下一次你准备让 AI “直接做个功能”时，先让它查清事实，再问一个真正需要你决定的问题。等这个习惯稳定下来，规格、工单和更长的流程自然会有位置。

参考资料

• Matt Pocock Skills 官方仓库
• Claude 插件清单 plugin.json
• ADR-0002：为什么暂缓原生 Codex 插件
• grilling Skill
• writing-great-skills Skill
• implement Skill