返回探索
指南VibeFix 内容整理更新于 2026年11月20日

别再把同一段话贴十遍了:给智能体写一份 SKILL.md 技能包

同一段指示贴到第三遍的时候,就别再贴了。SKILL.md 技能包能把重复流程写成一本操作手册,智能体需要时自己取出来用。本文用一个发版流程当例子,讲清 frontmatter 写法、脚本与动态上下文、存放位置,以及技能失灵的六个常见毛病。

一名开发者在笔记本电脑前敲代码,屏幕上开着代码编辑器

先把这篇的边界说清楚,免得你白读。站里已经有几篇沾边的文章:《AI Agent 记忆》讲的是智能体跨会话怎么记住事,《Agent 交接包》讲的是人走了之后项目怎么交给下一个人,《Agent 权限契约》讲的是智能体能碰什么、不能碰什么。这篇讲的都不是那些。这篇只讲一件事:同一套操作步骤,你在对话里贴了第三遍的时候,就该把它写成一份技能包,让智能体自己在需要的时候取出来用。记忆是"记住",交接是"交班",权限是"划线",技能是"把重复的活写成一本操作手册"。四件事各管各的。

下面用到的"小书架"是一个虚构的练手项目:一个用 AI 帮着写出来的个人藏书管理小应用,有前端、有后端、有数据库。本文所有以它为例的步骤和对话都是为了讲清楚做法编出来的,不是真实项目的记录。所有关于技能本身的规则、字段名和版本号,都来自 Claude Code 官方文档,来源见文末。

你是不是也在反复贴同一段话

先对一下症状。如果你用 Claude Code 这类智能体写代码,下面这个场面你大概率见过:每次要发版,你都要在对话里重新打一遍"先跑测试,测试全过再打包;打包前检查版本号是不是升了;发到预发布环境后打开首页点一遍登录和下单;有问题先回滚,别在预发布上修"。你贴过一次,两次,到了第五次,你开始怀疑人生:我到底是在写代码,还是在当复读机。

更糟的是,你不贴,它就按自己的想法来。有的智能体发版前不跑测试,有的跑了测试但失败了还继续往下走,有的直接在生产环境上改东西。这些都不是模型"笨",而是你每次都要现教的规矩,没有一个固定的地方放着。规矩只存在于你的聊天记录里,换个会话就没了,换个人就更没了。

常见的补救办法有两个,都有毛病。第一是把规矩塞进 CLAUDE.md。CLAUDE.md 是每个会话都会读的项目说明,放一两条没问题,但你把部署流程、评审清单、上线检查表全塞进去,它会越长越长。官方文档自己也提醒:CLAUDE.md 太长的时候,应该把里面的流程性内容拆出去。第二是每次现写提示词,写得长、写得细,但下次还得重写一遍,而且两个人写的版本还不一样,同一个流程今天一个做法、明天另一个做法。

技能包就是给这种情况准备的。它是一份放在仓库里的操作手册,平时不占上下文,智能体判断"现在该用它了"才加载。你写一次,之后每次需要,它自己取出来照着做。更重要的是,它可以进版本控制:团队里每个人用的都是同一份流程,改流程就是改文件、提 PR、走评审,而不是在某个人的聊天记录里改一句话。

技能包到底是什么

一句话:技能包就是一个文件夹,里面有一份 SKILL.md,加上可选的脚本和参考文件。文件夹的名字就是你输入的命令名。比如文件夹叫 deploy-staging,命令就是 /deploy-staging;如果你在 frontmatter 里写了 name: deploy,命令就变成 /deploy。文件夹可以放在三个地方:你个人的 ~/.claude/skills/,对所有项目生效;项目的 .claude/skills/,只对这个项目生效;或者打包进插件里分发给别人。

SKILL.md 本身分两段。上半段是 YAML frontmatter,夹在两行 --- 之间,告诉智能体"这个技能是干什么的、什么时候用"。最关键的字段是 description:一两句话写清楚技能的用途和触发条件,智能体就靠它决定要不要加载。下半段是 Markdown 正文,写智能体真正要执行的步骤:先做什么、再做什么、做到哪一步要停下来问你、什么情况算做完。

