很多人在第一次接触 Claude Skills 这个概念的时候，都会有和我一样的困惑：提示词明明已经写得很详细了，为什么每次遇到同类任务，还是要从头解释一遍？内容越长，模型越容易被无关信息干扰，行为越不稳定。这正是 Claude Skill 要解决的核心问题。而 Claude Skill Creator 2.0 这套技能创建工作流，就是帮我把"一长段提示词"变成"一个可以反复调用的技能包"的桥。
这篇文章适合三类人：还在靠手敲大段提示词干活的开发者、想把自己的工作流沉淀成可复用工具的进阶用户、以及刚听说 Agent Skills 但不知道怎么落地的初学者。我会从最基础的原理讲到完整实操，再把我这几个月踩过的坑和排查思路一并交代清楚，希望你看完能少走几周弯路。
1. 先搞清楚 Skill 到底是什么：它和普通提示词的本质区别
1.1 提示词工程的瓶颈在哪里
先讲个我自己的例子。几个月前，我有一套固定的合同审阅流程：让 Claude 看合同里的赔偿上限、违约触发条件、管辖法律条款，最后输出一份结构化风险清单。这套提示词我改了七八版，总算稳定了。但问题是，每次来一份新合同时，我都得把那一大段话重新粘贴一遍；换到另一个聊天窗口，又得从头开始。更麻烦的是，同一份提示词在不同场景里表现经常不一样，有时候它会忽略我要求输出的表格，有时候又自己加戏。
这不是提示词写得不好，而是提示词工程的三个老毛病在作祟：
- 长度失控：几千字的提示词每次都要占用上下文，消耗 tokens 不说，还会挤占真正需要处理的内容空间。
- 语义漂移：提示词改过太多版之后，前后矛盾的地方越来越多，模型优先级判断容易出偏差。
- 逻辑耦合：一段提示词里既讲目标、又讲步骤、又讲输出格式、又讲禁忌，所有信息搅在一起，模型很难分清主次。
打个比方：提示词像一张手写便签，夹带在你每个请求里；Skill 则像一本标准操作手册外加一整套工具箱。便签每次都要重新写，手册却可以摆在固定位置，需要时直接翻开用。
1.2 一个技能包到底由什么组成
一个 Claude Skill 本质上就是一个目录，目录里至少有一个入口文件，通常还会有若干附属资源。我之前建的合同审阅技能长这样：
contract-risk-review/ ├── SKILL.md ├── scripts/ │ └── extract_clauses.py ├── references/ │ ├── common_clause_patterns.md │ └── output_template.md └── assets/ └── sample_contract.md其中 SKILL.md 是入口文件，最前面有一段 YAML 格式的元信息（name 和 description），正文则是给模型看的操作指南。scripts 目录放可执行脚本或解析工具，references 放参考文档和模板，assets 放静态素材。
关键在于"分层"这两个字：说明层、代码层、素材层分开存放，模型才能做到按需读取。如果所有内容全部堆在一个文件里，那就又退回大提示词的老路了。
1.3 Skill Creator 2.0 在这套机制中扮演什么角色
需要先说明一下，Skill Creator 2.0 不是某个官方文档里的固定工具名，而是一套目前在社区里流传较广的技能创建工作流模板。我用下来的体会是，它把创建技能这件事拆成了三个固定阶段：需求结构化、骨架生成、验证回归。2.0 相比早期版本最大的变化，是把 description 的写作单独拎出来做了一轮强化，并且增加了资源目录的自动规划。
我自己习惯把这套流程沉淀成一个固定的对话模板。每次要创建新技能，我不再凭空让 Claude 写文件，而是先按模板整理需求，再让 Claude 基于需求生成完整骨架，最后自己逐个文件核对。这个固定节奏看起来多花了几分钟，但产出的技能质量稳定非常多。
2. 从零开始：环境准备与第一个技能包的完整生成过程
2.1 开始之前需要准备什么
动手之前，先把下面的东西准备好，全程大概十分钟就能搞定：
- Claude 客户端：桌面版、网页版还是命令行版本都可以，看你平时习惯用哪个。
- 本地技能目录：我习惯统一放在
~/claude-skills/下，或者放进具体项目的.claude/skills/目录里。个人建议项目级技能放项目目录，通用技能放用户级目录，这样职责分明。 - 文本编辑器：任意一款都行，最好支持 YAML 语法高亮，检查 frontmatter 时会省很多眼力。
- 基础 YAML 认知：会认键值对、缩进和列表就够了，不需要精通。
这里想多说一句：如果你完全不会写代码，也不用慌，只靠 SKILL.md 文本内容一样能创建技能。脚本资源只是锦上添花，不是必需品。
2.2 需求描述模板：Skill Creator 2.0 最核心的一步
很多人让 Claude 生成技能时直接丢一句"帮我做一个合同审阅技能"，出来的东西往往泛泛而谈，因为需求本身没有结构化。Skill Creator 2.0 的第一步，就是先把需求填进下面这个模板：
任务目标：这个技能要帮用户完成什么？ 适用场景：用户在什么情况下会需要它？ 输入信息：用户会提供哪些材料或参数？ 输出要求：交付物是什么？格式如何？ 边界条件：哪些情况不处理？哪些情况必须明确提示？ 质量校验：如何判断这次执行是否成功？ 示例输入：给一个最小可用例子。以合同审阅技能为例，我当时的填写是：
任务目标：对英文合同条款进行风险审阅，识别高风险条款并输出结构化意见。 适用场景：用户提供英文合同文本或合同片段，要求审查、审阅、评估法律风险。 输入信息：合同原文，可能包含部分条款或完整合同。 输出要求：按条款逐项输出风险等级、理由、修改建议的表格。 边界条件：不提供法律意见，只做条款风险提示；无法识别条款时明确说明。 质量校验：每个高风险条款必须给出具体条款内容和修改建议。 示例输入：一份包含赔偿上限条款的采购合同。这一步为什么重要？因为 Claude 在生成技能时，能依据的信息质量直接决定最终产物质量。需求模糊，产出的技能就模糊；需求里有明确边界和质量标准，产出的技能才具备可执行性。
2.3 用模板驱动 Claude 生成技能骨架
完成需求描述后，把它和下面这段指令一起发给 Claude：
请根据以下需求描述，输出一个完整的 Claude Skill 技能包： 1. 生成目录结构； 2. 编写完整的 SKILL.md 文件，包含 YAML frontmatter 和正文； 3. 如果需求中涉及固定计算或批量处理，建议在 scripts 目录补充脚本； 4. 最后输出一份一分钟检查清单，方便我核对。当时生成出来的 SKILL.md frontmatter 长这样：
--- name: contract-risk-review description: 用于对英文合同条款进行风险审阅，识别赔偿上限、违约触发条件、管辖法律等高风险条款，并输出结构化审阅意见。当用户提供英文合同文本或合同片段并要求审查、审阅、评估风险时使用。 ---正文部分则按"目标、输入、输出格式、注意事项"四段组织。整个生成过程不到两分钟，但比起我最初手动写的版本，结构清晰太多了。
2.4 生成之后先别急着用：四步体检
Claude 生成的技能文件不能直接信，我每次都会做一个快速体检：
- 通读一遍 description，把自己当成模型：看到这个描述，遇到同类任务时会不会调用它？
- 检查 name 是否和描述语义一致，目录名是否与 name 匹配。
- 通读正文，找有没有互相矛盾的指令，比如前面说"输出表格"，后面示例却给了一段散文。
- 检查 references 和 scripts 里的引用路径是否真实存在。
这一步花不了五分钟，但能省掉后面大量的返工时间。我见过太多人跳过体检直接投入使用，结果技能加载失败后怀疑模型出了问题，其实最根本的问题在第一项就埋下了。
3. SKILL.md 的字段玄机：为什么说 description 决定了技能的生死
3.1 自动加载机制的逻辑
Claude 在面对一项任务时，并不会把技能目录里所有文件都读一遍，而是先扫描所有技能的 description，判断当前任务和哪个技能匹配，匹配上了才加载对应的 SKILL.md 和资源文件。
也就是说，每个技能就像图书馆里的一本书，书名和内容简介决定了它会不会被人借走。你在正文里写得再详尽，如果 description 没有准确描述应用场景，模型根本不会打开这本书。
这一点是初学者最容易忽略的。很多人把全部精力花在写正文上，description 随手一句话带过，结果技能长期不被调用，还以为是功能有问题。
3.2 description 写作的常见误区与正确姿势
我整理了一下自己踩过的坑，description 常见有三种错误写法：
| 写法 | 问题 | 效果 |
|---|---|---|
| "用于合同审阅" | 缺少触发场景，模型不知道什么时候该用 | 几乎不会被加载 |
| "处理所有文本工作" | 范围太泛，任何场景都可能误加载 | 行为混乱，输出不可控 |
| "当用户提供英文合同并要求风险审阅时使用，覆盖赔偿、违约、管辖等条款" | 场景、动作、内容边界都齐全 | 触发准确，加载稳定 |
第三行就是我觉得比较理想的写法：包含使用场景（提供英文合同、要求风险审阅）、包含动作（识别高风险条款并输出意见）、包含内容边界（赔偿、违约、管辖）。模型只需要读这一句话，就能做出是否加载的判断。
3.3 name 的命名规则
name 字段看似简单，实际也有一些讲究：
- 统一用 kebab-case 或 snake_case，比如
contract-risk-review，避免空格和中文。 - 尽量采用"领域+动作"的结构，让别人（也让自己）一眼看出技能用途。
- 不同技能的 name 不要高度相似，否则容易互相干扰。
我见过有人给合同审阅技能命名analysis，给周报技能命名weekly-analyst，两个描述里都提到了"分析"，模型经常拿错文件。后来统一改成finance-contract-review和weekly-report-writer，问题立刻消失。
3.4 正文部分的组织原则
SKILL.md 的正文不用写成论文，但关键约束必须出现在里面。根据我的实测，模型对明确的"必须"和"禁止"遵守率远高于含混的期望描述。正文组织我一般遵循四个原则：
- 先说目标和边界，让模型知道这个技能能做什么、不能做什么。
- 再说操作步骤，步骤控制在五到十条之间，每步只讲一件事。
- 接着给输出模板或示例，把格式固定下来。
- 最后列禁忌项，明确哪些行为不被允许。
举个例子，合同审阅技能正文里的禁忌我会写成：
## 注意事项 - 必须基于合同原文逐条判断，不得臆测条款内容。 - 缺少原文的条款不得编造风险点。 - 本技能仅提示风险，不提供最终法律意见。 - 输出必须使用表格，不得用散文叙述。这样写的好处是，模型的每一次执行都有明确的行为边界，不会因为对话上下文变化而飘移。
4. 进阶调优：把技能从"能跑"做到"好用"
4.1 用"输入占位"让技能保持通用
一个好的技能指令应该是模板化的，而不是面向某一次具体输入的。我习惯在 SKILL.md 中用明确的占位符标出用户需要补充的内容，比如{{合同文本}}、{{输出语言}}。
占位符不是某种官方解析语法，它只是一种写作约定，目的是让模型在执行时清楚区分"用户输入"和"指令本身"。这样同一个技能既能处理采购合同，也能处理服务协议，只需要替换占位符位置的内容。
4.2 用示例锁定输出格式
"输出请用表格""注意格式规范"这类话写十遍，不如直接在正文里放一个输出示例。模型对具体示例的模仿能力，远强于对抽象指令的理解。
以风险审阅技能为例，我在 references/output_template.md 里放了这样一段：
| 条款编号 | 风险等级 | 风险描述 | 修改建议 | | --- | --- | --- | --- | | 第8条 | 高 | 赔偿上限过低，仅覆盖合同金额的10% | 建议提高到30%并增加例外条款 |后面实际使用时，模型输出的格式和这个模板保持得非常一致。格式类需求，能用示例解决的，就不要用长篇描述去交代。
4.3 技能之间要划清边界
当技能数量多起来之后，最大的问题不是单个技能不好用，而是技能之间互相抢活儿。描述都写了"分析""评估""总结"这些泛化动词，模型根本分不清哪个是哪个。
我的经验是：一个技能只解决一个问题，并在 description 里明确排除不属于自己的场景。比如合同技能里加一句"本技能不处理非合同类文档的分段总结"，周报技能里加一句"本技能不涉及合同条款解读"。这句话能极大减少误加载的概率。
4.4 给技能配脚本：什么时候该写代码
纯文本指令适合流程性任务，但遇到固定计算或批量提取时，脚本比指令可靠得多。我做过一个技能，需要从几十份合同里批量提取签约日期和金额，纯靠模型指令做，总有个别合同被遗漏。后来在 scripts 目录放了一个处理脚本，SKILL.md 里明确写"遇到批量文件时先运行 scripts/extract_dates.py"，稳定性立刻上来了。
给脚本写说明时有三个关键点：用什么命令运行、输入文件放哪里、输出格式是什么。SKILL.md 里这三项缺一不可，否则模型不知道该不该调用脚本、怎么调。
4.5 版本管理与回归测试
技能不是写完就完了，它需要迭代。我每改一版，都会在技能目录里记一句改动说明，同时维护一个 test-cases 文件，里面放五六组固定输入。每次改完代码，用这组输入重新跑一遍，对比输出有没有发生漂移。
这个习惯救过我一次。某次我在合同技能的正文里加了一段新指令，导致原有的输出格式完全变了，如果不是回归测试及时发现，那份技能在正式环境里会出大问题。
5. 实测中遇到的典型问题与完整排查链路
5.1 技能始终不被调用：从目录到描述的逐层排查
这个问题我遇到得最多，也最让人头疼，因为表面上看一切都正常，技能就是不生效。经过几次折腾，我整理出一套排查顺序：
- 检查目录位置：技能目录是否在 Claude 会扫描的范围内。项目级技能要放在
.claude/skills/下，用户级技能要放在用户配置目录下，放错位置等于白建。 - 检查文件名：入口文件必须叫 SKILL.md，大小写不能错，我之前用过一次
skill.md，加载直接失败。 - 检查 frontmatter 格式：name 和 description 两个键名是否写对，缩进是否一致，多余的引号有没有导致 YAML 解析失败。
- 检查 description 是否过窄或过泛：真实对话中用户不会说"现在触发合同审阅技能"这种话，description 描述的自然语言场景要和用户的真实表达接近。
- 检查是否和其他技能的 description 冲突：两个技能描述高度相似时，模型可能始终加载其中某一个。
大多数情况下，问题都出在第 4 步。我之前在 description 里写"用于对英文合同条款进行专业评估"，听起来没问题，但真实用户更可能说的是"帮我看看这份合同有没有问题"。后来我把描述改得更贴近真实口语，加载率明显提升。
5.2 技能被加载了，但输出和预期差距很大
这类问题通常不是加载失败，而是指令组织有问题。典型情况有三种：动作指令不够完整、缺少输出模板、需求里存在自相矛盾。前两种上面已经讲过对应的解法，这里重点说说第三种。
我在初版合同技能里写过"输出必须简洁"，同时又在示例里放了一段很详细的条款分析。模型就困惑了：到底简洁还是详细？加入输出模板后，我用模板本身的篇幅来定义"详细"的尺度，删掉了"必须简洁"这句抽象描述，问题立刻解决。抽象描述是矛盾的高发区，能用具体示例定义的东西，不要用形容词。
5.3 路径与编码问题：细节里的小坑
在我用过的各种配置里，最容易被忽略的是路径和编码问题，我第一次遇到时排查了很久。
- 技能目录和文件名尽量用英文。中文目录名在部分场景下会导致资源引用失败，不是必然发生，但没必要赌。
- 所有文件统一 UTF-8 无 BOM 编码。Windows 自带的编辑器有时会写入 BOM 头，YAML frontmatter 解析可能因此出错。
- Windows 换行符 CRLF 和 Unix 的 LF 也可能引发问题，建议统一用 LF，Git 里也可以配置自动转换。
- 脚本和资源引用路径必须相对 SKILL.md 所在目录写，不要写绝对路径，否则换环境就废了。
这些细节单个看都不大，但叠加起来就是一场排查噩梦。建议新技能落盘时直接把这几项一起检查掉。
5.4 多技能互相干扰：命名空间与描述排除
技能数量超过五六个之后，互相干扰开始出现。具体表现为：喂给模型一份合同，加载出来的却是"数据分析报告技能"。
原因通常是两个技能的 description 都包含"分析"这个高频词。我的解法是给每个技能加领域前缀，并在 description 末尾声明自己不做什么。比如：
description: 用于审阅英文合同中的赔偿、违约、管辖等高风险条款并输出结构化意见。当用户要求合同审查、风险审阅时使用。本技能不处理通用数据分析任务。"本技能不处理……"这句话看着不起眼，但它能非常有效地削减模型误匹配的概率。如果你的技能命名已经统一了领域前缀，这句排除式描述基本可以做到万无一失。
6. 一些我个人的使用习惯和最后提醒
说了这么多，最后再补几条我在实际使用中沉淀下来的习惯。
第一，技能仓库一定要分类管理。我的用户级技能目录里会分writing/、analysis/、document/三个子目录，每个技能再按"技能名-版本号"命名。虽然 Claude 并不强制要求这种结构，但维护久了，你一定会感谢当初这个决定。
第二，先做最小技能，再逐步加功能。很多人在第一个技能上就追求大而全，结果一个 SKILL.md 写了三千字，模型行为反而难以控制。我现在的做法是先做一个只覆盖 80% 高频场景的最小版本，跑通之后再把低频需求做成第二个技能。
第三，每隔一段时间，用"新用户视角"重新读一遍自己的技能正文。人在写的时候很容易默认读者知道一些背景，但模型没有这个背景。如果一段指令在你读起来都需要想一下，那它在模型那里大概率是失效的。
第四，Skill Creator 2.0 这套模板不只是用来创建新技能的。我经常把旧技能完整粘贴给 Claude，让它按 2.0 的需求结构化模板重新梳理一遍，相当于给老技能做一次重构，经常能发现之前埋下的隐患。
总而言之，Claude Skill 这套机制的核心价值，是让模型的能力扩展变得模块化、目录化、可复用。Skill Creator 2.0 的价值则是把"如何创建技能"这件事本身变成了一条稳定可复制的流水线。你不需要记住所有细节，只需要把第一个技能完整走一遍流程，整个逻辑自然就通了。
