构建 Claude Code 的经验：我们如何使用 Skills
出处
来源：原网页
一句话结论
一个真正有用的 Skill，不是多写几段说明，而是把“高价值规则、脚本、参考资料、验证流程和记忆机制”封装进可按需调用的工作单元里。
一张图看懂
核心观点
1. Skills 不是 Markdown 文件，而是 Agent 的可执行工作包
文章先纠正了一个常见误解： 很多人以为 Skill 只是一个写提示词的 markdown。
但作者强调，真正有价值的 Skill 是一个目录，可以包含：
- 说明文档
- 脚本
- 模板
- 参考资料
- 资源文件
- 配置文件
- 钩子（hooks）
- 持久化数据
也就是说，Skill 的本质不是“告诉 Agent 怎么做”，而是“给 Agent 一整套做事所需的环境部件”。
2. 好 Skill 通常落在清晰类别里，差 Skill 往往边界混乱
Anthropic 团队把内部大量 Skills 梳理后，归纳出了 9 类高频模式：
- 库与 API 参考：帮助正确使用内部库、CLI、SDK
- 产品验证：自动验证功能是否真的可用
- 数据获取与分析：接数据库、指标系统、监控系统
- 业务流程与团队自动化：自动生成站会、工单、周报等
- 代码脚手架与模板：生成样板与初始化结构
- 代码质量与审查：代码风格、对抗式审查、测试实践
- CI/CD 与部署：PR babysit、部署、回滚、cherry-pick
- 运维手册：根据症状跨工具排查并生成结构化报告
- 基础设施运维：有护栏地执行高风险运维动作
这个分类的价值不只是“整理”，而是帮助团队判断： 我们缺的不是更多 Skill，而是哪一类关键能力还没被产品化。
3. 最有信息密度的部分，通常不是概述，而是“踩坑点”
作者明确说，任何 Skill 里价值最高的部分通常都是 gotchas（踩坑点）章节。
因为这些内容：
- 不是模型通识
- 不是仓库里随处可见的常识
- 恰恰是 Claude 反复犯错后才被归纳出来的“高密度经验”
这对 Skill 设计很关键： 不要重复写显而易见的背景知识，重点写那些能打破模型默认思维模式的信息。
4. Skill 设计的关键，不是塞满上下文，而是做好渐进式披露
文章非常强调文件系统式组织和 progressive disclosure（渐进式披露）。
核心思想是：
- 不要一次性把所有内容塞进主说明里
- 只告诉 Agent 有哪些文件、哪些参考、哪些模板可读
- 让 Agent 在需要时再读取对应内容
比如：
references/api.md放详细 API 签名assets/放模板或样例scripts/放辅助脚本
这能显著降低上下文负担，也让 Skill 更可维护。
5. 约束要有，但不要把 Agent 限死
文章指出一个很实际的问题： Claude 往往会努力服从指令，所以 Skill 如果写得过于具体，会让它在实际变化场景中失去适应能力。
因此好的 Skill 需要平衡：
- 给足关键规则
- 保留具体执行自由度
换句话说： Skill 不是把 Agent 变成死板脚本，而是给它稳定边界和高价值默认。
6. 很多 Skill 其实需要“初始化配置”与“记忆能力”
一些 Skill 并不是开箱即用，而需要先知道：
- Slack 发到哪个频道
- 使用哪个项目 ID
- 某些系统的 schema 或 dashboard ID 是什么
作者建议把这类配置放到 Skill 目录下的 config.json，必要时由 Agent 先向用户询问。
更进一步，有些 Skill 还应该保留自己的历史记录，例如：
- standup-post 保存以前生成过的日报/站会
- 后续运行时读历史，知道什么是 delta
这说明一个重要点： Skill 不只是能力扩展点，也可以成为局部记忆单元。
7. 最强大的 Skill 往往不是“写得好”，而是“内置了代码与脚本”
作者特别强调： 给 Agent 最强的工具之一，就是代码本身。
如果 Skill 内置了：
- 数据抓取函数
- 查询助手
- 分析脚本
- 模板生成器
Agent 就不必每次重新发明轮子，而能把精力用在：
- 决定下一步做什么
- 如何组合现有能力
- 如何完成更复杂的编排
所以 Skill 的高级形态，本质上更接近一个“微型工具包”。
8. On-demand hooks 是高价值但不应常驻的护栏
文章提到按需钩子（On Demand Hooks）很适合处理：
- 危险命令拦截
- 限定写入范围
- 某种只在特定任务中才需要的检查
例如：
/careful：拦截rm -rf、DROP TABLE、force-push 等危险操作/freeze：禁止在指定目录之外写文件
这类机制的意义在于： 不是把所有护栏永久打开，而是在需要时临时加强系统约束。
9. Description 字段不是简介，而是触发条件说明
这是特别容易被忽略的一点。
作者说，Claude 在会话开始时会扫一遍所有 Skill 的 description，判断“这个请求该不该调用这个 Skill”。 所以 description 不该写成功能介绍，而应写成：
- 什么场景下触发
- 遇到什么请求时调用
- 哪种任务特别适合它
一句话： description 是给模型做路由判断的，不是给人看的营销文案。
10. Skill 生态的重点不只是创建，还包括分享、审核、组合与度量
文章后半段其实在讲 Skill 的组织治理：
- 小团队可以直接把 Skill 提交进仓库
- 大团队更适合做插件市场
- 新 Skill 先在小范围沙盒试用，再决定是否推广
- 需要避免低质量或重复 Skill 泛滥
- 可以记录 Skill 使用情况，观察哪些被频繁调用、哪些几乎没人用
这说明当 Skill 数量上来后，难点不再是“怎么写一个”，而是： 怎么让整个 Skill 体系可发现、可维护、可演化。
核心脉络
这篇文章真正想传达的逻辑
- Claude Code 的 Skills 已经成为重要扩展点
- 但 Skill 价值不在“加一段提示词”，而在封装可执行能力单元
- 好 Skill 有明确类别、边界和高密度经验
- 文件系统、脚本、配置、记忆、钩子共同构成 Skill 的真实能力
- 团队规模扩大后，还要解决分发、审核、组合与度量问题
对实际工作的启发
对个人使用 Skill
- 不要一上来就写大而全的说明书
- 先做一个能解决明确问题的小 Skill
- 重点补“踩坑点”和“参考资料”而不是废话背景
- 能脚本化的尽量脚本化
对团队推广 Skill
- 先做高频、重复、容易出错的场景
- 给 Skill 明确分类，不要职责混杂
- 对共享 Skill 建审核机制，否则很快失控
- 记录使用数据，别靠感觉判断有没有价值
对 Skill 设计本身
如果把这篇文章压缩成一个设计原则，就是： Skill = 规则 + 文件系统 + 工具脚本 + 记忆 + 按需护栏。
我认为最值得记住的三句话
- Skill 不是 markdown，而是可执行工作包。
- 最值钱的信息通常是“踩坑点”，不是通用说明。
- description 的职责不是介绍功能，而是告诉模型“什么时候该用我”。
原文标记
这是一篇宝玉翻译并扩展导读的 X 长文，原始内容来自 Anthropic Claude Code 团队成员 Thariq Shihipar。文章兼具一线经验总结与方法论归纳，尤其适合已经开始做 Agent / Skills 体系但还没有形成设计规范的人。