Skills 开发规范：4 原则、5 维度、5 层检查，告别不稳定触发

Skills 开发规范：4 原则、5 维度、5 层检查，告别不稳定触发

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 140 篇，Skills 最佳实战「2026」系列第 15 篇

大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。

我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

封面图：Skill 质量检查五大维度概览

图 1：Skill 质量检查五大维度概览

你在写 Claude Skill 的时候，可能遇到过这些情况：

• 写了个 Skill，第一次跑效果不错，换个输入就完全不对了
• description 认真写了，但 Claude 就是不主动触发它
• SKILL.md 越写越长，改了一处发现另一处又出问题
• 测试用例跑全过，实际使用还是翻车

这些问题看起来五花八门，但根源往往指向同一个方向：Skill 的质量瓶颈在设计层面，不在模型层面。

Anthropic 官方发布的 skill-creator（https://github.com/anthropics/skills/tree/main/skills/skill-creator ）本身就是一套完整的开发-测试-评估-迭代工作流。它的源码里藏着大量关于 Skill 质量管理的工程实践。结合官方文档（https://code.claude.com/docs/zh-CN/skills ）和最佳实践文档，可以把 Skill 的质量检查整理成五个维度。下面逐个拆解。

说明：本文内容基于 Claude Skills 官方文档（code.claude.com/docs/zh-CN/skills）、最佳实践文档和 skill-creator 源码（anthropics/skills）分析整理而成，源码分析基于笔者本地仓库版本。文中的配置模板和参数建议仅供参考，实际效果请以你的业务数据和环境测试结果为准。如果有实际使用经验，欢迎在评论区分享交流。

1. Skill 不是提示词，是执行规范

先说一个容易混淆的点：很多人把 Skill 当成一段加长版的 prompt，写完就觉得大功告成。但官方文档对 Skill 的定位远不止于此。

官方文档原文说得很清楚：

当你不断将相同的说明、检查清单或多步骤程序粘贴到聊天中时，或者当 CLAUDE.md 的一部分已经演变成程序而不是事实时，创建一个 skill。

注意这里的用词：程序。Skill 不是一段静态的描述文本，而是一个有输入、有处理逻辑、有预期输出的执行单元。

翻开 skill-creator 的源码，这个定位就很具体了。SKILL.md 文件定义了完整的工作流程：明确目标 → 编写草稿 → 创建测试用例 → 并行评估（with-skill vs baseline）→ 分析结果 → 迭代重写 → 扩大测试集再次验证。这和写一段提示词丢给模型，完全是两回事。

Skill 还有一个常被忽略的特性：持久性。官方文档明确指出：

Claude Code 不会在后续轮次重新读取 skill 文件，因此将应该在整个任务中应用的指导写成常设说明，而不是一次性步骤。

换句话说，Skill 的内容一旦加载，就会在整个会话中持续存在。你写的不是一次性的指令，而是一份会反复生效的常设规范。所以 Skill 的设计必须考虑长期稳定性和一致性，不能只盯着单次执行的效果。

2. Skill 的四种失败模式

在拆解检查维度之前，先看看 Skill 在实际使用中最容易怎么翻车。从 skill-creator 源码和官方文档中，可以归纳出四种典型的失败模式。

描述模糊：该触发时不触发

description 是决定 Claude 是否调用 Skill 的主要依据。官方文档说得很直白：Claude 使用它从可能超过 100 个可用 Skill 中选择正确的 Skill。

但实际写的时候，常见的坑包括：description 缺少关键触发词，导致 Claude 根本不调用；description 过于宽泛，比如写成 Helps with documents，触发率不稳定；description 超过 1,024 字符上限被截断，触发逻辑丢失。

skill-creator 的 SKILL.md 里专门有一章讲 Description Optimization，用了一套 60% 训练集 + 40% 留出测试集的优化流程，每个查询运行 3 次获取可靠触发率，最多迭代 5 次，才选出触发效果最好的描述。这说明描述设计不是拍脑袋的事。

结构不清：内容堆成一坨

官方文档建议 SKILL.md 正文控制在 500 行以内。接近这个限制时，应该拆分内容到单独的文件，在 SKILL.md 中用清晰的指引引用它们。

实际中经常遇到的问题是：SKILL.md 超过 500 行没有拆分；references 文件存在但 SKILL.md 里没有说明什么时候该读取它；超过 300 行的参考文件缺少目录索引。这些都会导致 Claude 在需要详细信息时找不到正确的来源。

