creating-skill

创建 Skills

创建可移植、可复用的专业知识，让 Claude 在不同上下文中具备更强的能力。

Skill 的用途 — 编写前请阅读

Skill 是一种流程锚点。在 528 组配对执行中进行测量后发现，Skill 的效果有 65.7% 来自提供可用的流程——设置步骤、工具顺序、中间检查、注意事项；只有 4.5% 来自提供 Agent 原本不具备的事实（Jiang 等人，2026 年，arXiv:2608.14036）。

以下三点决定了下方的每条规则：

1. 流程才是交付成果。 由三到五个步骤构成的高层计划，成功率为 47.7%，低于不使用 Skill 时的 50.0%。将相同经验写成完整的 SKILL.md，成功率则为 79.2%。含糊不清比保持沉默更糟。
2. 抽象是有代价的。 skill_guidance_misapplied_or_ignored 在不使用 Skill 时的发生率为 0.8%，使用 Skill 时则为 10.0%。如果 Skill 从未说明何时不适用，就没有发挥其价值。
3. 事实是参考资料，不是 Skill。 编写事实资料没有问题，但应将其称为参考资料，不要指望它能改变行为。

在编写或审核 SKILL.md 前，先加载 references/skill-utility-evidence.md。其中包含支撑本指南所有要求的失败模式表；阅读它有助于避免机械地遵循这些规则。

何时创建 Skills

适用场景：

• 需要在多个项目或对话中使用的能力
• 可广泛应用的流程性知识（而非特定于某个项目）
• 应根据触发模式自动启用的指令
• 希望创建可移植的专业知识，并按需渐进加载

不适用场景：

• 上下文仅适用于特定项目（请改用项目指令）
• 一次性任务（请改用独立提示词）
• 详细的决策框架请参阅 crafting-instructions Skill

Skill 结构

每个 Skill 都是一个目录，包含：

• SKILL.md（必需）：Frontmatter 和祈使式指令
• scripts/（可选）：用于确定性操作的可执行代码
• references/（可选）：按需加载的详细文档
• assets/（可选）：输出中使用的模板或文件

直接创建此结构：

mkdir -p skill-name/{scripts,references,assets}

打包前删除未使用的目录。

命名约定

使用动名词形式（动词 + -ing）：

• ✅ processing-pdfs、analyzing-data、creating-reports
• ❌ pdf-helper、data-tool、report-maker

要求：

• 仅使用小写字母、数字和连字符
• 最长 64 个字符
• 不得使用保留词（anthropic、claude）

Frontmatter 要求

---
name: skill-name
description: What it does. Use when [trigger patterns].
---

name： 遵循上述命名约定

description：（最多 1024 个字符）

• 使用第三人称：「Processes files」，而非「I process files」
• 说明它能做什么，以及何时使用（触发模式）
• 指明应触发此 Skill 的文件类型、关键词和任务类型
• 不得包含任何尖括号 — 此规则比「不得使用 XML 标签」更严格。上传时，-> 箭头或 >200MB 阈值也会像 <tag> 一样遭到拒绝。

良好示例：

• "Creates PowerPoint presentations. Use when users mention slides, .pptx files, or presentations."
• "Analyzes SQL queries for performance. Use when debugging slow queries, optimization requests, or EXPLAIN output."

无效示例：

• "I can help create presentations"（第一人称，没有触发条件）
• "Presentation creator"（没有触发条件，描述含糊）
• "Advanced presentation creation with animations"（实现细节过多）

描述至关重要——它决定 Claude 何时启用此 Skill。

描述会与相邻条目竞争

描述不会孤立地被阅读——它会与其他每个技能进行排名，而与它含义最接近的技能最可能胜出。混淆度，而非目录规模，才是压力来源：在包含无关干扰项的 100 项集合中，嵌入向量 Top-1 准确率降至 84.1%；在包含近邻干扰项时则降至 53.4%。而在个人目录中，每个干扰项都是近邻。

