01｜好 Skill 是踩坑长出来的
Thariq Shihipar 是 Claude Code 团队的 Builder。
今年 3 月，他写了一篇复盘，讲 Anthropic 内部数百个 Skill 是怎么使用的。后来，这篇文章又发布在 Claude 官方博客上。
我把这篇文章里的实践整理成了一个配套 Skill，叫 Build Reliable Agent Skills，已经放在 GitHub。仓库名是 Elisedai1013/build-reliable-agent-skills-skill。这期最后，我会告诉你可以怎么用它。
但我们先不急着看答案，先按 Thariq 的顺序，看 Anthropic 到底学到了什么。
02｜数百个 Skill 之后，他们在问什么
截至 7 月 14 日，这篇文章已经有超过 692 万阅读、接近 4.4 万收藏。
它一开头问了三个很实际的问题：什么样的 Skill 值得做？一个 Skill 应该怎么组织？什么时候适合分享给其他人？
这些问题不是来自纸上讨论。Anthropic 当时已经有数百个 Skill 在真实使用中。文章后面的结论，都是他们用过以后留下来的经验。
03｜Skill 不是一份 Markdown
Thariq 先纠正了一个常见误解：Skill 不只是一个 Markdown 文件。
它是一个文件夹。里面可以有指令，也可以有脚本、参考资料、数据和输出模板。Claude 会先看到入口，再根据任务需要，去读取或运行里面的内容。
在 Claude Code 里，Skill 还可以注册 Hook。你可以把 Hook 理解成一条只在特定场景出现的自动规则，比如碰到危险命令时直接拦住。
所以，Skill 不是把 Prompt 写得更长，而是给 Agent 准备一套可以查、可以运行、也可以约束它的工作环境。
04｜Anthropic 把 Skill 分成九类
接下来，Thariq 盘点了 Anthropic 内部的 Skill，大致分成九类。
有教 Claude 使用内部库和 API 的；有验证产品是否真的正常工作的；也有取数分析、团队自动化、代码脚手架、代码审查、部署、故障排查和基础设施运维。
这份分类不一定适合所有团队。Thariq 真正想提醒的是：好用的 Skill 通常能清楚地落在一类里。一个 Skill 如果又要查数据、又要改代码、又要部署，还要发通知，Agent 反而容易不知道重点是什么。
先让一个 Skill 把一类事情做好，比把所有能力塞进去更重要。
05｜验证类 Skill，效果最容易看见
九类里面，Anthropic 认为效果最容易衡量的是产品验证类 Skill。
比如测试注册流程，不是让 Claude 看一眼代码，然后说“应该没问题”。而是让它真的打开浏览器，走完注册、邮箱验证和新手引导，并在每一步检查状态。
测试结账也一样。页面显示成功，不代表付款流程真的成功，还要确认发票有没有进入正确状态。
Thariq 甚至说，让一名工程师专门花一周，把验证类 Skill 做好，都可能很值得。因为它解决的是 Agent 最常见的问题之一：做了很多动作，却没有证明结果真的成立。
06｜九类 Skill，其实都在补组织上下文
其他八类看起来差别很大，其实有一个共同点：它们都在补 Claude 原本不知道的组织上下文。
比如，内部 API Skill 会记录自家库的特殊用法；取数 Skill 会告诉 Claude 正确的表、字段和 Dashboard；Runbook 会把一个告警带到对应的排查步骤；部署 Skill 会写清灰度、冒烟测试和回滚方式。
这些内容的价值，不是教 Claude 一遍通用知识，而是告诉它：在我们这家公司、这套系统和这个流程里，事情到底应该怎么做。
07｜不要把 Claude 已经知道的再写一遍
讲完哪些 Skill 值得做，Thariq 开始讲怎么写。
第一条是：不要陈述显而易见的内容。
像“代码要清晰”“记得处理异常”这样的句子，Claude 本来就知道。把它们写进 Skill，只会占用上下文，并没有增加新的能力。
真正值得写的，是能把 Claude 从默认做法里推出来的信息。比如 Anthropic 的前端设计 Skill，会明确避开一些已经被模型用得很套路的设计选择。它不是重新教 Claude 什么是设计，而是在校准它的设计判断。
08｜Gotchas 是 Skill 里信号最高的部分
Thariq 认为，一个 Skill 里信号密度最高的部分，通常是 Gotchas。
Gotchas 就是 Claude 真正踩过的坑。比如，subscriptions 表只会追加新记录，所以要找版本号最高的一行，而不是创建时间最近的一行；又比如，测试环境即使 Stripe Webhook 没处理成功，也可能返回 200，必须去 payment_events 看真实状态。
这些细节，模型不可能凭通用知识猜出来。它们来自真实错误，也应该随着新的错误持续补充。
所以标题里说“好 Skill 是踩坑长出来的”，对应的就是原文这层意思：不是先写一份完美手册，而是把反复出现、又确实有用的经验留下来。
09｜把文件系统当成上下文工程
第二个很重要的写法，是使用文件系统和渐进式披露。
入口文件不用塞满所有内容。它可以告诉 Claude：详细的 API 在 references/api.md，输出模板在 assets，固定动作在 scripts。Claude 用到哪一部分，再去打开哪一部分。
Thariq 把整个文件系统都看成 Context Engineering。简单说，就是别一开始把所有信息都倒给 Agent，而是把资料放在合适的位置，让它在需要时自己找到。
这样既节省上下文，也让每类内容更容易维护。
10｜给信息和护栏，但别把 Claude 锁死
不过，写得具体不等于规定得越死越好。
Thariq 提醒，Claude 通常会尽量遵守指令。Skill 又会被反复使用，如果规则写得过于具体，它在新场景里就可能失去判断空间。
更合适的做法，是给它必要的信息和护栏，同时允许它根据任务调整。
还有一些 Skill 第一次运行时，需要先向用户拿到配置。比如自动发 Standup，要先知道发到哪个 Slack 频道。可以把这些信息保存在 config.json；没有配置时，再让 Agent 询问用户，而不是每次都重新问。
11｜Description 不是摘要，而是触发条件
接下来这一点很容易被忽略：Description 是写给模型看的，不是写给人看的。
Claude Code 开始一个 Session 时，会先看到所有 Skill 的名称和 Description，再判断当前请求该不该调用某个 Skill。
所以 Description 不是一句漂亮的内容摘要，而应该写清楚用户会在什么情况下需要它，可能会说哪些词，任务有什么特征。
如果一个 Skill 明明很有用，却总是没有被调用，问题可能不在正文，而在 Description 没有把触发场景说清楚。
12｜Skill 还可以记住过去
Skill 还可以保存数据，形成一种轻量的记忆。
比如，一个负责发布 Standup 的 Skill，可以把每次内容写进只追加的日志。下一次运行时，Claude 先读历史，就知道今天真正发生了哪些变化，不会把昨天的内容再说一遍。
这些数据可以放在文本、JSON，甚至 SQLite 里。重点不是让 Skill 拥有一套复杂的长期记忆系统，而是把下一次任务确实会用到的历史留在稳定的位置。
13｜把代码和按需 Hook 也放进 Skill
Thariq 还强调，能交给 Claude 的最强工具之一，就是代码。
如果一个动作每次都要重新写一遍，不如把稳定的脚本和函数放进 Skill。Claude 就可以把精力用在组合这些能力、判断下一步，而不是反复生成样板代码。
对于高风险场景，可以使用按需 Hook。比如 /careful 只在接触生产环境时启用，拦截 rm -rf、DROP TABLE、强制推送这类危险操作；任务结束后，它也随 Session 一起结束。
这比在文档里反复写“请小心”更可靠。
14｜先在小范围证明价值，再进入 Marketplace
写好以后，Skill 怎么分享？原文给了两条路径。
小团队可以直接把它放进仓库的 .claude/skills。团队和仓库变多以后，可以做成 Plugin，通过内部 Marketplace 分发。
Anthropic 也没有一个中央团队，先替所有人审核出所谓“完美 Skill”。有人会先把 Skill 放在 GitHub 的 Sandbox 目录，再到 Slack 邀请同事试用。真的有人持续使用以后，作者再提交 PR，把它移进 Marketplace。
也就是说，进入正式分发渠道之前，先让真实使用证明它有价值。
15｜Skill 可以组合，也应该被衡量
不同 Skill 之间还可以组合。虽然现在没有原生的依赖管理，但可以在指令里直接引用另一个 Skill；只要对方已经安装，Claude 就能继续调用。
Anthropic 也会衡量 Skill 的真实使用情况。他们用 PreToolUse Hook 记录公司内部的调用，看看哪些 Skill 经常被使用，哪些按理应该出现，却一直触发不足。
这说明 Skill 不是写完就结束的文档。它更像一个内部产品：要被发现、被使用，也要通过数据看它是不是真的有帮助。
16｜从几行指令和一个 Gotcha 开始
文章最后，Thariq 没有给一套复杂的制作流程。
他说，Anthropic 很多最好的 Skill，一开始只有几行指令和一个 Gotcha。Claude 遇到新的边界情况，团队再把真正有用的经验加进去，它才一点点成熟。
如果你也想开始，可以先找一个反复发生、而且 Claude 确实踩过坑的任务。把任务材料或现有 Skill 交给我做的 Build Reliable Agent Skills，它会帮你整理触发场景、缺少的团队经验、可以复用的脚本，以及怎么验证结果。
完整 Skill 已经放在 GitHub：Elisedai1013/build-reliable-agent-skills-skill。这一页可以直接打开。
最重要的不是一次把它写完，而是先让它进入真实工作，再看它还缺什么。
我是 Elise，这里是 AI Builders 解读。