缺少边界条件：没说不能做什么

官方最佳实践文档提到一个核心原则 - Principle of Lack of Surprise：

A skill's contents should not surprise the user in their intent if described.

Skill 的行为不应该让用户感到意外。要做到这一点，Skill 必须明确界定边界：什么情况做什么，什么情况不做什么。

常见的缺失包括：未处理边缘情况（空输入、错误格式）；缺少错误恢复指导；没有说明什么不该做（负面边界）。没有负面边界的 Skill，就像没有护栏的高速公路，看起来畅通无阻，实际上随时可能跑偏。

缺少验证：没有测试就没有信心

skill-creator 内置了一套完整的评估系统，核心是 evals.json 结构。每个测试用例包含 prompt（执行的任务）、expected_output（预期结果）、expectations（可验证的断言列表）。

但很多 Skill 开发者完全跳过了测试环节。更隐蔽的问题是：测试用例写了但没有区分度。skill-creator 的 Analyzer Agent 专门检查这种情况 - 某断言在有 Skill 和没 Skill 时都总是通过？说明这个断言无法区分 Skill 的价值，等于没测。

3. 五个维度的质量检查

五维质量雷达图

图 2：Claude Skill 五维质量检查雷达图

上面四种失败模式，可以归结为五个质量维度的缺失。下面逐个展开，每个维度都包含检查标准、常见问题和对输出质量的影响。

维度一：内容是否准确易懂

先看 Skill 的指令本身是否写得清楚。

常见问题：description 用第一人称写（I can help you...），导致在系统提示中显得突兀；指令里塞了太多 Claude 本来就知道的基础知识，浪费上下文窗口。

官方最佳实践给了个很直观的对比：解释 PDF 是什么、为什么用 pdfplumber、如何安装，这些内容大约消耗 150 个 token，而 Claude 其实根本不需要这些解释。直接给代码，50 个 token 就够了。

对输出质量的影响：内容不准确会导致 Claude 执行偏差，内容不简洁会挤占上下文窗口中其他信息的空间。官方文档说得很明确：上下文窗口是一种公共资源。Skill 与对话历史、系统提示、其他 Skill 元数据共享这个空间。多写的废话，就是在偷别的信息的空间。

维度二：结构是否清晰规范

再看 Skill 的文件组织是否符合 Progressive Disclosure（渐进式加载）原则。

Progressive Disclosure 是 Skill 的三级加载体系：

常见问题：把所有内容塞进 SKILL.md，不使用 references 拆分；references 文件存在但 SKILL.md 没有写明何时读取；超过 300 行的参考文件没有目录。

对输出质量的影响：结构混乱的 Skill 会导致 Claude 在执行时遗漏关键步骤，或者在上下文压缩后丢失重要信息。官方文档提到，自动压缩时会保留每个 Skill 的最近调用，但只有前 5,000 个 token，多个 Skill 共享 25,000 个 token 的组合预算。如果 SKILL.md 太长，关键信息很可能在压缩时被截断。

维度三：工程设计是否支持迭代维护

第三个维度看的是 Skill 是否具备可测试、可对比、可迭代的工程基础。

常见问题：没有 evals.json，完全靠手动测试；断言只检查文件名不检查内容，通过率虚高；没有 baseline 对比，无法判断 Skill 到底有没有价值。

对输出质量的影响：没有测试的 Skill 在修改时会引入回归问题。skill-creator 的 Grader Agent 有一条关键原则：不确定时，举证责任在通过方（When uncertain: The burden of proof to pass is on the expectation）。如果没有明确证据证明断言通过了，就按失败处理。这个标准很严格，但正是这种严格才能保证 Skill 在迭代中不会悄悄退化。

维度四：安全配置是否完善

第四个维度看 Skill 的工具权限和行为边界配置。

常见问题：allowed-tools 和 disallowed-tools 都没配，Skill 默认拥有所有工具权限；! 动态注入的 shell 命令没有审查；信任第三方仓库时没有先查看其项目 Skills（官方文档明确提示：skill 可授予自己广泛的工具访问权限）。

对输出质量的影响：安全配置缺失不一定影响单次输出质量，但会导致 Skill 在长期使用中出现不可控行为。一个没有工具限制的 Skill，可能在某些场景下执行了用户不期望的操作。官方文档的建议是：信任存储库前需查看项目 skills。