官方文档里有个最小例子,很值得照着学:一个叫 summarize-changes 的技能,description 写的是"汇总未提交的改动并标出风险。在用户问改了什么、想要提交信息、或者想 review diff 时使用。"正文里先用一行 !`git diff HEAD` 把当下的 diff 动态拉进来,再写两条指示:用两三条要点汇总改动,列出你注意到的风险,比如缺少错误处理、写死的配置、需要补的测试;如果 diff 是空的,就说没有未提交的改动。这个例子小,但五脏俱全:触发条件写在 description 里,实时数据用动态注入拿,正文只写判断和步骤,不写废话。

理解技能包,最关键的是理解"按需加载"这四个字。CLAUDE.md 的内容每个会话都读,不管用不用得上;技能包的正文只有在智能体决定用它的时候才加载。所以你可以把很长的参考材料、很细的检查清单放进技能里,平时几乎不花 token。这也是官方建议的判断标准:当你发现自己在反复粘贴同一段指示,或者 CLAUDE.md 里某一段已经长成了一套流程而不是一条事实,那就该把它拆成技能。事实留在 CLAUDE.md,流程做成技能。

另外要知道,技能包遵循 Agent Skills 开放标准,不只 Claude Code 一家能用。但 Claude Code 在标准之上加了自己的扩展,比如调用控制、子智能体执行、动态上下文注入。这些扩展在别的工具里不一定生效,写技能的时候心里要有数:只用标准字段,走到哪都能用;用上扩展字段,在 Claude Code 里更顺手。

什么时候该写技能,什么时候不该

不是所有重复都值得做成技能。判断之前先问三个问题。

第一个问题:这段话你贴过几次了?只出现过一次的,写进对话就行。同一项目里出现两三次、以后还会出现的,值得做成项目技能。好几个项目都在贴同一段话的,做成个人技能,放在 ~/.claude/skills/,所有项目都能用。判断标准不是"这段话有多重要",而是"它还要出现多少次"。

第二个问题:它是一条事实,还是一套流程?事实只有一句话,比如"这个项目用 pnpm,不用 npm",放 CLAUDE.md 就行。流程是有先后、有分支、有检查点的,比如"发版前先跑测试,失败就停;测试通过后升版本号;打包后部署到预发布;部署完打开首页点一遍登录",这就是技能的活。把流程塞进 CLAUDE.md,它会越长越读不下去;把事实写成技能,智能体每次都要加载一份只有一句话的手册,纯属浪费。

第三个问题:它需要动手,还是只需要知道?技能能带脚本、能读文件、能跑命令,适合"照着做"的活。如果你的需求是让智能体去调外部服务的实时数据,或者操作一个它本来够不着的系统,那不是技能的活,是 MCP 服务器的活。技能是给智能体的说明书,MCP 是给智能体的操作杆。两者常常配合:技能里写"什么时候调哪个工具、调完怎么判断",MCP 负责把工具真的递到智能体手里。站里另一篇《给自己的项目接一根线:从 0 写出第一个 MCP 服务器》专门讲后者,两篇合起来看更完整。

还有一种情况不值得做技能:流程本身还在天天变。你今天刚定的发版流程,明天就可能改。流程没定型之前,先在对话里多试几次,等做法稳定下来、你已经能一口气说出完整步骤了,再把它写成技能。过早把没想清楚的东西固化下来,唯一的下场是技能和实际做法对不上,智能体照着旧手册做错事,你还得花时间去修手册。

判断一段重复指示该放进对话、CLAUDE.md、技能包还是 MCP 服务器的决策流程图

上图把这个判断画成了流程:先数它出现过几次,再看它是事实还是流程,最后看它需不需要动手。四个出口分别对应对话、CLAUDE.md、技能包和 MCP 服务器,大部分日常重复都会落在技能包这一格。

从 0 写第一个技能:以发版流程为例

道理讲完了,动手写一个。拿"小书架"的发版流程当例子,目标是做出一个 /deploy-staging 技能:你一句话"发到预发布",智能体就按固定步骤走完测试、升版本、部署、验证四步。

第一步,建文件夹。项目技能放在仓库的 .claude/skills/ 下面,文件夹名就是命令名:

mkdir -p .claude/skills/deploy-staging

