一、先破除那个最贵的误解

很多人一听到 Skill（技能），第一反应是：不就是写个 .md 文件，告诉 Claude 该怎么做事吗？

这样理解是错的，而且代价很大。

Anthropic 官方对 Skill 的定义是一个文件夹，而不是一个文件——它里面可以装指令、脚本、资源文件、数据、模板，甚至配置信息。更关键的是，Skill 还能注册动态钩子（Hook），在特定工具被调用的时机触发特定行为。换句话说，Skill 不只是「给 Claude 的知识」，它是给 Claude 的工具、记忆和行为约束体系的集合。把它理解成一张 Markdown，就像把瑞士军刀当开瓶器来用——没出错，但你只用了一个功能。

这个区分的意义在于：一旦你把 Skill 当成「一个文档」，你就会拼命往一个 md 里塞东西，最后塞成一坨连模型都读不动的长文。而把它当成「一个文件夹」，你才会去认真想：哪些该做成脚本、哪些该按需读取、哪些该放模板。这恰恰是 Skill 真正的威力所在。

二、Anthropic 把几百个 Skill，归成了 9 类

Anthropic 在梳理完内部上百个活跃 Skill 之后，发现它们能干净地落进九大类别。而且他们有个非常重要的观察：最好的 Skill 只干一类事；那些什么都想干的 Skill，常常横跨多个类别，反而把智能体搞糊涂了。这九类大致是——

1. 库与 API 参考：讲清某个内部库、CLI 或 SDK 怎么用，重点是把边界情况和坑写明白（比如内部计费库的 various footguns）。
2. 产品验证：写完代码怎么验证它真的跑通了，常配合 Playwright、tmux 等工具。原文特意点名，这一类对产出质量的提升是最可量化、最明显的。
3. 数据获取与分析：接上数据仓库和监控体系，内置凭证、仪表盘 ID、常用查询模板和字段映射。
4. 业务流程与团队自动化：把重复的协作流程压成一条命令，比如聚合日报、按固定 schema 建工单、生成周报。
5. 代码脚手架与模板：按框架生成样板代码，注解、配置都预先填好。
6. 代码质量与评审：强制执行规范、辅助 review，甚至能派一个全新视角的子 Agent 来做「对抗式评审」挑刺。
7. CI/CD 与部署：盯 PR、重试不稳定 CI、渐进式放量、指标恶化时自动回滚。
8. 运维手册（Runbook）：从一个症状出发（一条告警、一个报错特征），多工具联动排查，最后产出结构化报告。
9. 基础设施运维：带护栏的运维操作，比如清理孤儿资源、依赖审批、成本核查。

这九类不用背，关键是那个原则：一个 Skill 对应一类事。你要是发现自己在写一个「既能查数据、又能发布、还能排障」的超级 Skill，停一下，拆开。

三、怎么写好一个 Skill？这几条最硬

分类讲完，重头戏是怎么把一个 Skill 写好。以下原则每一条背后，都是内部踩坑踩出来的。

1. 别说废话，只写能把 Claude「推出惯性」的东西

Claude 本身就对编程非常熟悉，也有大量默认观点。如果你的 Skill 主要是传递通用知识，那它基本已经内化了，写了等于白写。真正值得写的，是那些能把 Claude 从「默认路径」推出去的信息。

原文举的前端设计 Skill（frontend-design）是绝佳例子：它不是告诉 Claude「怎么写 CSS」，而是告诉它「我们团队的设计偏好是什么」——比如刻意避开那种烂大街的 Inter 字体和紫色渐变。一句话：写 Claude 不知道的，别写它已经知道的。

2. Gotchas（坑）区，是整个 Skill 信号最强的部分

一个 Skill 里信息密度最高、最值钱的地方，是「坑」。

什么叫坑？就是那种「不告诉你，你一定会踩」的东西。比如同一个字段在 A 系统叫 user_id、在 B 系统叫 uid；又比如某张表是 append-only 的，你以为能 update，其实只能插入。这类知识在文档里通常找不到，全靠人踩出来。把它写进 Skill 的 Gotchas 区，价值远大于你复述十遍官方文档。而且它不应该是静态的——每次 Claude 踩了新坑，就追加一条进去。这个章节本质上不是什么文档，而是你们团队与 AI 协作经验的活体积累。

3. 渐进式披露：SKILL.md 当索引，用到才读

这是 Skill 设计的精髓，也是它和「一个长 md」最本质的区别。

