从零写一个 Claude Code Skill:SKILL.md、脚本与验证全流程
一个 Claude Code Skill 就是一个装着 SKILL.md 的文件夹:frontmatter 写什么时候用,正文写怎么做。本篇以 changelog-entry 为例,从零走一遍:怎么写、放哪里、三道验证怎么过。

划界:这篇和已发的 Skill 文章有什么不同
先说清楚这篇指南的位置,免得和已经发过的内容撞上。站里已经有一篇《agent-skills-vs-prompts》,那篇是比较文章:讲 Skill 和提示词各适合什么场景、什么时候该用哪个,不教怎么写 Skill。也有一篇《build-first-mcp-server-guide》,教的是从零搭一个 MCP Server,那是另一种扩展机制:MCP 是给 Agent 接外部工具和数据源的,Skill 是给 Agent 沉淀流程和知识的,两者解决的问题不一样。还有一篇介绍 Ponytail Skill 的资讯,那是介绍一个现成的 Skill 产品,不是写作教程。
本篇是动手教程:从零写一个能用的 Claude Code Skill,全流程包括什么时候值得写、SKILL.md 怎么写、脚本和参考文件怎么组织、放哪里、怎么验证它真的被调用、以及常见的五个错误。读完之后,你应该能在一个小时之内,给自己最常重复的那套流程写出第一个 Skill,并且知道怎么判断它写得好不好。
依据是两份官方文档:Claude Code 的 Skills 文档(code.claude.com/docs/en/skills.md)和 Agent Skills 开放标准(agentskills.io)。本文提到的机制——文件位置、调用方式、渐进式加载、动态上下文注入——都出自这两份文档;其中的操作建议(比如 Skill 应该多短、什么时候拆文件)是基于这些机制给出的做法,文中会说明哪些是文档原话、哪些是建议。
什么时候值得写一个 Skill:三个信号
不是所有重复劳动都值得写成 Skill。Claude Code 的文档给了一个很直接的判断标准:当你发现自己总在往对话框里粘贴同一段说明、同一份检查清单,或者同一套多步骤流程的时候,就该写 Skill 了。另一个信号是 CLAUDE.md 里的某一节已经长成了一套流程,而不是一条事实——事实适合放在 CLAUDE.md 里随会话加载,流程适合写成 Skill,用到的时候再加载。
具体一点,三个信号出现任何一个,都可以动手。第一个信号是“同一段话说了三遍以上”。比如每次发版前,你都要跟 Agent 说一遍“先跑测试,再检查 CHANGELOG 有没有更新,再确认版本号 bump 了,再发”。说到第三遍的时候,这段话就该从对话框里搬进 SKILL.md。第二个信号是“流程有固定顺序,而且顺序错了会出事”。比如上线检查必须先跑测试、再看数据库迁移、最后才发布,顺序不能乱——这种带顺序的流程最适合写成 Skill,因为人每次口述都可能漏一步,写进文件就不会漏。第三个信号是“换个人(或者换个会话)就得重新教一遍”。团队里每个人都要跟 Agent 解释一遍“我们项目的发布流程是这样的”,说明这套知识只存在于人脑里,写成项目 Skill 提交进仓库,所有人就都不用再教了。
反过来,也有三种情况不值得写 Skill。第一,流程只用一次。写 Skill 本身也要花时间,只用一次的事,直接在对话框里说清楚更划算。第二,流程每天都在变。Skill 的价值在于稳定,今天写的步骤明天就过时了,维护成本比每次口述还高,不如等流程稳定下来再写。第三,事情本身就是一条事实而不是流程。比如“这个项目用 pnpm,不用 npm”,写进 CLAUDE.md 一行就够了,不需要一个 Skill。
一个简单的判断方法:如果你能用一句话说出“每次做 X,都要按 A、B、C 三步来”,而且 A、B、C 在未来一个月里都不会变,那就写。如果说不出来,或者步骤每周都在变,就先别写。
Skill 到底是什么:一张卡片加一个文件夹
按 Agent Skills 开放标准的说法,一个 Skill 本质上是一个文件夹,里面必须有一个 SKILL.md 文件。这个文件分两部分:顶部的 YAML frontmatter(写在两行 --- 之间),告诉 Agent 这个 Skill 是什么、什么时候用;下面的 Markdown 正文,是 Agent 执行时要遵循的说明。除此之外,文件夹里还可以放脚本(scripts/)、参考资料(references/)和模板(assets/)。结构长这样:
my-skill/
├── SKILL.md # 必需:元数据 + 说明
├── scripts/ # 可选:可执行代码
├── references/ # 可选:参考文档
└── assets/ # 可选:模板、资源
Skill 的工作方式叫“渐进式加载”,分三个阶段。第一阶段是发现:会话启动时,Agent 只加载每个 Skill 的名字和描述,刚好够判断“这个任务可能和哪个 Skill 有关”。第二阶段是激活:任务和某个 Skill 的描述对上了,Agent 才把完整的 SKILL.md 读进上下文。第三阶段是执行:Agent 按说明干活,需要的时候再运行附带的脚本、加载引用的文件。也就是说,SKILL.md 的正文平时根本不占上下文,只有用的时候才加载。这就是为什么你可以装很多 Skill 而不用担心上下文被挤爆:发现阶段的成本只有名字加一句话描述。
这个机制直接决定了写 Skill 的第一原则:描述(description)是最重要的部分,正文是第二重要的。描述写得不好,Agent 在发现阶段就认不出这个 Skill,正文写得再好也没人读到。Claude Code 的文档说得很清楚:description 帮助 Claude 决定什么时候自动加载 Skill。所以写描述的时候,别写“这是一个很有用的工具”,要写“这个 Skill 是做什么的、在什么情况下用”,最好把触发场景写进去,比如“当用户问改了什么、想要提交信息、或者想检查 diff 时用”。
第二个原则是 SKILL.md 正文要短,细节往 references/ 里放。因为正文只有在激活之后才加载,写得太长会一次性吃掉很多上下文;而且 Agent 读到一长篇说明的时候,容易只执行前半部分、漏掉后半部分。正确的做法是:正文只写“做什么、按什么顺序、做到什么算完成”,具体的命令、表格、长篇背景都放进 references/ 里的文件,正文里只写“需要的时候读 references/xxx.md”。脚本也是一样:别把一整段脚本粘贴进正文,写成 scripts/ 里的可执行文件,正文里只写“运行 scripts/check.sh”。
从零写一个 Skill:以 changelog-entry 为例
下面用一个真实可用的例子走完全流程。假设你的项目每次发版都要写 CHANGELOG,而且你希望 Agent 能根据这次的改动自动起草一条 changelog 条目,格式固定、措辞一致。我们要写的 Skill 叫 changelog-entry。
第一步,建文件夹。个人 Skill(只给你自己用、所有项目都能用)放在 ~/.claude/skills/ 下面;项目 Skill(提交进仓库、团队共享)放在项目根目录的 .claude/skills/ 下面。这个例子先做成个人 Skill,学会了再决定要不要放进项目里:
mkdir -p ~/.claude/skills/changelog-entry
第二步,写 SKILL.md。文件分两部分。先写 frontmatter,名字和描述是必需的:
---
name: changelog-entry
description: Draft a CHANGELOG entry from uncommitted changes. Use when the user asks to write a changelog entry, summarize what changed for a release, or prepare release notes from the current diff.
---
## Current changes
!`git diff HEAD --stat`
## Instructions
1. Read the diff summary above. If it is empty, say there are no uncommitted changes and stop.
2. Group the changes by area (feature, fix, docs) based on the files touched.
3. Draft one bullet per group, in the past tense, naming what changed and why it matters to users. Do not invent changes that are not in the diff.
4. Ask the user to confirm or edit before writing anything to CHANGELOG.md. Never write to the file unprompted.
这里有三个地方值得解释。第一,description 里写了“做什么”和“什么时候用”,而且特意写了三种触发说法(写 changelog 条目、总结发版改动、从 diff 准备 release notes),因为用户每次的说法可能不一样,描述里多写几种说法,Agent 在发现阶段认出来的概率就更高。第二,`!`git diff HEAD --stat`` 这一行是动态上下文注入:Claude Code 会在 Agent 读到 Skill 之前先运行这条命令,把输出替换进去。这样 Agent 读到的不是“去查一下 diff”,而是已经摆在眼前的 diff 摘要,回答就有了依据。第三,第 4 条特意写了“写文件之前先问用户确认”,这是给 Skill 加的一道护栏:起草是 Agent 的活,落盘是人的决定。
第三步,决定要不要加脚本和参考文件。这个例子很简单,不需要脚本。但如果你的 changelog 有固定格式(比如每个条目必须带 issue 编号),可以把格式说明放进 references/format.md,正文里加一句“格式按 references/format.md”。如果你的项目要求先跑测试再写 changelog,可以加一个 scripts/precheck.sh,正文里写“先运行 scripts/precheck.sh,测试不通过就停下来”。原则是:正文保持在一屏能读完的长度,超过的部分就拆出去。
第四步,测试。打开一个有改动的 Git 项目,进 Claude Code,先直接调用一次:输入 /changelog-entry,看它能不能按你的说明起草条目。然后再测自动触发:换个说法问一句,比如“这次发版改了什么,帮我写条 changelog”,看 Agent 会不会自己加载这个 Skill。两种方式都要试:直接调用测的是“说明写得对不对”,自动触发测的是“描述写得够不够清楚”。如果自动触发没反应,问题大概率出在 description 上——回去加触发场景,别急着改正文。
放哪里:个人、项目还是插件
放的位置决定了谁能用到这个 Skill。Claude Code 的文档列了几种位置,选的时候按“谁需要它”来定。只给你自己用的,放 ~/.claude/skills/,所有项目都能用,但云端会话(Cowork、云端定时任务)读不到你本机的个人 Skill,想在云端用要去 claude.ai 的设置里启用。团队共享的,放项目根目录的 .claude/skills/,提交进仓库,所有人拉下来就有了。Monorepo 里也可以在子目录下放 .claude/skills/,只对那个子目录里启动的会话生效。插件里的 Skill 则是跟着插件走的,启用插件的地方都能用,调用时要加插件名前缀,比如 /plugin-name:skill-name。
一个实用的经验是:先放个人位置试两周,确认这个 Skill 真的有用、步骤稳定了,再挪进项目里共享。反过来做很容易出问题:直接放进项目里,团队每个人都被一个半成品 Skill 打扰,改起来还要考虑所有人的使用情况。先个人、后项目,成本最低。
名字冲突的时候有一套优先级:企业级大于个人,个人大于项目;你自己写的 Skill 会替换掉同名的内置命令,但替换不了它的别名。比如你在项目里写了一个叫 code-review 的 Skill,它会替换掉内置的 /code-review,但内置的别名 /review 还是跑内置的那个。另外,别把文件夹起名叫 synced,也别用 anthropic-skills 开头,这两个是保留名字,用了不会加载。
还有一个放位置时容易踩的坑:单仓库(monorepo)和工作树(worktree)。在单仓库里,Claude 会从你启动的目录一路往上加载项目级 Skill,直到仓库根目录;你在子目录里读文件、改文件的时候,那个子目录里的 Skill 也会被加载进来。工作树的情况也类似:从 2.1.277 版本开始,如果工作树里没有自己的项目级 Skill,Claude 会加载主检出(main checkout)里的那一份。所以一个 Skill 到底在哪些目录里生效,不只看它放在哪,还要看你是在哪个目录里启动 Claude 的。写 Skill 的时候顺手想一下它会在哪些目录被加载,比事后发现它在不该出现的地方冒出来要好。
验证与维护:写完不是结束
Skill 写完之后要过三道验证。第一道是直接调用:/changelog-entry 能不能跑通,输出是不是你要的格式。第二道是自动触发:换三种不同的说法问同一个需求,Agent 能不能自己找到这个 Skill。三次里有一次没触发,就回去改 description——触发场景写得越多、越具体,触发率越高。第三道是“新人测试”:找一个没用过这个 Skill 的同事(或者开一个新会话、假装自己不知道这个 Skill 的存在),只凭任务描述让 Agent 干活,看它会不会自己用上。过不了第三道,说明这个 Skill 只对写它的人有用,描述里藏了只有你知道的暗语。
Claude Code 自带的 /doctor 命令能帮你做一部分检查。它会报告哪些 Skill 从来没被用过、哪些 Skill 和 CLAUDE.md 里的内容重复了,还会建议把 CLAUDE.md 里长出来的流程搬进 Skill。/doctor prompt-audit 则是检查你的 CLAUDE.md、Skill 和其他配置文件里有没有过时或者互相冲突的说明。养成习惯:每月跑一次 /doctor,把没用过的 Skill 删掉,把冲突的说明修掉。
维护上最容易犯的错是“写完就忘”。流程变了,Skill 没跟着变,Agent 就会按过时的步骤干活,而且你很难发现——因为它看起来还是在正常工作。所以每个 Skill 都要有一个“保质期”意识:流程变了,第一时间改 Skill;流程没人用了,就删掉。删 Skill 不心疼,留着一个过时的 Skill 才是真的贵:它会在每次触发时把错误的做法再教给 Agent 一遍。还有一个容易被忽略的维护动作:定期读一遍 Skill 的正文,删掉那些“当时觉得有用、现在从来没触发过”的步骤。Skill 和代码一样,也会长出用不上的分支,定期修剪才能保持好用。最后,Skill 之间不要互相抄正文:两份内容差不多的 Skill,不如合并成一份、把差异写成可选步骤,否则改了一处、漏了另一处,迟早会互相打架。
五个常见错误
第一个错误是描述写得太空。“帮你提高效率”“处理各种开发任务”这种描述等于没写,Agent 在发现阶段根本没法判断什么时候该用它。描述要写成“做什么 + 什么时候用”,最好带上触发场景。一个能用的检查方法是:把描述念给一个不了解这个 Skill 的同事听,他能不能说出“哦,这个是发版前用的”?能,就合格;不能,就重写。
第二个错误是把所有东西都塞进 SKILL.md。有的 Skill 正文写了上千字,从背景讲到历史,从命令讲到注意事项。Agent 读到后面就开始丢步骤。正确的做法是正文只留骨架:做什么、按什么顺序、做到什么算完成。细节、表格、长篇背景全放 references/,脚本放 scripts/,正文里只写文件名。
第三个错误是把项目路径写死在个人 Skill 里。个人 Skill 会在所有项目里加载,里面写了“去 /Users/xxx/myproject 里找配置文件”,换个项目就跑不通。个人 Skill 里只写通用的流程,项目特有的路径、命令、约定,放到项目 Skill 里,或者写成用动态上下文注入去查(比如 !`git rev-parse --show-toplevel`),而不是写死。
第四个错误是该用别的东西却用了 Skill。需要接外部工具、查实时数据,优先考虑 MCP Server;只是一条固定命令,写个 .claude/commands/ 下的命令文件就够了——命令文件现在和 Skill 用同一套 frontmatter,而且老格式依然能用。Skill 的位置是“多步骤流程 + 需要反复用的知识”,别拿它去干命令和 MCP 的活。
第五个错误是写了从来不验证。直接调用跑通了就以为完事了,自动触发从来没测过。结果是这个 Skill 只有你自己想起来的时候才用得上,Agent 永远不会主动想起它。记住验证的三道关:直接调用、换说法自动触发、新人测试。三道都过了,这个 Skill 才算真的写完了。
从哪一个 Skill 开始
别从最复杂的流程开始。选你这周重复了三次以上、步骤固定、出错代价不大的那件事。比如发版前的检查清单、写提交信息、整理 diff、准备 release notes。先写一个,跑两周,看看它是不是真的省了你的时间,再写第二个。第一个 Skill 的目标不是“写出完美的 Skill”,而是“走通一次完整的流程”:写、测、改、再测。
如果你已经有一个现成的检查清单躺在某个文档里,那是更好的起点:把清单搬进 SKILL.md,加上 description,再配一个动态上下文注入(比如 !`git status --short`),你就已经有了一个能用的 Skill。剩下的工作是慢慢打磨:描述写得更准一点,正文拆得更干净一点,脚本加上去一点。Skill 是越用越顺手的工具,不是一次写成的作品。
最后提醒一件事:Skill 的真正价值不在“写”上,而在“被用”上。一个写得完美但从来没被自动触发过的 Skill,等于不存在。写完之后的两周里,特意留意一下:Agent 有没有在你没点名的情况下自己用上它?如果有,说明你的 description 写对了,这个 Skill 已经从“你的笔记”变成了“Agent 的工具”。如果没有,回去改描述,别改正文——大多数 Skill 用不起来的原因,都在描述那两行字里,而不是正文那几十行里。
评论 (0)
原始来源
相关文章
函数你每天都在调,这篇把你一直在做的事讲清楚。本文按 MDN 的《Functions》《Arrow function expressions》《Rest parameters》三篇官方文档讲清楚:声明与表达式、参数与实参、默认值、剩余参数、展开语法、返回值、箭头函数省写规则、this 的坑、回调与高阶函数、作用域。
JavaScript 里数字只有一种类型 Number,存成 64 位浮点数,所以 0.1 + 0.2 等于 0.30000000000000004。本文按 MDN 的《Basic math in JavaScript》《Math》《Number》三篇官方文档讲清楚:一种数字类型、浮点误差、钱改成分算、字符串转数字、NaN 与 Infinity、安全整数、四种取整、Math.random、Math 工具箱与显示格式化。
Flexbox 一次只排一个方向,排对了,导航栏、卡片墙、购物车行都听话。本文按 MDN 的《Basic concepts of flexbox》《Aligning items in a flex container》《Controlling ratios of flex items along the main axis》三篇官方文档讲清楚:两根轴、容器与项目、方向与换行、剩余空间、flex 三件套、两根轴上的对齐、间距与自动边距。