你在开发 Skill 时有没有踩过安全方面的坑？比如 Skill 自动执行了意料之外的 shell 命令？欢迎在评论区聊聊。

维度五：可维护性与复用性是否达标

最后一个维度，看的是 Skill 在长期使用中的可维护性。skill-creator 的 SKILL.md 里有四条改进原则，直接关系到这一点。

原则一：从反馈中泛化，不做过拟合的小修小补，而是尝试不同的隐喻或工作模式。

原则二：保持 prompt 精简，移除不起作用的内容。判断方法不是看最终输出，而是读执行转录 - 模型在哪个环节犹豫了、绕弯了，那些地方往往就是指令不够清晰或多余的。

原则三：解释 why，避免 ALWAYS/NEVER 全大写。官方说法是 this is a tell - 全大写是过拟合的黄牌信号。

原则四：寻找重复工作。如果多个测试用例独立写了类似的辅助脚本，说明这个脚本应该直接捆绑到 Skill 的 scripts 目录中。

常见问题：指令过拟合到特定示例，换一个输入就不工作；每次发现问题都加一条 MUST 规则，Skill 越来越臃肿；没有版本管理意识，改了之后不知道改了什么。

对输出质量的影响：可维护性差的 Skill 会随着时间推移越来越不稳定。每次修补都在增加复杂度，而不是解决根本问题。最终的结果是：改不动，删可惜，重写又来不及。

4. 稳定性问题的根源

Skill 稳定性问题因果分析图

图 3：Skill 稳定性问题因果分析

上面五个维度检查的是 Skill 的静态质量。但在实际使用中，还有一个更让人头疼的问题：稳定性。同一个 Skill，同样的输入，为什么有时好有时差？

从源码和文档分析，稳定性问题的来源主要有三个。

上下文窗口的动态变化

官方文档说得很清楚：SKILL.md 内容作为单个消息进入对话后，会在会话其余部分保持。但会话长度不固定。对话短的时候，Skill 的指令占比高，模型遵守得好；对话长了，其他内容挤进来，Skill 指令的权重就被稀释了。

自动压缩流程也影响稳定性。压缩后只保留每个 Skill 最近调用的前 5,000 个 token，多个 Skill 共享 25,000 个 token 预算。如果你的 SKILL.md 有 400 行，压缩后可能只剩下一半内容。

这就是为什么官方反复强调 SKILL.md 要控制在 500 行以内 - 不只是加载效率的问题，更是压缩后信息完整性的问题。

指令的模糊性

skill-creator 的 Writing Style 章节有一段很关键的话：

Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs.

与其用 MUST 强制，不如解释为什么重要。因为模型理解了 why 之后，可以在不同场景下做出合理的泛化判断；而只遵循 MUST 的模型，一旦遇到 MUST 没覆盖的情况就会卡住。

这就是为什么官方建议避免全大写的 ALWAYS/NEVER - 它们看起来强调力度强，实际上反而降低了 Skill 的泛化能力，导致稳定性变差。

过拟合到特定示例

SKILL.md 的改进原则第一条就是从反馈中泛化。如果每次遇到问题都是针对具体 case 打补丁，Skill 就会变成一个只对特定输入有效的怪物。

官方的说法更直接：don't do narrow surgical fixes that overfit。解决过拟合的方法是换一种工作模式或隐喻来重新表述指令，而不是加更多的条件判断。举个思路：如果模型总是跳过某个步骤，与其加一条 MUST NOT skip step 3，不如重新组织整个流程的表述方式，让步骤三的逻辑自然地嵌入整体流程中。

5. 发布前的标准检查流程

五层发布检查流程图

图 4：五层发布检查流程

把上面的分析落地，可以整理出一套分层的发布前检查流程。这套流程参考了 skill-creator 的 quick_validate.py 脚本和官方文档的综合要求。

第一层：基础验证

这是 quick_validate.py 的检查逻辑，是 Skill 能被打包的硬性门槛。package_skill.py 在打包前会自动调用 quick_validate，验证不通过直接拒绝打包：