第二步,写 SKILL.md。先写 frontmatter,description 是最重要的一行,决定智能体什么时候会自己想起这个技能。写 description 有个笨办法但很管用:用"做什么 + 什么时候用"两句话写,不要只写名词。反面例子:"预发布部署技能。"这句话等于没说,智能体看不出什么时候该用它。正面例子:"把当前改动部署到预发布环境并验证首页可用。在用户说发到预发布、上预发布、部署到 staging 时使用。"触发词写得越具体,命中越准;但也别把触发词写成只有你自己才用的黑话,团队其他人说"部署一下测试环境",技能就该能对上号。

正文部分按"先做什么、再做什么、什么情况停下来"的顺序写。给"小书架"写的版本大概是这样:

---
name: deploy-staging
description: 把当前改动部署到预发布环境并验证首页可用。在用户说发到预发布、上预发布、部署到 staging 时使用。
---

## 步骤

1. 运行 `npm test`。如果有任何测试失败,停下来,把失败信息报给用户,不要继续。
2. 检查 `package.json` 里的版本号是否比上一版高。没升就提醒用户,先升版本再继续。
3. 运行 `npm run build`,构建失败同样停下来。
4. 把构建产物部署到预发布环境。
5. 部署完成后打开预发布首页,点一遍登录和查看藏书,确认页面能正常打开。

## 注意事项

- 预发布环境的数据是假数据,不要在上面做真实操作。
- 任何一步失败都不要自己绕过去,先停下来问用户。

注意正文里有两处刻意的设计。第一是"失败就停下来"出现了两次,而且写明了"不要自己绕过去"。智能体的默认倾向是把事情做完,你不写停,它就会自己想办法绕过失败继续走,最后给你一个"看起来成功了"的结果。第二是最后一步要求真的打开页面点一遍,而不是只看部署命令的退出码。部署命令成功只代表文件传上去了,不代表页面能打开,这一步是整个技能里最容易被省掉、也最有价值的一步。

第三步,测试技能。回到项目里,在 Claude Code 的提示框输入 /deploy-staging,看它是不是按步骤走。第一次测试建议故意留一个失败的测试,看它会不会真的停下来;再故意不升版本号,看它会不会提醒你。技能只有经过这种"捣乱测试"才算真的能用。官方文档还提供了一个更系统的办法:运行 /doctor 做安装检查,或者用 /doctor prompt-audit 审一遍你的 CLAUDE.md 和技能文件,看有没有过时或者互相打架的指示。

一个技能从写到能用,通常不应该超过半小时。如果写了两个小时还没跑通,往往不是你写得不够细,而是这个流程本身还没想清楚,或者它根本不适合做成技能。先退回对话里多试几次,等流程稳定了再来。

让技能自己带上"手":脚本与动态上下文

光会写步骤的技能只是半成品。很多流程里真正烦人的部分不是"第几步做什么",而是"做之前要先去查一堆现状"。比如评审一个 PR,你要先看改了哪些文件、改了多少行、有没有碰到敏感配置。让智能体自己去查,它查得慢,还可能漏;把现状直接塞进技能里,它一上来就能干活。这就是动态上下文注入:在 SKILL.md 里写一行 !`命令`,智能体加载技能的时候会先跑这条命令,把输出贴进技能内容里再开始执行。前面 summarize-changes 例子里的 !`git diff HEAD` 就是这个用法。

动态注入有个规矩要记住:它只在技能加载的时候跑一次,跑出来的结果是当时的快照。如果流程很长,中间的现状变了,技能不会自动刷新。别指望它当监控用,它只是帮你把"开始干活之前要看的东西"提前准备好。

比动态注入再往前一步,是让技能带上脚本。技能文件夹里除了 SKILL.md,还可以放 scripts/、references/ 这类配套文件。比如"小书架"要加一个检查数据库迁移的技能,正文里写"运行 scripts/check-migration.sh,脚本会告诉你迁移文件和数据库现状对不对得上",脚本本身就放在技能文件夹里一起提交。智能体执行的时候按你给的路径去跑,不用每次现写命令。官方文档里还提到了 ${CLAUDE_SKILL_DIR} 这个变量:在技能正文和 allowed-tools 的 Bash 规则里,它会被替换成技能文件夹的实际路径,这样技能里写脚本路径就不用写死绝对路径,换台电脑、换个人都能用。

