好用的 Agent Skill 到底怎么构建？丨AI Engineer

好用的 Agent Skill 到底怎么构建？丨AI Engineer 好用的 Agent Skill 到底怎么构建？丨AI Engineer Modified July 2 🔗 原文链接： https://mp.weixin.qq.com/s/UZSGrouF... 原创 Capihom Capihom 晚点再听LaterCast2026年7月1日 21:23 北京 我们每天为你更新硅谷最新的 AI 创业与科技播客总结，让你与前沿保持同频。 全文约 4000 字，如果你现在没有时间，试试转成播客稍后再听 "区分好 Skill 和坏 Skill 的能力，只会越来越重要。" "Skill Hell 里，免费 Skill 到处都是，你却看不出它们怎么拼在一起。" "每增加一个模型可触发的 Skill，Agent 都要多背一份上下文负担。" 如果你最近用过 Codex、Claude Code，或者在团队里写过 AGENTS.md，大概已经碰到过一个新问题：给 Agent 的规则越来越多，效果却不一定越来越好。 一开始，大家会觉得答案很简单。模型没按预期做，就再补一条规则；写作不像人，就再加一段风格要求；代码改偏了，就再塞一份流程。几轮下来，Skill 越写越长，Agent 还是会漏读、误读，团队也不知道哪句话真的起作用。 AI Engineer 这场演讲讲的就是这件事。演讲者 Matt Pocock 维护着一个很受欢迎的工程 Skill 仓库，他把这类混乱叫做 Skill Hell。听起来像玩笑，放进工程团队就很现实：你要把代码审查、写 PRD、排查问题、做复盘这类工作交给 Agent，就得先学会写一份 Agent 真能执行的团队规程。否则 Skill 只是换了名字的提示词堆叠。 别再只往 Skill 里加规则 Pocock 说，开发者很擅长给自己制造新的困境。以前有 tutorial hell：教程看了一堆，还是拼不出完整项目。后来有 framework hell：框架更新太快，大家一直追新。现在轮到 skill hell。 Skill Hell 不像错误日志那样直接跳出来。它通常长得很体面：GitHub 上有一堆免费 Skill，看上去都能下载、改造、复用。问题在后面。你看不出哪份 Skill 设计得好，也看不出哪段文字只是摆在那里。 "组织还不知道怎样构建好 Skill，怎样把自己的操作规程变成 Agent 能做的事。" 放到日常工作里，就是这个场景：你把“我们怎么写需求、怎么查代码、怎么做测试”写进 Skill，以为 Agent 会自动学会团队习惯。结果它有时照做，有时跳过，有时读了也没变。Pocock 给出的审稿顺序很直接：先看谁触发，再看结构，再看文本有没有改变 Agent 的动作，最后删掉无效内容。 多装一个 Skill 很快，重新审一遍团队规程更慢，也更接近问题本身。团队规程原来是写给人看的，人会跳过废话，会用经验补空。Agent 不会。它只能读到你写下来的东西，也会被你写下来的废话拖住。 所以 Skill 写作不像写一篇说明文，更像给一个很勤快但很死板的新同事写交接。写少了，它不知道边界；写多了，它把边角料也当任务。Skill Hell 就从这里开始。一次失败往往不全是模型能力问题，团队也可能把交接写成了备忘录。 先决定谁来叫它 一份 Skill 写出来之后，有两种入口。一种是用户手动调用。文件在本地，你明确告诉 Agent：现在去读这份 Skill。另一种是模型自己调用。Skill 的 description 平时就放在 Agent 的上下文里，模型看到任务后自己判断要不要打开。 很多人会本能地喜欢第二种。少一步操作，看起来更聪明。但 Pocock 提醒，自动触发不是免费午餐。每多一个模型可触发的 Skill，Agent 每次请求都要多背一条描述，也要多一个选择。Skill 少的时候没感觉，几十上百个以后，模型会被一堆入口拖住。 "如果有 100 个模型可触发的 Skill，Agent 的上下文里就会有 100 条描述。" 所以团队要先分清两类 Skill。高频、低风险、边界清楚的，可以让模型自己发现；低频、影响大、需要人判断时机的，最好让人手动触发。比如“生成提交说明”可以自动一点，“重写客户需求文档”就不该悄悄发生；“给线上事故做复盘”也不该在上下文不完整时自动开跑。 很多团队会跳过入口设计，因为大家急着写正文。但入口选错了，后面写得再细也会别扭：要么 Agent 背太多无关描述，要么用户记不住什么时候该用哪份 Skill。 Pocock 自己更偏向用户触发。他承认这样会让使用者多记一点东西，但换来的是少一层不确定性。模型自动触发看起来省事，背后还要做另一件麻烦事：验证它有没有在该调用的时候真的调用。 公司内部 Skill 更需要这道判断。一个客户交付流程、一次线上事故复盘、一次安全审查，触发错了就会带来额外成本。与其把所有东西都塞进模型视野，不如先让人决定什么时候打开哪扇门。这个选择听起来很小，后面会影响每一次请求的上下文重量。 Skill.md 不该写成团队杂物柜 Pocock 拆 Skill 的方式很朴素：一份 Skill 里通常只有两类东西。步骤，告诉 Agent 接下来怎么走；参考材料，帮助 Agent 在某一步里查信息。 他举了一个 2PRD 的例子。这个 Skill 要把当前上下文整理成产品需求文档，所以步骤可以是：先找到相关材料，再和用户确认 test seam，最后写 PRD。参考材料则是 test seam 的定义、PRD 模板。一个负责行动，一个负责查阅。 团队最容易犯的错，是把这两类东西混在一起。今天有人加一段模板，明天有人补一段术语解释，后天又有人把一次项目复盘塞进去。半年后，Skill.md 变成谁都不敢删的公共文档。新人打开它，只能猜哪几段是命令，哪几段只是背景。 "每删掉一个词，都是从 Skill 成本里刮掉一个 token。" Pocock 的建议是把主文件写小。主文件只留公共入口：什么时候用，按什么顺序做，遇到分支时去哪里取材料。模板、样例、ADR、glossary，都可以放到旁边文件。Agent 需要时再取，人类 review 时也能一眼看出哪句话在控制行为。文件短，团队才敢改；团队敢改，Skill 才不会沉积。 他举的另一个例子是 domain modeling。这个 Skill 可能更新 glossary，也可能创建 ADR。ADR 模板只在其中一个分支里用，就没必要塞进主文件。主文件里留一句“需要 ADR 模板时去读这个文件”，已经够了。 对读者来说，可以马上拿自己的 Skill.md 做一个检查：如果某段内容只在一种情况里使用，它就应该被挪出去；如果某段内容每次都会用，才留在主文件里。这个动作很小，却能让 Skill 从“长文档”变回“可执行入口”。 一个短词，有时比一整段规则管用 很多 Skill 读起来都很认真：“不要一次性写完整功能”“请先做小范围验证”“尽量早点拿反馈”。这些话没有错，但 Agent 经常读完还是按老习惯做。 Pocock 给出的办法，是找 leading words，也就是能压住一整套做法的短词。他举的例子是 vertical slice。Agent 做大需求时，常常会先写数据库层，再写 schema，再写 API，再写前端，横着铺一层。vertical slice 这个词会把它拉回另一种工程习惯：先做一个能跑通的小切片，早点验证，再往外扩。 "我们把很多含义打包进一个相对短的短语里，然后在 Skill 里反复使用它。" Pocock 给了一个很实在的验证方式：你能从 Agent 的输出里看到它有没有学进去。当它开始说“先做一个薄的 vertical slice”，计划通常也会跟着变。团队写 Skill 时，与其堆十句近义提醒，不如先把几个能改变动作的词钉住。比如“vertical slice”“deletion test”“read first”这类词，短，但能把做法拉回来。以后看执行计划时，也能顺手检查这些词有没有出现。 注意，短词要稳定。今天叫 vertical slice，明天又叫 thin slice，后天改成 minimum path，模型读到的是一串近义词，动作反而不稳。好的 Skill 应该像团队黑话一样，少数几个词反复出现，每个人和 Agent 都知道它们指向什么。 团队里的工程口头禅也是这样。你说“先写测试”，很多解释都还要补；你说“红绿重构”，熟悉的人立刻知道先失败、再通过、再整理。Skill 里的短词也一样，它负责把一整套动作压进一个稳定入口。 让 Agent 一次只认真做一件事 Pocock 还讲了一个很常见的坑：Agent 在前置步骤上偷懒。最典型的是 plan mode。它通常要求 Agent 先问澄清问题，再生成计划。结果你会发现，它匆匆问两句，就急着交计划。 为什么？因为它已经看到了终点。只要最终目标写着“生成计划”，追问就容易被当成前奏，而不是任务本身。 他的做法是拆开。先用一个单独的 Skill 专门追问和读材料，比如 grill with docs：先把文档、仓库、历史 issue 和用户口述都问透，再交给下一份 Skill 写 PRD。这个阶段结束后，再进入写 PRD 的 Skill。Agent 当下只看到一件事，脚力就会多一点。 放到团队工作里，这条很实用。代码库探索、需求追问、失败复盘、资料核对，都很容易被最终交付物挤掉。要让 Agent 做扎实，就别把所有未来步骤一次性摊在它面前。先让它把当前阶段做厚，再把下一阶段交给它。Pocock 的 plan mode 例子，其实就是把“问清楚”和“写计划”拆开。下次写 Skill 时，可以先问一句：哪一步最容易被 Agent 敷衍过去？那一步就值得单独拿出来。 拆开流程，是为了保护前面那些容易被压缩的工作。人类同事也一样。如果你一边让他调研，一边告诉他最后要交三页方案，他很可能会按方案倒推材料。Agent 更会这样。它会朝着最终交付物跑，除非你暂时把终点藏起来。 删掉那些不会改变结果的句子 最后是删减。Pocock 提到几类坏味道：重复、沉积物、no op。 重复很好理解。同一个模板、同一条约束、同一个术语解释，散落在好几个地方，后面一定会改漏。沉积物更麻烦。团队维护 markdown 时，每个人都往里加一点，却没人敢删别人的旧话，Skill 就慢慢堆出一层灰。那些被反复复制的旧说明，最容易留下来。 "No op 是 Skill 里看起来有用、实际不会改变 Agent 行为的东西。" No op 最值得警惕。比如一个实现 Skill 里写了一大段“请写详细 commit message”。你把这段删掉，Agent 可能仍然会写一段像样的提交说明。那这段文字就没有改变行为，只是在占空间。 Pocock 的删除测试很简单：删掉一段，再看 Agent 的输出有没有变化。没变化，就别留。人读文档时会自动跳过废话，Agent 不会。它会把每一句都当成可能有用的上下文，哪怕那句话只是过去某次讨论留下的礼貌性提醒。 删除测试还能帮团队少吵架。很多文档里的句子不是错，只是没用。说它错，作者会防御；说“删掉后 Agent 行为没有变”，讨论就回到结果上。Skill 越短，留下来的每句话就越有责任。保留下来的句子，应该能让 Agent 多做一步、少犯一个错，或者少读一段无关材料。 Pocock 最后的扫尾清单其实很硬：重复的，合并；放错分支的，挪走；过期的，删掉；看起来像要求、实际不改变行为的，杀掉。Skill 不是越厚越专业，能让 Agent 稳定做对事才算数。 写在最后 如果团队已经开始给 Agent 写 Skill，先别急着多装十份。拿最常用的一份出来，看三件事：入口是不是清楚，主文件是不是能十分钟读完，删掉一段后 Agent 的结果会不会变。能把这一份改干净，后面的 Skill 才有可能越写越轻。先让一份 Skill 变好，比收集一堆 Skill 更可靠。 内容来源："Building Great Agent Skills: The Missing Manual"丨AI Engineer 原视频：https://www.youtube.com/watch?v=UNzCG3lw6O0 No access e4d3cadef81d460f98b63b51d5eb901a 00:00 如果你喜欢深度好文，试试用小程序将不方便立刻阅读的文章转成播客，用「听」的方式，稍后阅读，不再错过好文章⇣ ⇣ 关注我，每天为你更新硅谷最新的 AI 创业／科技播客总结，让你与前沿保持同频 ⇣ https://mp.weixin.qq.com/s/UZSGrouF... 🔗 原文链接： https://mp.weixin.qq.com/s/UZSGrouF... https://mp.weixin.qq.com/s/UZSGrouF... 原创 Capihom Capihom 晚点再听LaterCast2026年7月1日 21:23 北京 我们每天为你更新硅谷最新的 AI 创业与科技播客总结，让你与前沿保持同频。 全文约 4000 字，如果你现在没有时间，试试转成播客稍后再听 "区分好 Skill 和坏 Skill 的能力，只会越来越重要。" "Skill Hell 里，免费 Skill 到处都是，你却看不出它们怎么拼在一起。" "每增加一个模型可触发的 Skill，Agent 都要多背一份上下文负担。" 如果你最近用过 Codex、Claude Code，或者在团队里写过 AGENTS.md，大概已经碰到过一个新问题：给 Agent 的规则越来越多，效果却不一定越来越好。 一开始，大家会觉得答案很简单。模型没按预期做，就再补一条规则；写作不像人，就再加一段风格要求；代码改偏了，就再塞一份流程。几轮下来，Skill 越写越长，Agent 还是会漏读、误读，团队也不知道哪句话真的起作用。 AI Engineer 这场演讲讲的就是这件事。演讲者 Matt Pocock 维护着一个很受欢迎的工程 Skill 仓库，他把这类混乱叫做 Skill Hell。听起来像玩笑，放进工程团队就很现实：你要把代码审查、写 PRD、排查问题、做复盘这类工作交给 Agent，就得先学会写一份 Agent 真能执行的团队规程。否则 Skill 只是换了名字的提示词堆叠。 别再只往 Skill 里加规则 Pocock 说，开发者很擅长给自己制造新的困境。以前有 tutorial hell：教程看了一堆，还是拼不出完整项目。后来有 framework hell：框架更新太快，大家一直追新。现在轮到 skill hell。 Skill Hell 不像错误日志那样直接跳出来。它通常长得很体面：GitHub 上有一堆免费 Skill，看上去都能下载、改造、复用。问题在后面。你看不出哪份 Skill 设计得好，也看不出哪段文字只是摆在那里。 "组织还不知道怎样构建好 Skill，怎样把自己的操作规程变成 Agent 能做的事。" 放到日常工作里，就是这个场景：你把“我们怎么写需求、怎么查代码、怎么做测试”写进 Skill，以为 Agent 会自动学会团队习惯。结果它有时照做，有时跳过，有时读了也没变。Pocock 给出的审稿顺序很直接：先看谁触发，再看结构，再看文本有没有改变 Agent 的动作，最后删掉无效内容。 多装一个 Skill 很快，重新审一遍团队规程更慢，也更接近问题本身。团队规程原来是写给人看的，人会跳过废话，会用经验补空。Agent 不会。它只能读到你写下来的东西，也会被你写下来的废话拖住。 所以 Skill 写作不像写一篇说明文，更像给一个很勤快但很死板的新同事写交接。写少了，它不知道边界；写多了，它把边角料也当任务。Skill Hell 就从这里开始。一次失败往往不全是模型能力问题，团队也可能把交接写成了备忘录。 先决定谁来叫它 一份 Skill 写出来之后，有两种入口。一种是用户手动调用。文件在本地，你明确告诉 Agent：现在去读这份 Skill。另一种是模型自己调用。Skill 的 description 平时就放在 Agent 的上下文里，模型看到任务后自己判断要不要打开。 很多人会本能地喜欢第二种。少一步操作，看起来更聪明。但 Pocock 提醒，自动触发不是免费午餐。每多一个模型可触发的 Skill，Agent 每次请求都要多背一条描述，也要多一个选择。Skill 少的时候没感觉，几十上百个以后，模型会被一堆入口拖住。 "如果有 100 个模型可触发的 Skill，Agent 的上下文里就会有 100 条描述。" 所以团队要先分清两类 Skill。高频、低风险、边界清楚的，可以让模型自己发现；低频、影响大、需要人判断时机的，最好让人手动触发。比如“生成提交说明”可以自动一点，“重写客户需求文档”就不该悄悄发生；“给线上事故做复盘”也不该在上下文不完整时自动开跑。 很多团队会跳过入口设计，因为大家急着写正文。但入口选错了，后面写得再细也会别扭：要么 Agent 背太多无关描述，要么用户记不住什么时候该用哪份 Skill。 Pocock 自己更偏向用户触发。他承认这样会让使用者多记一点东西，但换来的是少一层不确定性。模型自动触发看起来省事，背后还要做另一件麻烦事：验证它有没有在该调用的时候真的调用。 公司内部 Skill 更需要这道判断。一个客户交付流程、一次线上事故复盘、一次安全审查，触发错了就会带来额外成本。与其把所有东西都塞进模型视野，不如先让人决定什么时候打开哪扇门。这个选择听起来很小，后面会影响每一次请求的上下文重量。 Skill.md 不该写成团队杂物柜 Pocock 拆 Skill 的方式很朴素：一份 Skill 里通常只有两类东西。步骤，告诉 Agent 接下来怎么走；参考材料，帮助 Agent 在某一步里查信息。 他举了一个 2PRD 的例子。这个 Skill 要把当前上下文整理成产品需求文档，所以步骤可以是：先找到相关材料，再和用户确认 test seam，最后写 PRD。参考材料则是 test seam 的定义、PRD 模板。一个负责行动，一个负责查阅。 团队最容易犯的错，是把这两类东西混在一起。今天有人加一段模板，明天有人补一段术语解释，后天又有人把一次项目复盘塞进去。半年后，Skill.md 变成谁都不敢删的公共文档。新人打开它，只能猜哪几段是命令，哪几段只是背景。 "每删掉一个词，都是从 Skill 成本里刮掉一个 token。" Pocock 的建议是把主文件写小。主文件只留公共入口：什么时候用，按什么顺序做，遇到分支时去哪里取材料。模板、样例、ADR、glossary，都可以放到旁边文件。Agent 需要时再取，人类 review 时也能一眼看出哪句话在控制行为。文件短，团队才敢改；团队敢改，Skill 才不会沉积。 他举的另一个例子是 domain modeling。这个 Skill 可能更新 glossary，也可能创建 ADR。ADR 模板只在其中一个分支里用，就没必要塞进主文件。主文件里留一句“需要 ADR 模板时去读这个文件”，已经够了。 对读者来说，可以马上拿自己的 Skill.md 做一个检查：如果某段内容只在一种情况里使用，它就应该被挪出去；如果某段内容每次都会用，才留在主文件里。这个动作很小，却能让 Skill 从“长文档”变回“可执行入口”。 一个短词，有时比一整段规则管用 很多 Skill 读起来都很认真：“不要一次性写完整功能”“请先做小范围验证”“尽量早点拿反馈”。这些话没有错，但 Agent 经常读完还是按老习惯做。 Pocock 给出的办法，是找 leading words，也就是能压住一整套做法的短词。他举的例子是 vertical slice。Agent 做大需求时，常常会先写数据库层，再写 schema，再写 API，再写前端，横着铺一层。vertical slice 这个词会把它拉回另一种工程习惯：先做一个能跑通的小切片，早点验证，再往外扩。 "我们把很多含义打包进一个相对短的短语里，然后在 Skill 里反复使用它。" Pocock 给了一个很实在的验证方式：你能从 Agent 的输出里看到它有没有学进去。当它开始说“先做一个薄的 vertical slice”，计划通常也会跟着变。团队写 Skill 时，与其堆十句近义提醒，不如先把几个能改变动作的词钉住。比如“vertical slice”“deletion test”“read first”这类词，短，但能把做法拉回来。以后看执行计划时，也能顺手检查这些词有没有出现。 注意，短词要稳定。今天叫 vertical slice，明天又叫 thin slice，后天改成 minimum path，模型读到的是一串近义词，动作反而不稳。好的 Skill 应该像团队黑话一样，少数几个词反复出现，每个人和 Agent 都知道它们指向什么。 团队里的工程口头禅也是这样。你说“先写测试”，很多解释都还要补；你说“红绿重构”，熟悉的人立刻知道先失败、再通过、再整理。Skill 里的短词也一样，它负责把一整套动作压进一个稳定入口。 让 Agent 一次只认真做一件事 Pocock 还讲了一个很常见的坑：Agent 在前置步骤上偷懒。最典型的是 plan mode。它通常要求 Agent 先问澄清问题，再生成计划。结果你会发现，它匆匆问两句，就急着交计划。 为什么？因为它已经看到了终点。只要最终目标写着“生成计划”，追问就容易被当成前奏，而不是任务本身。 他的做法是拆开。先用一个单独的 Skill 专门追问和读材料，比如 grill with docs：先把文档、仓库、历史 issue 和用户口述都问透，再交给下一份 Skill 写 PRD。这个阶段结束后，再进入写 PRD 的 Skill。Agent 当下只看到一件事，脚力就会多一点。 放到团队工作里，这条很实用。代码库探索、需求追问、失败复盘、资料核对，都很容易被最终交付物挤掉。要让 Agent 做扎实，就别把所有未来步骤一次性摊在它面前。先让它把当前阶段做厚，再把下一阶段交给它。Pocock 的 plan mode 例子，其实就是把“问清楚”和“写计划”拆开。下次写 Skill 时，可以先问一句：哪一步最容易被 Agent 敷衍过去？那一步就值得单独拿出来。 拆开流程，是为了保护前面那些容易被压缩的工作。人类同事也一样。如果你一边让他调研，一边告诉他最后要交三页方案，他很可能会按方案倒推材料。Agent 更会这样。它会朝着最终交付物跑，除非你暂时把终点藏起来。 删掉那些不会改变结果的句子 最后是删减。Pocock 提到几类坏味道：重复、沉积物、no op。 重复很好理解。同一个模板、同一条约束、同一个术语解释，散落在好几个地方，后面一定会改漏。沉积物更麻烦。团队维护 markdown 时，每个人都往里加一点，却没人敢删别人的旧话，Skill 就慢慢堆出一层灰。那些被反复复制的旧说明，最容易留下来。 "No op 是 Skill 里看起来有用、实际不会改变 Agent 行为的东西。" No op 最值得警惕。比如一个实现 Skill 里写了一大段“请写详细 commit message”。你把这段删掉，Agent 可能仍然会写一段像样的提交说明。那这段文字就没有改变行为，只是在占空间。 Pocock 的删除测试很简单：删掉一段，再看 Agent 的输出有没有变化。没变化，就别留。人读文档时会自动跳过废话，Agent 不会。它会把每一句都当成可能有用的上下文，哪怕那句话只是过去某次讨论留下的礼貌性提醒。 删除测试还能帮团队少吵架。很多文档里的句子不是错，只是没用。说它错，作者会防御；说“删掉后 Agent 行为没有变”，讨论就回到结果上。Skill 越短，留下来的每句话就越有责任。保留下来的句子，应该能让 Agent 多做一步、少犯一个错，或者少读一段无关材料。 Pocock 最后的扫尾清单其实很硬：重复的，合并；放错分支的，挪走；过期的，删掉；看起来像要求、实际不改变行为的，杀掉。Skill 不是越厚越专业，能让 Agent 稳定做对事才算数。 写在最后 如果团队已经开始给 Agent 写 Skill，先别急着多装十份。拿最常用的一份出来，看三件事：入口是不是清楚，主文件是不是能十分钟读完，删掉一段后 Agent 的结果会不会变。能把这一份改干净，后面的 Skill 才有可能越写越轻。先让一份 Skill 变好，比收集一堆 Skill 更可靠。 内容来源："Building Great Agent Skills: The Missing Manual"丨AI Engineer 原视频：https://www.youtube.com/watch?v=UNzCG3lw6O0 No access e4d3cadef81d460f98b63b51d5eb901a 00:00 No access e4d3cadef81d460f98b63b51d5eb901a 00:00 如果你喜欢深度好文，试试用小程序将不方便立刻阅读的文章转成播客，用「听」的方式，稍后阅读，不再错过好文章⇣ ⇣ 关注我，每天为你更新硅谷最新的 AI 创业／科技播客总结，让你与前沿保持同频 ⇣