根据此目录上的测量结果，得出四条规则：

1. 先写问题的对象，而不是技术。用户会询问符号，而不是 AST。
2. 列出用户实际输入的字面说法。 某技能在自身查询上的得分为 4/5，正是因为其描述包含“de-claude”“humanize this”“this reads like AI”。
3. 通过省略与近邻区分，而不是添加免责声明。 检索器会对含义词袋进行评分，无法表示否定，因此“does not debug a Docker build”会被理解为“Docker build”，反而让你更接近你所声明不涉及的内容——两个技能的余弦相似度分别实测上升了 +0.05 和 +0.10。路由说明应放在正文的 When NOT to use 下，由 LLM 阅读并理解否定。描述用于评分；正文用于阅读。
4. 不要重复同类技能的触发短语。 tree-sitting 列出了“map this codebase”和“explore repo”——这两者都属于 exploring-codebases 的范畴——结果它自己的五个标准查询全都未能命中。

发布前先运行检查。 oaustegard/claude-workspace 中包含此检查：

python3 scripts/skill_confusability.py --queries q.json

正向查询放在技能自己的名称下；负向查询放在保留键 __none__ 下。查看三个数字：top-1（技能能否在自己的查询中胜出）、steals（技能是否会在其他技能的查询中胜出）、near-misses（本应忽略的内容是否得分并进入命中范围）。只针对 top-1 调优的描述，会更容易被找到，也更难避免妨碍其他技能。

完整测量结果和逐条款实验： references/skill-utility-evidence.md。

使用 Anthropic 的验证器验证 frontmatter，而不是凭目测

描述写得足够详细才容易被找到，但也可能长到违反规范。未加引号的 : 会结束 YAML 标量，导致文件停止解析；尖括号则会被直接拒绝。无论哪种情况，技能都会静默地无法加载，因为读取时不会验证 frontmatter。

不要自己手写这项检查。skill-creator 自带验证器，而且它比任何值得重写的工具都严格：

python3 /mnt/skills/examples/skill-creator/scripts/quick_validate.py <skill-dir>

它会强制检查 YAML 是否可解析、属性是否在允许列表中（name、description、license、allowed-tools、metadata、compatibility）、名称是否为 64 个字符以内的 kebab-case、描述是否少于 1024 个字符且不含尖括号，以及每个目录中是否恰好有一个 SKILL.md——Skills API 和 claude.ai 上传时会拒绝多个文件，尽管 Claude Code 的文件系统可以加载它们。

批量编辑前，先对整个目录运行验证：

for d in */; do
  printf '%-24s ' "${d%/}"
  python3 /mnt/skills/examples/skill-creator/scripts/quick_validate.py "$d" 2>&1 | tail -1
done

问题于 2026-08-24 查出，一次检查中发现两次。第一次：两个技能的未加引号描述中包含 Primitives: depends_on... 和 makes skills work: a concrete...，导致两个文件都无法解析。第二天又发现：某个描述包含字面文本 "review what's new in <repo>"，违反了不得使用尖括号的规则。正则表达式读取器——包括 skill_confusability.py——都会欣然接受这三种情况，因此检索检查通过了，技能却已无法使用。quick_validate.py 大约一秒就能捕获所有问题，而且它一直都在磁盘上。

编写有效的 SKILL.md

应用 writing-instructions 原则：

使用祈使句

采用直接命令的表达方式：

• ✅ “使用 pdfplumber 提取文本” / “使用脚本验证输出”
• ❌ “考虑提取……” / “你可能需要验证……”

具体流程，战略判断

将两者分开。明确写出操作步骤；是否执行则留作判断。

明确写出——这是技能存在的目的，占 65.7%：

• 配置和依赖的安装顺序，以及实际命令
• 工具的使用顺序，以及重要的标志
• 中间检查，以及错误答案的表现
• 各项注意事项，以及提示问题的信号