脚本和动态命令都涉及权限,这里有个容易踩的坑:技能里声明的 allowed-tools 是"预授权",意思是智能体执行这个技能的时候,某些命令不用每次都弹框问你。但这个预授权要走正常的权限流程,不是绕过权限。如果你所在的组织开了 allowManagedPermissionRulesOnly 这类管控,技能里的预授权可能直接失效,智能体还是会一步一问。写技能的时候别把"不用确认"当成默认前提,关键操作——删数据、对外发请求、动生产环境——宁可让它多问一次。

还有两个 frontmatter 字段值得认识,但别滥用。disable-model-invocation: true 的意思是"这个技能只许人来调,不许智能体自己加载"。适合那种一旦误触发就很麻烦的技能,比如删库、清缓存、对外发版。context: fork 的意思是"这个技能在独立的子智能体里跑",子智能体看不到你的对话历史,技能内容必须自成一体。适合那种步骤很长、中间产物很多、不想污染主对话的任务,比如"把整个仓库的文档过一遍,列出过时的部分"。默认不写这两个字段,就是"你和智能体都能调、在当前对话里跑",大部分技能这样就够了。

技能放哪、谁能用

位置决定范围。个人技能放在 ~/.claude/skills/,你名下所有项目都能用,适合"不管什么项目我都要这么干"的东西,比如你自己的提交信息格式、你习惯的代码评审清单。项目技能放在仓库的 .claude/skills/,跟着代码走,团队每个人 checkout 下来就都有,适合"这个项目必须这么干"的东西,比如发版流程、上线检查。插件里的技能则是分发形态,适合"想让很多人装上就用"的东西,比如某个开源项目给贡献者准备的操作手册。

范围越大,越要克制。个人技能写得太多太泛,智能体每次都要在一大堆技能里挑,挑错的概率就上去了。项目技能也一样:一个项目里放三五个常用的就够了,十几个技能堆在一起,维护成本比收益还高。判断技能是不是太多了,有个简单的信号:/skills 菜单打开之后,你自己都说不清每个技能是干什么的,那就该合并或者删掉几个了。

团队用项目技能的时候,还有个组织层面的好处:改流程变成了改代码。以前流程变了,你要在群里发消息"以后发版先跑测试再打包",总有人没看到;现在流程变了就是改 SKILL.md、提 PR、走评审,改完所有人用的都是新版。而且新同事入职第一天 checkout 仓库,就能看到"这个项目是怎么做事的",不用再靠老同事口口相传。官方文档里的 /verify 技能就是个好例子:它把"提交前怎么验证改动"录成技能,Claude Code 在 v2.1.286 之后甚至会在每次提交前自动跑它,前提是技能放在项目、个人这些合规的位置,并且你没有关掉相关的 Git 指示。

最后是同步与可见性。技能文件是普通文件,跟着仓库走,同步问题就是 Git 的问题。但要注意,技能一旦进了仓库,它的 description 和正文就是团队共识,改的时候要当成改流程来对待:改之前想清楚影响,改完在 PR 里写清楚改了什么、为什么改。一个人偷偷改了技能正文,第二天整个团队的智能体都按新流程走,出了问题都不知道是谁改的——这和改 CI 配置是一个级别的事。

技能也会失灵:六个常见毛病

技能不是写完就万事大吉。下面六个毛病,官方文档的排错章节里基本都提到了,照着检查一遍,能省掉很多"为什么它不按我写的做"的困惑。

第一,description 写得像标题。"部署技能""评审助手""代码检查",这类描述智能体没法匹配。你要写"做什么 + 什么时候用",而且要写用户真正会说的那种话。写完之后自己读一遍:如果一个新同事只看这句话,不知道什么时候该用这个技能,那它就不合格。

第二,名字撞了。两个技能同名,或者技能名和内置命令重名,到底跑哪一个,要看它是从哪来的。项目技能、个人技能、插件技能的优先级各不相同,具体规则可以去查官方文档的命名章节。给技能起名字的时候,尽量具体:deploy-staging 比 deploy 好,review-pr 比 review 好。具体的名字不仅不容易撞,也更容易被智能体正确匹配。

第三,frontmatter 没有放在文件第一行。官方文档明确说了:只有当开头的 --- 是文件的第一行时,它才会被当成 frontmatter。前面多了一行空行、一段注释,整段 frontmatter 都会被当成正文,description 也就失效了。技能突然"不触发了",先检查文件开头。

