2026-03-23 16:42
扫码打开虎嗅APP
本文来自微信公众号： 夕小瑶科技说 ，作者：丸美小沐，原文标题：《Claude Code 内部复盘的Skills实战经验公开：好 Skill 的 5 个共性》
上个月我写过一篇Skill的实测文章，从翻译两本书的实战出发，讲了“做完打包”这件事有多重要。
但依旧有小伙伴反馈，“我写出来的Skill就是不好使”。
说实话，这个问题我自己也遇到过。有的Skill写完就是越用越顺，有的怎么调都差点意思，一直说不上来到底差在哪。
3月18日，Anthropic工程师Thariq发了一条长推，标题就叫_《Lessons from Building Claude Code:How We Use Skills》_。他们内部已经有数百个Skill在活跃使用，踩过的坑和总结出来的经验，终于公开讲了一次。
我看完之后有一个很大的触动。不是某个具体技巧，而是让我意识到，大部分写Skill的时候，写进去的东西压根就不是AI需要你告诉它的。
在讲Thariq的五条经验之前，先说一个看似无关但其实特别重要的事。
你有没有想过，传统编程其实是一种非常极端的沟通方式？你必须把输入、输出、参数、条件、流程全部写清楚，少写一个分号程序都会崩。计算机不猜你的意思，你说什么它做什么，一个字都不能省。
但我们人和人之间在团队里干活，完全不是这样的。老工程师会跟你说：这个接口不是不能用，但线上最好别这么调。产品经理会说：这个需求文档写的是A，但老板真正想要的是B。
这些话你在任何文档里都找不到。它们只存在于经验、默契、口头传授，和一堆做久了就知道的判断里。
学术上有个说法叫“高语境沟通”。Edward T.Hall在上世纪提出的框架：低语境沟通依赖字面信息，高语境沟通依赖共享背景、默认规则和隐含共识。你跟一个合作了三年的同事说老规矩处理一下，他立刻知道该怎么做。但你跟一个新来的实习生说同样的话，他会一脸懵。
你现在调教的Skill，就是那个实习生。
API文档、代码示例、技术教程，这些写得明明白白的东西它都知道，甚至比你记得还清楚。但一旦进入真实工作流，卡住它的恰恰是那些高语境信息：你们团队真正的验收标准是什么、哪个图表才是组织里公认的“准口径”、哪些步骤文档上没写但必须额外核验。
所以很多Skill之所以不好用，是因为大家写进去的，仍然是模型本来就知道的东西，本质上等于又喂了它一份已经吃过的饭。那些低语境的、写在明面上的知识，模型原本就会。你多说一遍，它也未必做得更好。
那应该写什么？
Thariq在推文里说了一句话，我觉得含金量很高：“一个Skill里信息密度最高的部分是坑点总结。”
因为Claude本身已经知道很多东西了。你写一个Skill告诉它“这个SDK的init方法接收三个参数”，大概率它已经知道了，这种信息它在预训练数据里见过无数遍。
但如果你告诉它：“我们这个审批流程，文档里标的是可选，但实际上必须走。不走这一步，后面的权限审核会直接卡住。”——这种信息它查遍全网也查不到。因为这根本就是你们自己定的规矩，不在任何公开文档里。
这就是坑。这就是高语境知识。
回头看我们之前翻书那个案例，翻译Skill里最有用的部分是什么？不是“怎么调用LinguaGacha”这种流程说明，而是“50并发会炸API”，这些踩过之后才知道的坑。
所以写Skill之前，先问自己一个问题：这里面有多少内容是Claude自己搜不到的？
如果答案是大部分都搜得到，那这个Skill的价值大概率就很有限。说明书是低语境知识，谁都能查到；Gotchas是高语境知识，只有你自己最清楚。Skill真正的价值，就是把后者从你脑子里掏出来，变成AI能读取的格式。
只把经验写进去还不够。一个Skill再有价值，如果它不能在正确的场景里被调出来，效果还是会打折。
这也是为什么Thariq特别强调：description字段非常重要。
很多人写Skill，花了很多心思在正文内容上。流程写得很详细，步骤列得很清楚，参考文档也附上了。但description字段随手写了一句“这是一个翻译工具”就完事了。
问题是，description字段不是给人看的摘要，是给模型看的触发条件。Claude Code启动的时候，会扫描所有可用的Skill，读的就是这个，然后根据用户当前的请求，判断要不要激活某个Skill。
所以，Description写得好不好，直接决定了这个Skill会不会在该出现的时候出现。
你写“这是一个翻译工具”，模型看到用户说“帮我翻译这篇文章”的时候可能会激活。但用户说“把这个英文PDF转成中文”呢？说“这个论文能不能出个中文版”呢？
这些都是翻译场景，但如果description写得太窄，模型就匹配不上。
反过来，如果description写得太宽，比如“处理各种文本任务”，那用户随便说句话它都可能跳出来捣乱。
好的description应该像一个精准的if条件：
当用户需要翻译英文文档（PDF/DOCX/EPUB/网页文章）为中文，包括学术论文、书籍、长文翻译、术语密集型内容时触发。不适用于日常短句翻译或口语化翻译。
你看，该触发的场景列清楚了，不该触发的场景也排除了。
这个细节看起来小，但当你手上有十几个Skill的时候，差别会非常明显：description写得好的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加上钩子，就是在做同样的事情。
除了这些实用技巧，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能做多少事，验证能力决定你敢让它做多少事。差距就在这。
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的质量，取决于你往里面装了多少只有你才知道的东西。