留作判断——强行规定会导致机械地误用：

• 当前情况是否属于此技能的适用范围

• 几种合理做法中，哪种适合当前情况

• 假设不再成立时，何时放弃该流程

• ✅ "$TREESIT /tmp/$REPO --stats。对于你确定含有代码的仓库，如果符号数量为零，说明缺少 tree-sitter core；无论哪种情况，它都会以 0 退出。"

• ❌ "对仓库进行结构化扫描并检查结果。"

第二种形式就是实测中简短计划的情况：成功率为 47.7%，低于不使用技能时 50.0% 的基线。将流程删减到只剩目标，并不会让它变得更具战略性，只会让结果比完全没有流程更糟。

显而易见的步骤仍应保持简洁——mkdir -p skill-name/{scripts,references} 写成一行，不要拆成三行。判断标准是省略某个步骤是否会让读者猜错，而不是结果看起来是否整齐。

信任基础行为

Claude 已经了解：

• 基本编程模式、常用工具和文件操作
• 如何组织清晰的输出、设置 Markdown 格式
• 代码质量方面的通用最佳实践

只说明技能特有的差异，或 Claude 不具备的领域专业知识。

使用正向指令

说明要做什么，而不是要避免什么：

• ✅ "使用祈使语气，给出直接指令"
• ❌ "不要使用暗示性语言或不确定的措辞"

以正向方式表述要求，因为这样更清晰、更具可操作性。

此规则规定了指令的措辞方式，不适用于适用范围。“何时不要使用此技能”、路由表和经过验证的例外都属于内容，而非措辞；它们是必需的——请参阅下文的“适用边界”。将“不要将此用于 X”改写成“将此用于 Y”，会抹去适用边界，而不是以正向方式说明它；适用边界正是防止 10.0% 误用率的保障。两者都要保留：说明技能能做什么，也说明它的适用范围止于何处。

提供上下文

说明不明显的要求背后的原因：

• ✅ "将 SKILL.md 控制在 500 行以内，以支持渐进式加载——将详细内容移至 references/"
• ❌ "将 SKILL.md 控制在 500 行以内"

上下文能帮助 Claude 在边缘情况下做出良好的自主决策。

示例质量

示例会传授所有模式，包括无意中传达的模式。确保示例的每个方面都体现预期行为。与其提供传达混杂信号的示例，不如不提供。

如需全面的提示词编写指导，请调用 writing-instructions。 如需判断是否应该将其作为技能，请调用 crafting-instructions。

必需章节

每项会改变工作方式的技能都必须包含以下四个章节。纯参考文档可以省略这些章节——但必须在第一行说明它是参考文档，以免读者误以为它会改变执行方式。

适用范围边界

不可妥协。skill_guidance_misapplied_or_ignored 在不使用技能时为 0.8%，使用技能时为 10.0%；把看似合适的技能用在错误场景中，是技能引入的最大单项成本。请写明：

• 何时不应使用此技能——若存在同类技能，则用路由表说明：一列写适用场景，另一列写负责处理该场景的技能。请列出真实技能，而不是类别。
• 有充分理由的例外——对于任何强到有时会出错的规则，都要列出一组 banned when / earned when。declauding 是范例：它有三个这样的表格，因此在不删掉语气词所承载主张的前提下，语气词清理环节可以减少语气词。
• 何时在执行过程中放弃此技能——指出流程假设已失效、继续执行只会让情况更糟的条件。

如果技能作者说不出该技能不适用的场景，说明还没有充分考虑其适用范围。

常见失败模式

每个条目都应采用信号 → 缓解措施的形式，绝不能只写警告。信号是读者实际会看到的现象；没有信号，缓解措施就无法生效。

✅ "Zero symbols on a repo you know has code → tree-sitter core is missing.
    It exits 0 and prints no error. Reinstall before concluding anything."
❌ "Make sure dependencies are installed."