第四,YAML 写坏了。frontmatter 里少个空格、多一个冒号,解析失败时技能照样能加载,但所有字段都当成没写。症状就是:/deploy-staging 能打出来,但智能体从来不自动用它。官方给的诊断办法是带 --debug 跑,或者对技能目录跑 claude plugin validate,直接找出哪个文件的 frontmatter 解析失败。

第五,description 里放了尖括号占位符。比如写"给 <分支名> 做评审",界面上会显示成转义后的样子。官方建议用方括号写占位符,或者把占位提示挪到 argument-hint 字段里。这是个小毛病,但会让技能在菜单里看起来很怪。

第六,技能写得太长。正文不是越细越好。技能正文的正确长度是"一个有经验的同事照着它能把事做对",而不是"把所有背景知识都讲一遍"。背景知识、参考资料应该放在 references/ 文件夹里,让技能正文在需要的时候去引用,而不是全塞进正文。技能正文一长,智能体反而抓不住重点,执行的时候开始自由发挥。

先从一个技能开始

如果你之前从来没写过技能,不要一上来就规划十个。先挑一个你这周已经贴过两遍的流程,按下面的清单走一遍:

一、找到那段话。打开最近的聊天记录,找到你重复贴过的那段指示,复制出来。二、判断位置。只在这个项目出现,放项目技能;好几个项目都在用,放个人技能。三、写 description。按"做什么 + 什么时候用"写两句,触发词用你和同事真正会说的话。四、写正文。按步骤写,每一步失败了怎么办也要写,关键操作写明"停下来问我"。五、捣乱测试。故意留一个失败、故意漏一个步骤,看它会不会停、会不会提醒。六、提交进仓库。让技能跟着代码走,而不是躺在你一个人的电脑里。

做完这一个,你会立刻感觉到变化:下次再要做这件事,你不用再翻聊天记录找那段话,直接一句话,智能体自己把手册取出来照着做。省下来的不是打字的时间,是每次重新讲一遍规则的注意力。而注意力,才是你用智能体写代码时最贵的东西。

最后再提醒一句:技能解决的是"重复的流程",不是"模糊的想法"。如果你自己都说不清一个流程到底分几步、先干什么后干什么,技能帮不上忙。先在对话里把事情做明白,把做法固定下来,再把它写成技能。顺序反了,技能只会把混乱固化下来,而且固化得比聊天记录更持久、更难发现。

来源:Claude Code 官方文档《Extend Claude with skills》(https://code.claude.com/docs/en/skills.md ,2026-11-17 亲读);Agent Skills 开放标准(https://agentskills.io ,文档中引用);MCP 服务器做法见本站《给自己的项目接一根线:从 0 写出第一个 MCP 服务器》。

阅读 3评论 0

评论 (0)

ME
0/1000
评论加载中...

原始来源

浏览项目广场发布你的项目

相关文章

真实照片:一双手在 MacBook Pro 上打字,屏幕显示改写 HTML 内容的 JavaScript 代码,白色桌面上有白色鼠标、纸张和文件夹
指南
别让函数把你绕晕:JavaScript 函数、参数与箭头函数实战指南

函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。

工具技巧前端工程AI 编程实践
真实照片:木桌上的卡西欧科学计算器,屏幕显示 123456789 + 987654321 = 1111111110,旁边是写满手写数学公式的笔记本、钢笔、咖啡杯和笔记本电脑一角
指南
别让 0.1 + 0.2 坑了你的账单:JavaScript 数字与 Math 实战指南

JavaScript 里数字只有一种类型 Number,存成 64 位浮点数,所以 0.1 + 0.2 等于 0.30000000000000004。本文按 MDN 的《Basic math in JavaScript》《Math》《Number》三篇官方文档讲清楚:一种数字类型、浮点误差、钱改成分算、字符串转数字、NaN 与 Infinity、安全整数、四种取整、Math.random、Math 工具箱与显示格式化。

工具技巧前端工程AI 编程实践
真实照片:一名女子站在办公室白墙前,把彩色便利贴按行贴在墙上,手里还拿着一张粉色便利贴
指南
别再用 margin 硬凑间距了:Flexbox 一维布局实战指南

Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。

开发工作流前端工程AI 编程实践