笨办法是把所有参考文档、脚本源码、模板、每个边界情况的说明一股脑塞进上下文，结果还没干活上下文就满了，Claude 反而抓不住重点。聪明办法叫渐进式披露（progressive disclosure）：SKILL.md 只放一个轻量概要和「指针」——告诉 Claude「要做计费相关的事，去看 references/billing.md」，等它真用到了才去读那份文件。你可以把详细函数签名拆到 references/api.md，把模板放进 assets/，把可执行脚本放在 scripts/。

这其实就是上下文工程。文件夹结构本身就是你给 Claude 安排的上下文加载顺序。

4. 描述（description）是写给模型看的，不是写给人看的

SKILL.md 里的 description 字段，决定了模型什么时候会触发这个 Skill。当会话启动时，Claude Code 会构建一份所有可用 Skill 及描述的清单，然后扫描它来判断「这个请求有没有对应的 Skill」。

所以它不是给人看的简介，而是给模型看的「触发条件」。原文建议很直接：把一个好的描述写成 if-then 条件句，比如「当[某个条件]满足时，就执行[具体操作]」，而不是文绉绉地写「本技能用于持续监控合并请求的状态」。写的时候换视角想：用户会用什么样的话来唤起这个能力？把那些词写进描述。

5. 让 Claude 记住自己干过什么

这条很容易被忽略，但很实用：Skill 可以存数据，让模型读自己的历史。

做法是在 Skill 里维护一个只追加写入的日志文件或 JSON 文件（复杂一点也可以用 SQLite）。Claude 每次跑的时候读一眼上次的记录，据此调整这次的行为。比如一个站会 Skill 可以保留一份 standups.log，下次运行时它就知道从昨天到现在发生了什么变化，只输出 delta。官方还提供了 ${CLAUDE_PLUGIN_DATA} 这个稳定目录，避免数据在升级 Skill 时被删掉。这相当于给 Skill 加了一层长期记忆。

6. 存脚本、给现成代码，让 Claude 把算力花在「决策」上

还有一条工程味很重的建议：能给现成脚本和函数，就别让模型现写。

原文说得很到位——这样 Claude 就能「把它的回合花在组合上，决定下一步做什么，而不是重新拼样板代码」。翻译成人话：模型的每一步推理都是有成本的。你把重复的样板活做成脚本，它就能省下脑子去想真正需要判断的事。比如数据分析 Skill 里预置一组从事件源取数的 helper 函数，当用户问「上周二发生了什么」，Claude 不用重写取数逻辑，直接调用 helper 组合出分析脚本，把精力全放在解读数据上。

7. 别想着一上来就写个完美 Skill

这是最有实践价值的一条。Anthropic 内部那些最好用的 Skill，几乎都不是设计出来的，是「养」出来的。原文说得很坦诚：大多数 Skill 一开始就是几行字加一个坑，后来变好，是因为大家在 Claude 不断撞到新边界情况时，一条一条往里加。

路径很清晰：先写最小版（几行字 + 一个已知的坑）→ 在真实使用里撞到新坑 → 补进 Gotchas → 循环往复，它慢慢长成一个靠谱、高频复用的 Skill。别一上来就憋大招，憋出来的往往是个又长又没人用的文档。

四、比工具更深的：经验成了可复利资产

如果只到这里，Skill 就只是个效率工具。但真正重要的一层藏在后面——Skill 正在改变团队的知识流动方式。

以往，一个高级工程师花两周搞清楚内部计费库的所有陷阱，这些知识存在他脑子里，或者一个没人维护的 Confluence 页面里，下一个接手的人大概率要重新踩一遍。现在，他把知识写进 billing-lib Skill，推到团队插件市场，每个用 Claude Code 的人都自动获得了这两周的积累，而且每次踩新坑都会迭代进去。经验，第一次有了可复用的载体。

往深处想，这里有两层变化：个人层面，会不会系统地沉淀 Skill 库，正在成为工程师的新分水岭——不是加分项，而是基础门槛；组织层面，两个规模相同的团队，一个有 200 个高质量 Skill、一个只有 10 个，他们的 AI 协作效率差距可能不是 2 倍，而是 10 倍，而且是复利式、几乎不可见的差距。

说到底，Skills 不是魔法，也没有标准答案，Anthropic 自己也承认「最佳实践还在演进中」。但方向已经很明确了：它不是一张 Markdown，而是一个带脚本、带资源、带记忆、按需加载的文件夹；它最好只干一类事；它最值钱的部分是坑；它最该有的姿势是先小、再长大。

与其纠结理论，不如挑一个你每天都在重复的活——验证某个功能、查某张表、走某个发布流程——写成一个最小的 Skill，明天就开始用。