五度妙笔
API商城
数据库Claude Code 内部复盘的Skills实战经验公开：好 Skill 的 5 个共性
上个月我写过一篇 Skill 的实测文章，从翻译两本书的实战出发，讲了“做完打包”这件事有多重要。
但依旧有小伙伴反馈，“我写出来的 Skill 就是不好使”。
说实话，这个问题我自己也遇到过。有的 Skill 写完就是越用越顺，有的怎么调都差点意思，一直说不上来到底差在哪。
3 月 18 日，Anthropic 工程师 Thariq 发了一条长推，标题就叫_《Lessons from Building Claude Code: How We Use Skills》_。他们内部已经有数百个 Skill 在活跃使用，踩过的坑和总结出来的经验，终于公开讲了一次。
我看完之后有一个很大的触动。不是某个具体技巧，而是让我意识到，大部分写 Skill 的时候，写进去的东西压根就不是 AI 需要你告诉它的。
Skill 补的不是说明书，是语境
在讲 Thariq 的五条经验之前，先说一个看似无关但其实特别重要的事。
你有没有想过，传统编程其实是一种非常极端的沟通方式？你必须把输入、输出、参数、条件、流程全部写清楚，少写一个分号程序都会崩。计算机不猜你的意思，你说什么它做什么，一个字都不能省。
但我们人和人之间在团队里干活，完全不是这样的。老工程师会跟你说：这个接口不是不能用，但线上最好别这么调。产品经理会说：这个需求文档写的是 A，但老板真正想要的是 B。
这些话你在任何文档里都找不到。它们只存在于经验、默契、口头传授，和一堆做久了就知道的判断里。
学术上有个说法叫“高语境沟通”。Edward T. Hall 在上世纪提出的框架：低语境沟通依赖字面信息，高语境沟通依赖共享背景、默认规则和隐含共识。你跟一个合作了三年的同事说老规矩处理一下，他立刻知道该怎么做。但你跟一个新来的实习生说同样的话，他会一脸懵。
你现在调教的 Skill，就是那个实习生。
API 文档、代码示例、技术教程，这些写得明明白白的东西它都知道，甚至比你记得还清楚。但一旦进入真实工作流，卡住它的恰恰是那些高语境信息：你们团队真正的验收标准是什么、哪个图表才是组织里公认的“准口径”、哪些步骤文档上没写但必须额外核验。
所以很多 Skill 之所以不好用，是因为大家写进去的，仍然是模型本来就知道的东西，本质上等于又喂了它一份已经吃过的饭。那些低语境的、写在明面上的知识，模型原本就会。你多说一遍，它也未必做得更好。
第一：Anthropic 内部最看重的，是“坑”
那应该写什么？
Thariq 在推文里说了一句话，我觉得含金量很高：“一个 Skill 里信息密度最高的部分是坑点总结。”
因为 Claude 本身已经知道很多东西了。你写一个 Skill 告诉它“这个 SDK 的 init 方法接收三个参数”，大概率它已经知道了，这种信息它在预训练数据里见过无数遍。
但如果你告诉它：“我们这个审批流程，文档里标的是可选，但实际上必须走。不走这一步，后面的权限审核会直接卡住。”——这种信息它查遍全网也查不到。因为这根本就是你们自己定的规矩，不在任何公开文档里。
这就是坑。这就是高语境知识。
回头看我们之前翻书那个案例，翻译 Skill 里最有用的部分是什么？不是“怎么调用 LinguaGacha”这种流程说明，而是“50 并发会炸 API”，这些踩过之后才知道的坑。
所以写 Skill 之前，先问自己一个问题：这里面有多少内容是 Claude 自己搜不到的？
如果答案是大部分都搜得到，那这个 Skill 的价值大概率就很有限。说明书是低语境知识，谁都能查到；Gotchas 是高语境知识，只有你自己最清楚。Skill 真正的价值，就是把后者从你脑子里掏出来，变成 AI 能读取的格式。
第二：Description 字段非常重要
只把经验写进去还不够。一个 Skill 再有价值，如果它不能在正确的场景里被调出来，效果还是会打折。
这也是为什么 Thariq 特别强调：description 字段非常重要。
很多人写 Skill，花了很多心思在正文内容上。流程写得很详细，步骤列得很清楚，参考文档也附上了。但 description 字段随手写了一句“这是一个翻译工具”就完事了。
问题是，description 字段不是给人看的摘要，是给模型看的触发条件。Claude Code 启动的时候，会扫描所有可用的 Skill，读的就是这个 ，然后根据用户当前的请求，判断要不要激活某个 Skill。
所以，Description 写得好不好，直接决定了这个 Skill 会不会在该出现的时候出现。
你写“这是一个翻译工具”，模型看到用户说“帮我翻译这篇文章”的时候可能会激活。但用户说“把这个英文 PDF 转成中文”呢？说“这个论文能不能出个中文版”呢？
这些都是翻译场景，但如果 description 写得太窄，模型就匹配不上。
反过来，如果 description 写得太宽，比如“处理各种文本任务”，那用户随便说句话它都可能跳出来捣乱。
好的 description 应该像一个精准的 if 条件：
当用户需要翻译英文文档（PDF/DOCX/EPUB/网页文章）为中文，包括学术论文、书籍、长文翻译、术语密集型内容时触发。不适用于日常短句翻译或口语化翻译。
你看，该触发的场景列清楚了，不该触发的场景也排除了。
这个细节看起来小，但当你手上有十几个 Skill 的时候，差别会非常明显：description 写得好的 Skill，你提需求它就自动出来干活；写得差的，你每次都得手动指定。
第三：让 Skill 自己记住上次干了什么
不过，能在对的时候被触发，仍然只是第一步。
一个助手真正开始“顺手”，不只是因为它知道你们怎么做事，还因为它记得上一次已经做到哪一步。
这也是 Thariq 那条推里我觉得最被低估的一点：Skill 可以有自己的记忆。
最简单的做法：就是在 Skill 目录下放一个日志文件，每次执行完往里面追加一条记录。下次执行的时候，AI 先读一遍日志，就知道上次做了什么。
复杂一点：放一个 JSON 文件，记录结构化数据。再复杂一点：放一个 SQLite 数据库。
这件事为什么重要？因为很多传统 AI 助手最让人抓狂的问题就是：每次都像第一次见你。你昨天让它写过日报，今天它又从零开始猜你的格式。你上周让它跑过一套数据分析，这周它又像失忆了一样问你“数据在哪”。
有了 Skill 内记忆，情况就变了。
Thariq 举了个例子：一个 standup-post Skill，每天帮你写站会日报。如果它保留了之前每天的日报内容，那第二天它运行的时候就不只是“生成一份新日报”，而是能知道：今天和昨天相比，真正新增了什么、哪些任务从“进行中”变成了“已完成”、哪些卡了两天还没动。
这才是有用的日报，只写发生了什么变化。
我们自己做新闻选题系统的时候也有类似体会。如果选题 Skill 不记得昨天推荐过什么，今天就可能推荐一模一样的选题。但如果它能读到自己的历史记录，就会自动跳过已推荐的，只推新的。
这种“记忆”不需要多高级。一个 append-only 的文本文件就够了。关键是意识到：Skill 不只是一次性的指令集，它可以是一个有状态的工作助手。
每次执行完，让它把关键信息写进日志。下次执行前，让它先读日志。就这么简单的一个循环，效果天差地别。
第四：Skill 的威力不在那份 markdown，在于整个文件夹
这一条是我自己体会最深的。
你用过一段时间 Skill 就会发现，一份 markdown 写得再好，能承载的东西也有限。你没法在一段文字描述里把一个查询逻辑说清楚，也没法用文字精确定义一份报告该长什么样。
Thariq 举了个例子。假设你做数据分析，经常需要从公司的事件系统里拉数据。每次你都要告诉 AI：“先连这个数据库，用这个查询语句，然后按这个格式输出。”累不累？累。而且 AI 每次重新写查询，写出来的还不一定对。
但如果你把这些操作封装成几个 Python 函数，放在 Skill 的 scripts/ 目录下。那 AI 在执行的时候就不需要从头写查询逻辑了。它只需要决定：先调哪个函数、传什么参数、结果怎么组合。
让 Claude 把精力花在决策上，而不是重建轮子上。
同样的道理，如果你的 Skill 最终输出是一份特定格式的报告，你可以在 assets/ 目录下放一个模板文件。AI 看到模板，就知道该往里填什么、格式长什么样。比你在 markdown 里用文字描述格式要准确十倍。
还有一种更高级的用法：放参考代码。比如你们团队有一套代码风格，光靠文字描述很难说清楚，但放三个写得好的文件进去，AI 一看就懂。
这个思路其实就是 Thariq 说的“渐进式上下文披露”。你不需要把所有信息都塞进主提示词里，那样又长又乱。把详细内容拆到不同文件里，告诉 AI 这些文件在哪、分别是干什么的。它会在需要的时候自己去读。
用高低语境的框架来看，这其实就是在帮 AI 建立“共享背景”。
就像一个成熟团队不会把所有规范写进一封超级长的邮件里。而是有文档库、有脚本、有模板、有 checklist。Skill 本质上就是把这套东西做成 AI 能直接调用的工作环境。
第五：但只有能力还不够，还要有边界和护栏
不过，一个真正可用的工作环境，不能只有能力，没有约束。
如果 scripts、模板、参考代码解决的是“AI 能不能做”，那钩子机制解决的就是“AI 会不会乱做”。
Thariq 提到，Claude Code 的 Skill 可以注册“on-demand hooks”，也就是临时钩子。这些钩子只在 Skill 被激活的时候生效，Skill 结束就自动关闭。
比如你有一个叫 /careful 的 Skill。激活之后，它会挂一个 PreToolUse 钩子，拦截所有危险操作：rm -rf、DROP TABLE、force-push、kubectl delete。你碰生产环境的时候开一下，它就像一个安全锁，AI 想执行危险命令的时候会被拦住。平时不开，不影响正常工作。
再比如一个叫 /freeze 的 Skill。激活之后，AI 只能编辑指定目录下的文件，其他地方碰都不让碰。你在调试的时候特别有用。你想加几行 log，但不想 AI 顺手"修"了别的文件。开了 /freeze，它就只能在你指定的范围内活动。
这个设计特别巧妙。因为大多数人写 Skill 的思路是“告诉 AI 该做什么”。但临时钩子反过来，是“告诉 AI 什么绝对不能做”。
前者是引导，后者是护栏。两个都有，才算一个完整的工作环境。
想想你带一个新人。你不光要告诉他“你的任务是什么”，还要告诉他“这几台机器千万别碰”。Skill 加上钩子，就是在做同样的事情。
9 类 Skill，背后只有一个判断标准
除了这些实用技巧，Thariq 还透露了 Anthropic 内部管理 Skill 的方式。Thariq 还分享到，Anthropic 内部把几百个 Skill 归成了 9 类：
库和 API 参考——教 AI 用你们内部的 SDK 产品验证——让 AI 自己测试自己写的代码 数据获取与分析——连接你们的数据和监控系统 业务流程自动化——把重复的团队流程一键化 代码脚手架——生成符合你们规范的项目模板 代码质量与审查——自动化 code review CI/CD 与部署——从构建到发布到回滚 Runbook——从报警信号到排查到出报告 基础设施运维——清理、成本分析、依赖管理
类别很多，但最好的 Skill 都只落在一个类别里。如果一个 Skill 既想当教程，又想当自动化工具，还想当审查员，最后往往什么都做不好。
背后其实只有一个判断标准：这个 Skill 到底是在补“知识差”，还是在补“执行差”。
补知识差的，重点写坑、写边界、写反例；补执行差的，重点给脚本、给验证工具、给自动化流程。搞清楚这一点，你就知道自己的 Skill 里该写什么、不该写什么。
特别值得一提的是验证类 Skill。Thariq 也着重强调了一句话：如果验证 Skill 做得好，值得一个工程师花一周时间专门打磨。
一个好的验证 Skill 可能包括：浏览器自动化脚本、测试账号、状态断言规则、甚至让 AI 录一段操作视频以便你事后检查。生成能力决定 AI 能做多少事，验证能力决定你敢让它做多少事。差距就在这。
Skill 商店已经开始出现了，但质量战才是重点
Thariq 还透露了 Anthropic 内部管理 Skill 的方式。
他们没有一个中央团队来审批。而是让 Skill 自然生长。
你觉得好用，先放到 GitHub 的沙盒文件夹里，在 Slack 里告诉同事。有人用了觉得好，口碑传开了，再提 PR 进入正式的 Skill marketplace。
这个模式特别像早期 App Store。先让数量爆发，再靠口碑和使用数据做淘汰。
但 Thariq 也提了一句警告：创建糟糕或冗余的 Skill 太容易了。确保你有某种策展机制再上架。
这跟我们之前文章里观察到的一模一样。SkillsMP 上的 Skill 数量增长很快，但质量参差不齐。有些 Skill 就是把官方文档复制粘贴进去，description 写得模糊不清，根本不可用。
数量先爆、质量后补、优胜劣汰。这条路 App Store 走过，小程序走过，现在 Skill 生态也在走。
他们内部还用 PreToolUse 钩子做了使用统计，能看到哪些 Skill 被调用得最多、哪些 Skill 触发率低于预期。这意味着 Skill 的好坏不再靠感觉判断，而是有数据可查。
对普通开发者来说，这条信息的意义是：如果你做了一个 Skill 放到 GitHub 上，别人用不用、好不好用，将来是可以被量化的。这也意味着，做 Skill 的门槛虽然低，但做好 Skill 的标准正在变高。
回到最初的问题：为什么你的 Skill 不好使？
把 Thariq 的经验总结和高低语境的框架放在一起，答案其实很清楚了。
不好用的 Skill，写的是低语境信息。功能介绍、API 文档、操作步骤。这些东西模型本来就知道，你多写一遍它也不会做得更好。
真正让 Skill 好使的，是高语境信息：你们团队特有的坑、你们自己的验收标准、那些“做久了就知道”的默认规则、“这个命令千万别在生产环境跑”之类的护栏。
这些东西没法从预训练里学到，没法从官方文档里抄到，只有你自己最清楚。
Claude Code 之所以会让人觉得越用越顺手，就是因为 Skill 开始承载越来越多团队自己的语境、经验、工具和边界。
所以写 Skill 的正确顺序应该是：
第一步，别急着写说明书。先列出你们团队在这类任务上踩过的 10 个最大的坑，写进 Gotchas。
第二步，把 description 当触发条件写，而不是当简介写。想清楚这个 Skill 该在什么场景下被自动调出来，什么场景下不该出现。
第三步，给脚本、给模板、给参考代码，而不只是给文字。让 AI 把精力花在判断和组合上，而不是花在重建轮子上。
第四步，加记忆。哪怕只是一个日志文件，让 Skill 知道上次做了什么，这次该做什么不一样的。
第五步，加护栏。不光告诉 AI 该做什么，还要告诉它什么绝对不能做。
这五步做完，你的 Skill 就是一个有知识、有工具、有记忆、有边界的工作环境。
说白了，你在做的事情，是把你脑子里那些高语境的、只可意会的工作经验，翻译成一种 AI 能接住的格式。
模型决定 AI 能想多远。Skill 决定 AI 能干多稳。而 Skill 的质量，取决于你往里面装了多少只有你才知道的东西。
