打造 Claude Code 的那群人,公开了他们自己团队里是怎么用 Skills 的。这不是泛泛的"这样做比较好",而是把数百个 Skills 放进实战中跑了一遍后,把哪些有效、哪些失败全部总结了出来。执笔者是 Thariq Shihipar —— Claude Code 团队的工程师,也是凭《Claude Code is All You Need》在 X 上拿下 120 万浏览量的那个人。
这是什么?
Anthropic 一边在内部开发 Claude Code,一边也是自家最大的用户。9 个团队 —— 安全、法务、基础设施、前端、数据等 —— 各自打造自己的 Skills,总数已经到了数百个。
这次公开的内容主要有两块。第一,Claude Code 官方文档新增的 Best Practices 和 Skills 指南。第二,Thariq 在 X 上分享的 内部运营经验。如果说此前那份 33 页 PDF 指南讲的是"如何打造一个 Skill",那这次讲的就是 "把数百个 Skills 真刀真枪跑起来之后,才发现什么才是真正关键"。
核心信息很直白 —— 一个 Skill 的成败,几乎在动笔之前就决定了。别急着写代码,先把 3 个 use case 写清楚再说。
有什么不同?
之前那份 33 页指南是"Skill 是什么、怎么做"。这次公开的级别完全不同 —— 讲的是 实战中什么有效、什么失败,以及 团队规模下如何管理。
| 原 33 页指南 | 内部实战手册(本次公开) | |
|---|---|---|
| 焦点 | Skill 概念与制作方法 | 运营数百个 Skills 总结出的模式与反模式 |
| 设计原则 | SKILL.md 格式说明 | 先定 3 个 use case → 再动笔 |
| 品质管理 | 基本测试提及 | 触发 / 功能 / 性能三阶段验证体系 |
| 团队共享 | 仅提及路径 | Enterprise → Personal → Project 优先级体系 + 插件发布 |
| 上下文管理 | 简略提及 | character budget 2% 规则 + 500 行上限 + progressive disclosure |
| 触发控制 | 基本说明 | 用 Hook 强制触发 + disable-model-invocation 分离 |
特别值得一提的是 70% 法则。这是 Anthropic 内部各团队普遍出现的模式 —— Claude Code 能稳定完成约 70% 的实现工作,剩下的 30% 由人来做。而这 30% 恰恰是 Skill 的设计、验证循环、边界情况处理。
上手指南
- 先写下 3 个 Use Case
在动手做 Skill 之前,先把"谁、说什么、应该得到什么结果"以 3 个场景的形式写下来。Anthropic 说,一旦跳过这一步,Skill 品质就会断崖式下跌。场景示例:"帮我 review 这个 PR" → 3 个并行 agent 分别做安全 / 代码质量 / 效率审查 → 整合报告 - 把 description 写得精准
Claude 用"progressive disclosure"来加载 Skills。先把 name + description 放进系统提示(约 100 tokens),等用户请求匹配上了,再去读 SKILL.md 全文。 description 含糊就触发不了,太宽泛又会在不该用的时候被调用。 - 在 body 里放入验证循环
这是 Anthropic 强调最多的一条。把"执行 → 验证 → 修正 → 再验证"这个循环以清单的形式写进 Skill 正文。 比如代码生成类的 Skill,就要明确写出"生成后运行 lint → 跑测试 → 失败就修 → 再跑一遍"。 - 保持 500 行以内
SKILL.md 一旦太长,Claude 就会漏掉指令。详细内容放到 references/ 文件夹里,SKILL.md 只保留目录和核心指示。 参考文件如果很长,顶部必须放目录 —— 这样 Claude 用 head -100 读的时候才能看清结构。 - 分享给团队
把 Skill 放进.claude/skills/并提交到 git,整个团队就都能用了。 个人用的放~/.claude/skills/,全组织范围则用 managed settings 发布。优先级顺序是 Enterprise > Personal > Project。
Anthropic 从实战中学到的 5 条教训
以下是从官方文档与 Thariq 的分享中提炼出的、运营数百个 Skills 所得的核心经验。
教训 1:不要在 SKILL.md body 里写"When to Use"
触发判断在 description 阶段就已经完成了,body 是在那之后才被加载的。在 body 里写"本 Skill 用于……",等于是已经被触发之后才去读它 —— 纯粹浪费上下文。body 里只写"怎么执行"就够了。
教训 2:有副作用的 Skill 一律改成手动触发
设置 disable-model-invocation: true。部署、提交、发 Slack 消息这类 Skill,绝不能让 Claude 擅自判断"代码好像准备好了,我去部署吧"然后就自动执行。
教训 3:Skill 太多,就一个都跑不动
Claude 在上下文窗口 2% 的预算(最少 16,000 字符)内管理 Skill 列表。一旦超出这个预算,一部分 Skills 会被直接排除在外。用 /context 可以查看。
教训 4:用 Hook 提高触发率
Skill 没被调用,最大的原因就是 Claude 没匹配上 description。这时候 Hook 就派上用场了 —— 可以在用户输入里直接追加 Skill 推荐。比如听到"帮我实现个功能"时,自动插入"CRITICAL SKILLS: session-management"。
教训 5:用 context: fork 保护主上下文
调研、审查这类 Skill 会读大量文件,很容易污染主上下文。设置 context: fork 后,它会在 sub-agent 里隔离执行,只把结果摘要回传。
实战 Skill 结构示例
基于 Anthropic 实际使用的模式,整理出在团队规模下行之有效的 Skill 结构。
| Skill 类型 | 示例 | 关键设置 | 位置 |
|---|---|---|---|
| 参考型(知识) | api-conventions、legacy-system-context | user-invocable: false(仅 Claude 调用) | Project (.claude/skills/) |
| 任务型(执行) | deploy、fix-issue、pr-summary | disable-model-invocation: true | Project (.claude/skills/) |
| 个人工作流 | explain-code、debug-session | 默认(自动+手动都可) | Personal (~/.claude/skills/) |
| 组织标准 | code-review、security-audit | 通过 managed settings 发布 | Enterprise |
这里的关键在于 把"参考型 Skill"和"任务型 Skill"划清界线。 参考型是 Claude 用作背景的知识,任务型则是用户明确触发的工作流。两者混在一起,Skill 就会在不该用的时候被调用,或者在真需要时又调不起来。
与此前 claude-skills-guide 一文的区别
上一篇(Claude Skills 33 页指南全解)讲的是 Anthropic 公开的 PDF 指南 —— 重点在 Skill 的概念、SKILL.md 的写法和基本结构。这篇讲的是其后才出现的 内部实战经验,综合了官方文档更新、Thariq 的 X 长帖以及社区分析。
