Skills 不是 Markdown，而是能力包
flowchart LR
A["Skill"] --> B["SKILL.md"]
A --> C["references/"]
A --> D["scripts/"]
A --> E["assets/"]
A --> F["hooks"]
A --> G["memory / config"]很多人第一次看到 Claude Code Skills，会把它理解成“给模型多写几段 Markdown 提示词”。这个理解太轻了。真正好用的 skill，更像一个可被 Agent 发现、读取、执行、复用和迭代的能力包。
出处与延伸阅读：
- 原始出处：@trq212 的 X thread：Lessons from Building Claude Code: How We Use Skills
- 本文基于用户提供的本地译文《Claude Code 构建经验：我们如何使用 Skills》整理和改写。
- 相关文档：Claude Code Skills、Plugin marketplaces
这篇文章会讲什么
Skills 最容易被低估。
因为它表面上只是一个文件夹，里面常常有一个 SKILL.md。于是很多人会自然地把它当成“提示词模板”。
但从 Claude Code 团队的实践看，Skills 更像是组织能力的封装单元。它可以包含：
- 说明文档
- 示例代码
- gotchas
- 验证脚本
- 模板文件
- 配置文件
- hooks
- 历史日志
- 数据访问方法
这篇文章会按三个问题展开：
- 什么样的 skill 值得做
- 怎么写一个真的好用的 skill
- 团队里怎样分发、组合和衡量 skill
先说结论
好 skill 不是“更多上下文”，而是“更好的上下文入口”。
它不应该把所有知识一次性塞给模型，而应该让模型在需要时逐步发现：
- 先知道这个 skill 适合什么任务
- 再读最短的工作说明
- 需要细节时去
references/ - 需要执行时用
scripts/ - 需要输出时套
assets/模板 - 需要强约束时启用 hooks
- 下次复用时参考历史记录
所以 skill 的本质不是 Markdown。
它是把组织里的经验、工具、流程、模板和限制，包装成 Agent 能理解和调用的一种能力。
什么样的 Skill 值得做
不是所有知识都值得做成 skill。
如果一段内容只是普通编程常识，模型本来就知道；如果一段流程一年只用一次，也未必值得维护成公共能力。最适合做 skill 的，通常是那些重复出现、容易出错、组织内部有特殊规则的任务。
Claude Code 团队总结出的几类 skill 很实用。
1. Library 与 API 参考
这类 skill 教模型正确使用某个库、CLI、SDK 或内部平台。
它不应该只是复制官方文档，而应该写那些模型容易踩错的地方：
- 内部封装和公开 API 哪里不同
- 哪些参数不能组合
- 哪个 helper 已经过时
- 真实项目里推荐哪种写法
- 常见错误应该怎么修
对企业来说，这类 skill 很适合封装内部平台知识。它能减少“模型写了看似正确、但不符合内部约定的代码”。
2. 产品验证
这是最值得投入的一类。
很多 Agent 失败，不是不会写代码，而是不会验证代码真的工作。验证类 skill 可以告诉模型如何用 Playwright、tmux、测试账号、测试卡、状态断言、录屏等方式验证产物。
好的验证 skill 不只是说“跑一下测试”，而是明确：
- 入口命令是什么
- 预期状态是什么
- 失败时看哪些日志
- 哪些结果才算通过
- 是否需要截图、录屏或程序化断言
如果一个团队只能先做一类 skill，我会优先做验证类。它能直接提升 Agent 产出的可信度。
3. 数据获取与分析
这类 skill 把数据仓、监控、仪表盘和常用查询路径封装起来。
它解决的问题不是“模型会不会写 SQL”，而是：
- 哪张表是 canonical source
- user_id 到底在哪个字段
- 事件漏斗应该怎么 join
- dashboard 的 datasource UID 是什么
- 某个指标口径是否已经变过
这些知识通常散落在团队脑子里。做成 skill 后，Agent 才能少猜。
4. 团队流程自动化
比如 standup、weekly recap、建 ticket、发 release note、同步 Slack。
这类 skill 的价值在于压缩重复流程，并保持输出一致。
它们往往不需要特别复杂，但很适合带一点“记忆”：上次发过什么、这周新增了什么、哪些 ticket 已经同步过。一个追加日志文件，有时就能让 skill 稳定很多。
5. 脚手架与模板
当你的团队有固定代码结构、迁移格式、服务模板、PR 模板时，skill 可以把自然语言需求和代码模板结合起来。
纯脚本适合完全确定的生成；skill 适合“有模板，但仍需要理解需求”的生成。
比如新建一个内部 service，既要固定认证、日志、部署配置，又要根据用户说的业务目标生成 handler、schema 和测试。这里 skill 比单纯 generator 更灵活。
6. 质量审查与代码规范
这类 skill 适合把 review 经验固化下来。
尤其是那些模型默认做得不好的地方：
- 项目特有代码风格
- 测试边界
- 安全审查
- 错误处理
- 性能风险
- 迁移兼容性
如果可能，最好把确定性的部分交给脚本，把需要判断的部分交给模型。
7. CI/CD、Runbook 与运维
部署、回滚、告警排查、日志关联、资源清理，都可以做成 skill。
但这类 skill 要更谨慎，因为它们往往接近生产系统。
越是危险的 skill，越应该带：
- 明确环境识别
- 只读优先
- destructive action 前确认
- dry-run
- 审计日志
- hooks 护栏
Agent 能做运维，不代表它应该默认拥有运维权限。
写 Skill，少写显而易见的东西
一个常见错误，是把 skill 写成“给新人看的入门文档”。
这对模型不一定有帮助。
Claude 本来就知道大量通用知识。你再写一遍“React 组件应该可复用”“SQL 查询要注意性能”，只会增加上下文负担。
Skill 应该优先写模型不知道、容易错、和你组织强相关的东西。
更具体一点：
| 不值得写 | 更值得写 |
|---|---|
| 如何写单元测试 | 这个仓库哪些模块必须用集成测试 |
| 如何调用 REST API | 内部 API 哪些字段语义容易误解 |
| 如何写迁移 | 线上迁移哪些表不能锁、必须分批 |
| 如何做设计 | 这个产品设计系统禁止哪些套路 |
好 skill 的内容应该有“把模型从默认思路里拉出来”的能力。
Gotchas 是最高信号密度区域
如果一个 skill 只能写一段内容，我会写 gotchas。
因为 gotchas 通常来自真实失败：
- Claude 总是把某个字段名写错
- 某个测试命令在本地和 CI 不一样
- 某个内部库看似支持异步，其实不支持
- 某个部署命令在 prod 必须先锁流量
- 某个设计组件不能嵌套使用
这些内容比“正向说明”更有价值。
正向说明告诉模型怎么做；gotchas 告诉模型不要怎样做，以及为什么过去会失败。
一个 skill 应该随着失败案例不断变厚，而不是一开始就追求完整。
很多有生命力的 skill，一开始可能只有几行说明和一个 gotcha。真正让它变强的，是团队持续把模型踩过的坑补进去。
把文件系统当作上下文工程
Skill 是文件夹，不是单文件。
这件事很关键。
如果所有内容都写进 SKILL.md，模型每次触发 skill 都要读很多不一定需要的东西。更好的方式是分层：
my-skill/
├── SKILL.md
├── references/
│ ├── api.md
│ └── gotchas.md
├── examples/
│ └── happy-path.ts
├── scripts/
│ └── verify.ts
└── assets/
└── report-template.mdSKILL.md 只做入口：
- 什么时候用这个 skill
- 最短流程是什么
- 目录里有哪些资料
- 需要细节时读哪个文件
- 需要执行时跑哪个脚本
这样模型可以按需读取，形成 progressive disclosure。
这比把一切塞进上下文更干净，也更符合 Agent 的工作方式。
给脚本，而不是让模型每次重写脚本
如果某个动作需要稳定执行，就不要让模型每次现场发明。
比如：
- 拉取漏斗数据
- 跑一套浏览器验证
- 生成迁移文件
- 检查 PR 风险
- 对比部署前后错误率
这些动作很适合放在 scripts/ 里。
模型的任务就从“重新写一段工具代码”，变成“理解当前目标，然后组合已有脚本”。
这会显著降低随机性。
一个好 skill 不是让模型少思考，而是让它把思考花在更高层：
- 现在应该验证什么
- 哪个脚本适合
- 输出说明了什么
- 下一步该不该继续
不要把 Claude 限死
Skill 还有另一个常见问题：写得太死。
因为 skill 会被复用，作者很容易把某一次成功经验写成固定流程。但真实任务会变化，模型也需要根据上下文调整。
比较好的写法是给原则、边界和决策依据，而不是强迫每一步都固定。
例如：
- 不要写：“永远先运行 A，再运行 B。”
- 可以写：“如果任务涉及登录态，先运行 A；如果只是静态页面变更，可以直接运行 B。”
Agent 需要被约束，但不应该被机械化。
Skill 的目标不是把 Claude 变成 shell script，而是给它一个更懂组织上下文的工作方式。
Description 是写给模型看的
很多人会把 description 写成人类摘要：
用于处理前端相关任务。
这对模型帮助不大。
Description 更应该写成触发条件：
当任务涉及修改 Web UI、组件样式、响应式布局、视觉质量检查或设计系统一致性时使用。使用前先读取
references/design-rules.md，完成后运行scripts/visual-check.ts。
因为 Claude Code 会通过 skill 列表里的 description 判断什么时候启用某个 skill。
换句话说，description 不是封面文案，而是路标。
路标写得含糊，skill 就会触发不足或误触发。
分发：小团队进仓库，大团队上 Marketplace
对于小团队，把 skills 放进仓库通常已经够好。
比如：
.claude/skills/
frontend-design/
checkout-verifier/
migration-helper/好处是简单、透明、和代码一起版本管理。
但随着团队变大，问题也会出现：
- 每个仓库都塞很多 skill
- 模型上下文负担变重
- 重复 skill 越来越多
- 没人知道哪个是官方推荐
- 坏 skill 扩散得很快
这时内部 plugin marketplace 更适合。它允许团队成员按需安装，也能做审核、推荐、版本管理和使用统计。
Skill 分发不是越自由越好。太自由会变成提示词碎片化；太中心化又会让好东西出不来。
比较健康的模式是：
- sandbox 里鼓励试验
- 有 traction 后申请进入 marketplace
- 进入前做轻量审核
- 发布后继续看使用数据和反馈
衡量 Skill 效果
一个 skill 发布后，不应该只靠感觉判断好不好。
至少可以看几类信号：
| 信号 | 说明 |
|---|---|
| 触发率 | 模型是否知道什么时候用它 |
| 完成率 | 用了以后任务是否更容易成功 |
| 人工接管率 | 是否减少用户纠偏 |
| 脚本失败率 | skill 里的工具是否稳定 |
| 反复编辑次数 | 输出是否接近可用 |
| 新 gotcha 数量 | 是否还在暴露边界 |
Claude Code 团队提到可以用 PreToolUse hook 记录 skill 使用情况。这类日志非常有价值，因为它能告诉你两类问题：
- 很多人用，说明值得继续打磨
- 很少触发，可能 description 写错，或者根本不是好 skill
不要把 skill 当成写完就结束的文档。它更像内部工具，需要观测和迭代。
小结
Skills 的价值，不在于多给模型一段提示词。
它真正解决的是一个组织问题：
如何把团队里那些隐性的经验、脚本、模板、验证方法和风险边界，变成 Agent 可以复用的能力？
做得好的 skill，会让 Claude 更像一个熟悉你团队的新同事。
它知道哪里有文档，知道哪些坑不能踩，知道怎么验证，知道什么时候该问人，知道哪些动作需要护栏。
这比单纯“多给上下文”高级得多。
未来很多团队的 Agent 能力差距，可能不只来自模型和工具，而来自这些看似不起眼的 skills：谁更会把组织经验封装成可复用能力，谁的 Agent 就越像真正进了团队。