# quick_validate.py 的核心检查项（来源：skill-creator 源码）
# 1. SKILL.md 必须存在
# 2. 必须有 YAML frontmatter（以 --- 开头）
# 3. frontmatter 必须是合法 YAML 字典
# 4. name 必须存在，kebab-case，最大 64 字符
# 5. name 不能以连字符开头/结尾或包含连续连字符
# 6. description 必须存在，不含尖括号（< 或 >），最大 1024 字符
# 7. compatibility（可选）必须是字符串，最大 500 字符
# 8. 无非法 frontmatter 属性

注意 name 的命名规范：不能包含保留词 anthropic 和 claude，推荐使用动名词形式（verb-ing），比如 processing-pdfs、analyzing-spreadsheets。避免使用 helper、utils、tools 这类没有信息量的名字。

第二层：结构质量

过了基础验证后，检查 Skill 的文件组织：

• SKILL.md 正文是否在 500 行以内
• 是否使用了 Progressive Disclosure 三级结构
• references / scripts / assets 是否被合理引用
• 超过 300 行的参考文件是否有目录

第三层：内容质量

结构没问题后，检查指令内容本身：

• description 是否包含触发关键词和何时使用的上下文
• 指令是否使用祈使句
• 是否解释了 why 而非堆砌 MUST
• 是否包含示例和输出格式定义
• 是否遵循 Lack of Surprise 原则

第四层：安全配置

确认 Skill 的工具权限配置：

• allowed-tools / disallowed-tools 是否合理配置
• disable-model-invocation 是否正确设置
• ! 动态注入的 shell 命令是否安全
• 是否包含可能让用户意外的行为

第五层：可维护性

最后一层，检查 Skill 的长期可维护性：

• 指令是否泛化而非过拟合
• 是否有 evals.json 测试用例
• 测试用例是否有区分度（不是 always pass 或 always fail）
• 重复工作是否已提取为脚本

这五层不是可选的。skill-creator 的工作流明确要求：编写草稿 → 创建测试 → 运行评估 → 分析结果 → 迭代重写 → 扩大测试集再次验证。这是一个闭环，不是一次性动作。

不同模型也需要交叉验证。官方最佳实践文档指出：对 Opus 完美有效的内容可能需要为 Haiku 提供更多细节。如果你的 Skill 需要支持多个模型层级，至少在 Haiku 和 Sonnet 上各跑一轮测试。

6. 降低维护成本的四个设计原则

最后说说怎么从设计阶段就降低 Skill 的维护成本。这四条原则直接来自 skill-creator 的 SKILL.md，每一条都对应一类具体的维护问题。

解释 why，不要堆 MUST

与其写 ALWAYS use error handling，不如写 错误处理很重要，因为它能防止一个文件的失败中断整个批处理流程。模型理解了原因，自然会在合适的场景做出正确判断。官方的说法是：全大写的 MUST 是 overfitting 的黄牌信号。

保持精简，移除无效内容

判断哪些内容不起作用？skill-creator 的方法是读执行转录，而不只是看最终输出。转录会告诉你模型在哪个环节犹豫了、绕弯了，那些部分往往就是指令不够清晰或者多余的地方。移除这些内容，Skill 反而更稳定。

从反馈中泛化

遇到问题时，不要做手术刀式的针对性修补。官方建议是尝试不同的隐喻或工作模式来重新表述指令，让模型从逻辑层面理解任务，而不是通过堆叠规则来约束行为。

提取重复工作

如果多个测试用例独立写了类似的辅助脚本，说明这个脚本应该直接捆绑到 Skill 的 scripts 目录中。这和普通软件工程中的 DRY 原则一致 - 重复代码是维护成本的根源。

总结

回到开头的问题：Skill 的质量瓶颈到底在哪？

答案很明确：在设计层面，不在模型层面。 模型已经很智能了，但再智能的模型也需要清晰的规范来约束行为。一个合格的 Skill 必须在内容准确性、结构规范性、工程可维护性、安全配置、可复用性这五个维度上同时达标。

官方的 skill-creator 给出了很好的参考实践：基础验证有 quick_validate.py 做硬性约束，测试评估有 evals.json + Grader Agent + Comparator Agent 做量化对比，迭代改进有四条设计原则做方法论指导。

说到底，写 Skill 和写代码是一样的道理。你不能写完功能就说做完了，还得有测试、有 review、有迭代。区别只在于，Skill 的测试对象是 AI 模型的行为，而不是函数的输入输出。

五个维度里你觉得哪个最难做到？是描述设计、结构拆分，还是测试评估？欢迎在评论区聊聊你的经验。

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！