环境、输出格式和服务生命周期方面的故障，是最适合通过技能解决的一类问题——研究中，仅仅记录设置步骤，就让 environment_infrastructure_failure 从 5.3% 降至 0.2%。如果技能封装了某个工具，该工具的设置方法和静默失败信号都应写在这里。

验证

说明如何确认工作确实成功，并给出命令。技能本身不会增加运行时验证：static_verification_without_runtime 在不使用技能时为 12.5%，使用技能时为 11.7%；在整个研究中仅下降了 0.8 个百分点。只有技能要求 Agent 在运行时检查时，Agent 才会进行运行时检查。

对于会编辑或生成内容的技能，还要说明看似成功但实际不成功是什么样——也就是通过检查、却丢失了内容的输出。这类失败无法通过通读发现。

已诊断的失败及其结果标记

如果技能包含了从惨痛教训中学到的经验，请记录出错的时间、情况，以及当时出现的信号。在失败轨迹进入来源池后，构建技能时不标注结果，导致研究中的消融实验得分下降了 15 到 35 个百分点——未标注结果的失败案例看起来就像可以照搬的流程。

✅ "Diagnosed 2026-08-22 on a FreeToken review: a 5,697-line gather was cut at
    line 120 and every finding came from targeted reads instead. Use --orient."
❌ "Use --orient for reviews."

要写明日期和具体细节，不能只说“已知问题”。并且要把这些内容放在一套行之有效的流程中：几乎在所有配置下，纯粹从事后分析中提炼出的技能，其效果都低于不使用技能的基线。失败案例应作为有效流程的注释，而不能取代流程。

捆绑资源模式

决策框架： Claude 是否会反复生成类似代码？→ 使用 scripts/。 领域知识是否十分丰富，或 SKILL.md 是否接近 500 行？→ 使用 references/。 是否有用户会收到的输出模板？→ 使用 assets/。 否则仅使用 SKILL.md。

脚本需要明确处理错误，并清晰输出结果——静默失败的脚本比没有脚本更糟，因为技能随后会报告成功。references/ 中的内容应保持一层深；assets/ 会被使用，但不会读入上下文，因此不会占用上下文。

完整模式和示例： references/bundled-resources.md。

渐进式披露

技能分三个层级加载：

1. 元数据（名称 + 描述）：始终为所有技能加载
2. SKILL.md 正文：技能激活时加载
3. 捆绑资源：Claude 读取时加载

让 SKILL.md 聚焦于核心工作流（最多约 500 行）。将详细内容移至 references/，以便按需加载。这样可以构建高效利用上下文的技能生态系统。

令牌效率

逐行审视：Claude 确实需要这段解释吗？我可以假设 Claude 已经知道吗？这值得花费这些令牌吗？

优先采用简洁的模式：

• 用代码示例代替冗长的解释
• 用决策框架代替详尽的清单
• 用一条命令及其失败信号，代替一段描述该命令的文字

删掉流程残留，而不是流程本身。 这是两件截然不同的事，而且区别可以量化。原始轨迹和仅经过少量清理的工作流记忆会因流程过载而失败——timeout_budget_exhaustion 的发生率为 10.6%，而完全不提供帮助时仅为 1.7%——因为它们保留了探索过程、死胡同和底层调试内容，以及关键步骤。提炼是技能与轨迹转储之间的全部区别；如果 SKILL.md 逐渐膨胀，重新接近轨迹，就会再次遭遇轨迹的失败模式。

因此，应该删掉的是讲述如何发现流程的内容。应该保留的是流程本身、检查项和陷阱——即使这样篇幅会变长。在这项研究中，技能每项任务实际消耗 521.5K 个令牌，而工作流记忆消耗 426.2K 个；相应地，技能带来了 4.8 个百分点的成功率提升。用于步骤和信号的篇幅是值得的投入；用于背景故事的篇幅则是浪费。

打包与交付

创建 ZIP 归档：

cd /home/claude
zip -r /mnt/user-data/outputs/skill-name.zip skill-name/

