读完这篇，你会明白 Skill 到底是什么、怎么被触发、为什么不能「又长又全」；然后跟着我动手，写出一个可以直接复制进
.claude/skills/的迷你 Skill；最后带走一条判断------什么时候不该写 Skill。
背景与动机
用 Claude Code 一段时间后,我发现自己一直在做重复的事:把随手记的笔记整理成博客草稿、把零散想法梳理成文档结构、按固定流程跑某些检查。每次都要重新交代一遍背景、步骤和语气要求------很烦,而且交代得不够清楚时,结果还不稳定。
Skill 就是来解决这个的:把你做某类事的流程,写成一份「给 Claude 的说明书」,一次写好,反复使用。
但刚入门时最难受的,不是没有文档------而是文档一摞一摞,你却不知道「这玩意儿到底怎么用、怎么才能写出一个能用的」。这篇文章就是给那时的你写的:不求覆盖所有细节,只求让你真的会用、真的能写出第一个属于自己的 Skill。
目标读者:会一点 Claude Code、刚接触 Skill 的开发者。
读完能带走三样东西:
- 用对现成的 Skill(知道它怎么触发、怎么选、别踩哪些坑)
- 有能力写出第一个属于自己的 Skill(附完整可复制的文件)
- 一套判断「要不要写 Skill、该用哪种机制」的方法
Skill 到底是什么
一句话大白话:Skill 是放在磁盘上的一份「给 Claude 的说明书」------告诉它遇到什么任务、按什么流程、用哪些工具去干活。写一次,它就稳定地替你重复做这类事。
最小的 Skill 只有一个文件:
bash
.claude/skills/<名字>/SKILL.md它分两部分:
yaml
---
name: note-to-draft
description: 一句话说清这个 skill 干嘛的 + 触发场景
allowed-tools: [Read, Write, Edit] # 可选,限制可用工具
---
## 工作流程
1. 第一步要做什么
2. 第二步要做什么
...name:技能名。用来手动调用(/note-to-draft)。description:触发开关。这句话会被语义匹配,决定 Claude 什么时候想到用这个 Skill。allowed-tools:最小权限(可选)。限制这个 Skill 能用哪些工具,不给它留走捷径的空间。
注意:frontmatter 必须被 --- 上下包裹 ,少一个 --- 就不生效------这是新手第一个高发坑,后面踩坑清单会再提。
核心机制
理解 Skill 为什么这么设计,是写对它、用对它的前提。这一节讲三件事:它怎么被触发 、为什么不能一次把全部内容塞进上下文 ,以及它和 rule / hook 的边界在哪。
触发机制:description 才是开关
初学者的第一大误解是:以为 description 管流程、正文管触发------其实正好反了。
description管触发:Claude 读到你输入的内容,在语义上和某个 Skill 的 description 匹配,就把它「请上场」。- 正文管行为:触发之后,正文里的工作流程才生效。
所以写 Skill 的时候,description 是重中之重。它要满足两件事:
- 一句话说清功能------「将随手笔记整理成结构化博客草稿」
- 包含触发词------「整理笔记」「笔记转博客」「把想法写成文章」「润色成文」
触发词别贪多,塞一大堆反而稀释语义匹配的精度,容易误触发。
除了自动语义匹配,也可以手动点名 :输入 /技能名,绕过语义匹配直接触发。这是测试 Skill 时最可靠的方式。
渐进式披露:为什么不能一次全塞进去
这是 Skill 机制最精妙的设计,也是理解「为什么 Skill 要写小」的钥匙。
先算一笔账。假如你攒了 20 个常用 Skill,每个几十到上百行,粗算一个几千 token。如果每次都把全部 Skill 的内容塞进上下文:
- 20 个 × 几千 token ≈ 好几万 token 的上下文,每次对话开局就背着这个包袱;
- 而且绝大多数 Skill 这次根本用不上------用不上的东西,对模型来说就是纯噪声,还会干扰它对当前任务的判断。
所以 Skill 用了渐进式披露,分三层加载:
- 对话开始,只载入所有 Skill 的
description------占用极小; - 某个 Skill 被触发后,才载入它的正文;
- 正文里提到的辅助文件(
references/、scripts/),用到时才读。
这套设计的本质,是提升上下文的信噪比、省 token。它也直接推导出写 Skill 的第一铁律:
「小而准」 > 「又长又全」。
渐进式披露是机制层面的保障,「写小」是作者层面的自觉------两者是一个硬币的两面。
三兄弟:skill / rule / hook
刚入门很容易把 .claude/ 下的几个机制搞混。我用「三兄弟」来记:
三个机制不互相替代,适用场景不同:
- rule(常驻守则):项目公认的规范,希望每次对话都默认生效------用 rule。
- Skill(按需说明书):针对某项任务沉淀下来的 SOP,用到才加载------用 Skill。
- hook (节点拦截):需要 100% 触发的场景,比如拦截
rm -rf这种危险命令------必须用 hook。
这里藏着最重要的一个判断:hook 是确定性的,Skill 是概率性的。
Skill 的触发靠 LLM 语义匹配------它会漏触发,也会误触发。而 hook 挂在生命周期节点上,到点必然触发。所以任何「必须拦住、不能赌」的场景,都不能用 Skill 凑合,必须用 hook。能容忍概率的,才用 Skill。
实践示例
原理讲完,动手。这一节带你写一个真实的 Skill,看它从错误版本 到正确版本的演化过程,以及新手最容易踩的坑。读完你手上就有一份能直接用的东西。
动手:写第一个属于自己的 Skill
我用一个真实例子带大家走一遍:「把随手笔记整理成博客草稿」------这也正是我每天都会做的事。
在项目下创建文件 .claude/skills/note-to-draft/SKILL.md,内容如下(可以直接复制):
markdown
---
name: note-to-draft
description: 将随手笔记、零散想法、会议记录整理成结构化的博客草稿。触发场景:整理笔记、笔记转博客、把想法写成文章、润色成文。
allowed-tools: [Read, Write, Edit]
---
## 工作流程
1. **收集原始素材**
- 读取用户提供的笔记内容(文本、文件、或对话中的片段)
- 识别核心观点、关键论据、待展开的想法
- 先复述确认理解,素材不足或缺关键信息时主动提问
2. **提炼主题与结构**
- 从素材中归纳出一个明确的主题与标题
- 规划结构:引言 → 主体(2--4 段)→ 结尾
- 若素材撑不起完整文章,明确告诉用户缺什么
3. **扩写为博客草稿**
- 按规划结构展开写作,口语化但有条理
- 补充过渡句与上下文衔接
- 保留原文的独特表达和个人观点,不要过度"官方化"
4. **输出与确认**
- 输出完整草稿,标注哪些是原文保留、哪些是补充扩写
- 询问是否需要调整风格、增删段落、继续打磨写完后怎么验证它真的能用?
- 保存文件;
- 在对话里输入
/note-to-draft手动触发,或者直接说「帮我整理笔记......」看它是否被语义匹配触发; - 看它是不是严格按 4 步流程走、有没有跳过「先复述确认」这一步。
这套「写 → 测触发 → 复测」的循环,建议纳入版本管理,每次改动后都复测一次。
错误写法 vs 正确写法
上面这个 Skill 不是一次写成的,而是从几个典型错误里改出来的。把它们列出来,比讲一百句理论都管用:
| 错误写法 | 正确写法 | 说明 |
|---|---|---|
| description 写「当用户说...时触发」 | 直接列触发场景 | meta 措辞不提供匹配信息,纯占长度 |
frontmatter 缺 --- 包裹 |
--- 上下包裹 |
不包裹不生效 |
| 正文只有「收集素材、提炼主题...」4 个词 | 每步给出可执行动作 | 模型才知道具体怎么干活 |
| 正文写得又长又全 | 小而准,辅助内容放 references/ |
烧上下文、拉低信噪比 |
踩坑清单 / FAQ
Q:Skill 放在哪? 个人级:~/.claude/skills/;项目级:.claude/skills/。别放进 .claude/rules/------那是放守则的地方,不是 Skill。
Q:Skill 触发是 100% 可靠的吗? 不是。语义匹配是概率性的,会漏触发、误触发。需要确定性的场景(如拦截危险命令)用 hook,别赌 Skill。
Q:写 Skill 需要什么前置知识吗? 不需要。它就是一份纯文本 markdown 说明书,会写文档就能写 Skill。难的不是写文件,是想清楚这个 Skill 该解决什么问题、怎么把流程拆成模型能照做的步骤。
我的思考:护城河不在 Skill,在方法论
Skill 文件本质是纯文本,复制成本趋近于零 。谁都能复制你的 SKILL.md------所以 Skill 本身没有壁垒。
真正的壁垒,是复制不走的三件事:
- 知道该写什么 Skill(对自身工作流的洞察);
- 知道怎么写才好用(触发词怎么打磨、步骤怎么拆、护栏怎么加);
- 知道怎么迭代(跑一次发现不好用,怎么改)。
有人可能会反驳:Skill 不就是个 markdown 文件,有什么方法论可言?我的回答是:正因为它是纯文本,所以任何一个 Skill 都不值钱;值钱的是围绕它沉淀的隐性知识。
但这里要泼一盆冷水:Skill 不会自己越跑越准。 它只是个文本文件,不会自己更新。所谓「越跑越准」,靠的是有人把每次执行的经验------上次 A/B 测试哪个方案赢了、为什么赢------手动回写进 SKILL.md。
所以更精确的说法是:
Skill 是载体,反馈闭环才是护城河;而闭环成立的前提,是维护纪律。
什么时候不该写 Skill
知道什么时候写,更要知道什么时候不写。三个问题判断:
值得写 Skill 的,是那些高频、可复用、流程相对稳定的事。新手建议先写 1--2 个「小而准」、每天都用的流程 Skill,把 description 触发词打磨好,再逐步扩展。
参考资料
- Claude Code 官方文档 · Skills 章节:机制的权威来源,写 Skill 前值得通读一遍 frontmatter 的字段说明。
写在最后
这篇博客本身就是一场 Skill 的现场演示------「把笔记整理成草稿」正是 note-to-draft 这个 Skill 干的事。Skill 的学习曲线不长,难的是动手写第一个。
强烈建议你现在就做一件事:从自己最烦的重复工作里挑一件,照文章里的结构写一个迷你 Skill,放到 .claude/skills/ 里,然后输入 /技能名 测一次。跑通了,你就有第一个属于自己的 Skill 了。
由于文章篇幅和文章定位原因，更进阶的内容没有写:怎么提高语义匹配的准确性、任务怎么拆分、任务怎么分配(该用哪种机制)、怎么用好工具(包括 MCP) 。想了解的话在评论区告诉我------如果想看的人多,我会单独开一篇,你的反馈决定我下一篇写什么。