验证内容：

unzip -l /mnt/user-data/outputs/skill-name.zip

向用户展示打包后的结构：

tree skill-name/
# or
ls -lhR skill-name/

提供下载链接：

[Download skill-name.zip](computer:///mnt/user-data/outputs/skill-name.zip)

版本控制（可选）

对于正在积极开发的技能，跟踪更改：

cd /home/claude/skill-name
git init && git add . && git commit -m "Initial: skill structure"

修改后：

git add . && git commit -m "Update: description of change"

参阅 versioning-skills，了解高级模式（回滚、分支、比较）。

最佳实践

用祈使句向 Claude 下达指令，而不是在文档中描述 Claude。开篇说明技能能实现什么，将相关指令分组，并使用概括内容而非描述流程的标题。相信 Claude 的智能：明确成功标准，让它自行选择方法；只有在打包资源确实能解决实际问题时，才添加该资源。保持术语一致，并在任何不言自明的要求旁说明原因。

在至少 3 个真实场景中进行测试——简单场景、复杂场景和边缘情况——并根据实际结果迭代，而不是根据预期进行调整。

质量检查清单

向用户提供技能前：

元数据：

• 名称：小写、使用连字符、动名词形式，最多 64 个字符
• 描述：使用第三人称，包含 WHAT + WHEN 触发条件，最多 1024 个字符，不含 XML
• 描述以问题的具体事项开头，而非技术
• 描述包含用户可能输入的原样短语
• 描述通过省略内容与同类技能区分，而不是添加免责声明
• 已运行 skill_confusability.py：该技能在 5 个任务型查询中排名第一
• 没有相似度超过约 0.65 的相邻技能，除非双方都明确说明边界
• quick_validate.py 检查通过（YAML、允许的键、名称、长度、不含尖括号）
• 已更新 metadata.version（发布以版本差异为门槛；未更改 = 静默无操作）

结构：

• SKILL.md 少于 500 行（将额外内容移至 references/）
• 已删除未使用的目录
• 引用只嵌套一层（避免冗长的引用链）

内容：

• 全文使用祈使语气
• 使用肯定表述，同时保留否定的适用范围（两者并非同一规则）
• 具体说明操作方法：真实命令、真实标志、真实顺序
• 对判断保持开放：是否适用、采用哪种方法、何时放弃
• 为不明显的要求提供上下文
• 示例准确展示预期模式
• 术语一致

必需章节（仅当文档声明自身为参考资料时才可跳过）：

• 何时不应使用——用路由表列出真实的相邻技能
• 为可能有时不适用的规则提供充分理由的例外
• 何时在执行过程中放弃流程
• 以“信号 → 缓解措施”的形式编写故障模式，不要只写警告
• 如果该技能包装了工具，则说明设置步骤及其静默失败信号
• 验证：用于确认成功的命令
• 如果该技能会编辑或生成内容，则说明“看似成功但实际不佳”的情况
• 已诊断的故障需注明日期、信号和结果标签

资源：

• 脚本解决实际问题（而不是把任务推给 Claude）
• 脚本具备错误处理并提供清晰的输出
• 参考资料聚焦于具体主题
• 资源是用于生成输出的模板/文件

测试：

• 已在至少 3 个真实场景中测试
• 在预期触发条件下激活
• 可以访问打包的资源
• 已验证软件包结构

高级主题

复杂的技能模式请参阅：

• references/skill-utility-evidence.md - 必需章节背后的衡量依据
• writing-instructions 技能 - 全面的提示词原则
• crafting-instructions 技能 - 在技能、项目指令和提示词之间进行选择
• versioning-skills 技能 - 基于 Git 的开发工作流
• references/advanced-patterns.md - 验证工作流、多阶段模式
• references/optimization-techniques.md - 令牌预算管理
• references/bundled-resources.md - 详细的资源模式和示例
• references/environment-reference.md - 特定环境的模式