skill-creator-primer

Skill Creator 入门指南

注意：如果缺少 skill-creator skill，请停止并请用户安装 skill-creator@claude-plugins-official（如有需要，先通过 /plugin marketplace add anthropics/claude-plugins-official 注册市场），或克隆 https://github.com/anthropics/skills，并将其 skills 目录链接到本地 skills 目录。

根据当前任务选择入口（按照“分支增多时的路由”进行分流，而非查阅内容索引）：

• 创建新 skill → 从“从对话中捕捉意图”开始，然后继续往下。
• 编辑现有 skill → 阅读与你要修改的内容相关的章节，然后阅读“自我审查流程”。
• 审查 skill 或其 diff → 阅读“审查 skill”。
• 调整描述或触发条件 → 阅读“编写有效描述”。
• 生成展示 skill 发现的报告、页面或视觉内容 → 使用 references/html-report.md。

过程应可预测，输出无需一致

skill 会在适用时让随机系统表现得更具确定性。它让_过程_变得可预测——即 Agent 每次运行时采取相同的步骤——而非让_输出_变得一致。头脑风暴 skill 应当以可预测的方式发散：其 token 会变化，行为不会。这是理解本入门指南其余内容的视角：触发条件、结构、引导和精简都是影响过程一致性的手段；成本和可维护性则随之而来。评估任何变更时，都应看它是否能让 Agent 的行为更一致，同时考虑该 skill 的具体用途。

将每个步骤跟踪为任务

创建、更新或审查 skill 之前，请为工作的每个步骤创建一个任务（待办事项）——包括你将应用的入门指南章节，以及自我审查环节——并为每项任务写明完成标准，然后逐一完成。

• 这是本入门指南防止过早结束的措施：明确终点后，Agent 往往会完成显而易见的编辑，却跳过审查。跟踪任务能让整个流程始终清晰可见。
• 根据变更规模调整流程：重要的 skill 工作应为每个步骤设置一个任务；即使只是细微编辑，也仍需更新描述、检查触发冲突并进行自我审查，并对这些步骤进行跟踪。

Skills 的实际工作方式

**Skills 是基于提示词的上下文修饰器。**调用 skill 时，它会：

1. 将 SKILL.md 中的指令注入对话上下文
2. 通过更改工具权限并可选择切换模型来修改执行上下文
3. 通过简洁的指令引导 Agent 的行为

**Skill 的选择完全依靠大模型推理。**不存在算法匹配、关键词搜索或意图分类（可选的 paths frontmatter（一种文件 glob 筛选条件）是唯一例外）。Agent 会读取 Skill 工具提示词中的描述，并据此判断哪个 skill 符合需求。因此，description 字段是最关键的部分。

**分支决定披露哪些内容。**将 skill 的每个分支都需要的内容直接写入；只有单个分支会用到的内容，才通过上下文指针（捆绑文件）引用。决定 Agent 是否会跟进指针的是指针的_措辞_，而不是目标文件本身——必需内容若藏在措辞不够明确的指针后面，就会造成行为不一致，因此在决定内联之前，先把措辞写得更明确。如有疑问，对于这份入门指南，应将几乎可以确定会用到的材料直接写入，让 Agent 无须判断是否要读取。

**分支增多时的路由方式。**当一个 skill 分散到许多参考资料时，应将加载决策写成决策树：每个分支用一行说明条件，每个叶节点指向一份参考资料。

• 将条件表述为任务的需求，而不是目标文件的名称——Agent 会将任务与条件进行匹配来选择路径：“键值（配置、会话、缓存）-> references/kv.md”。
• 决策树保持一层深度，并确保分支互斥——每次路由都是 Agent 可能出错的一次决策。
• 参考资料数量不多时，不必使用决策树——措辞明确的普通指针比增加一层路由更省成本。
• 决策树只用于决定选哪一份；参考资料适合用表格，流程顺序适合用编号列表。

调用模式需要权衡——应慎重选择。

• 模型调用：每次请求时，描述都会出现在 Agent 的上下文中并占用其注意力；即使 skill 与任务很匹配，Agent 也可能不会调用它，因此应编写触发评估以确认它能被触发（参见“测试 Skill 触发”）。
• 用户调用（disable-model-invocation: true）：描述不会出现在任何 Agent 会话中，但用户必须记得有这个 skill，并通过斜杠命令触发它。

默认采用模型调用，以便在任务进行中发现 skill；当 skill 只是偶尔使用，且用户能稳定地找到并使用它时，改用用户调用。如果不确定哪种模式合适，就同时提供两种选项，并各用一句话说明优缺点。

---

Skills 与自定义 Agent

编写 skill 之前，先确认 skill 是否合适：

• Skill——知识、详细工作流或辅助工具，供 Agent 在当前上下文中按需加载。
• 自定义 Agent——拥有独立上下文窗口和视角的角色，最多携带轻量级工作流。对抗性分析或全新视角的工作（审查、红队测试、前提核查）适合由自定义 Agent 负责，正是因为独立上下文能避免它继承调用方的假设。
• 二者可以组合使用——Agent 可以加载 skills，因此即使某个角色需要独立上下文，共享知识仍可放在 skill 中。

相关 Skills 优先合并为一个

当请求涉及多项相关能力时，默认采用一个使用渐进式披露的 skill，而不是为每项能力分别创建一个 skill：

• 为什么一个更好——每增加一个 skill，就会多出一段始终存在于 Agent 上下文中的描述，在选择时还会与其他描述争夺注意力，并可能导致触发条件重叠。这会造成 skill 臃肿。
• 如何整合——将相关行为合并到一个 SKILL.md 中，并将每项行为的详细内容放入捆绑的 references/，供 Agent 按需加载。
• 何时拆分——仅当各 skills 的触发意图确实不同，或工具、权限需求相互冲突时才拆分。

---

从对话中捕捉意图

当用户说“把这个变成一个技能”时，先从当前对话中提取工作流，再提问。留意：

• 使用了哪些工具，以及采取步骤的顺序
• 用户在过程中做出的更正
• 观察到的输入／输出格式
• 对话中重复出现的模式

起草前，确定：

• 范围 - 询问用户，这个技能负责的是用户要求的任务，还是更高层的结果（“修复此崩溃”与“确保应用不会崩溃”）。若要对结果负责，就需要具备相应访问权限：列出 Agent 无需协助即可执行操作和验证所需的数据源、环境及映射。
• 方法 - 针对该技能的领域，回答：顶尖从业者会做哪些用户未要求的事；他们从什么最原始的材料开始；使用哪些方法和工具；除了 Agent 之外，还有什么能证明结果正确。将答案编入步骤（参见“失败模式”中的“方法优于角色”和“自我评分”）。

与用户一起补齐缺漏，然后开始创建技能。

在 primer 的 assets/skill-template.md 中起草：将其复制到新技能目录并命名为 SKILL.md，填入占位符，删除未使用的部分。

编写有效的描述

描述是技能中最重要的部分。它与其他所有技能的描述共用令牌预算，并且始终处于 Agent 的上下文中。

技能描述检查清单

针对以下每一项创建一项任务，判定通过或未通过；全部通过后即完成。每次编辑后都要重新检查整组项目——一处修改可能破坏其他项目（新增的子句可能导致字数超限）：

1. 简洁。 技能供 Agent 使用；Agent 需要清晰、高信号的触发条件，而不是冗长的文字。
2. 控制在 1-2 句内。 验证器的字数上限是上限，绝不是需要填满的目标：无论技能是否触发，每轮对话中都会计入描述的开销，因此超出上限的问题比正文中的任何问题都严重。
3. 描述仅用于让 Agent 判断是否加载技能。 不要包含激活后的指令，也不要概述技能内容或内部机制——工作流摘要会诱使 Agent 只按摘要行事，而跳过技能中的分支。
4. 确保描述具有辨识度。它不能与相邻技能混淆——名称相似、动词和对象相同，或触发情境重叠。共同激活的技能集合会因部署而异，因此辨识度应来自明确而具体的触发条件；若相邻技能可以列举，请运行下方的“检查描述触发冲突”。
5. 使用祈使表达。将描述写成给 Agent 的指令：使用此技能，当……。Agent 正在判断是否采取行动，因此要告诉它何时行动。
6. 聚焦用户意图，而非实现方式。描述用户想达成什么，而不是技能的内部机制。Agent 会根据用户的请求进行匹配。
7. 将核心词前置。描述开头的词负责触发调用，因此要把它放在前面。如果用户提示、文档和代码中也出现了同一个词，调用效果会更强。
8. 每个分支只设一个触发条件，不要堆砌同义词。技能处理的每个不同分支都给出一个触发条件；用不同说法重复指向同一个分支，只会占用上下文而不会扩大覆盖范围。删除技能正文中已经说明的身份信息。
9. 技能触发过多时，添加排除条件。指出相邻意图及其适用位置——“X 不要使用此技能，请改用 Y”——这样 Agent 不仅知道何时使用此技能，也知道何时应转而使用其他技能。

检查描述中的触发冲突

当 Agent 阅读两条描述后，无法可靠判断某个请求应该加载哪项技能时，这两项技能就存在冲突——这正是此检查唯一关注的问题；覆盖相关领域的技能没有问题。请针对可枚举的同级技能运行检查：与该技能一同安装的技能，或它将要被贡献到的代码库中的技能。

若要将新描述或修改后的描述与一组技能进行比较，请列出每项技能的目录、名称和描述：

python3 <skill-creator-primer>/scripts/list_descriptions.py <skills-root>

将共享动词或对象的技能分组（创建/编辑、图表、审查、测试），然后逐对比较，查看它们是否具有相同意图且没有区分信号——而不只是共享词语。

当触发条件中存在明确的区分信号时，这一对技能可以接受：

• 目标工具、语言或文件类型不同——Agent 会据此路由。使用相同模板的有意技能系列（go/rust/python：“处理 <language> 项目时激活”）没有问题；语言就是路由信号，因此不要将其合并。
• 同一活动的阶段或范围不同（规划与实施；单个文件与整个代码库）。
• 一项是入门技能或子技能，另一项明确提及了它。

以下情况构成冲突：

• 两项技能的触发条件可以互换：同一请求与两者的匹配程度相同。
• 一项描述是另一项的逐字子集，且没有额外的区分信息。
• 两项技能声称要对同一对象执行相同活动，且没有路由信号加以区分。

可接受——措辞几乎相同，但工具名称可以清楚地引导路由：

mermaid-diagrams：“……创建或更新 mermaid 图表。提供 mermaid 最佳实践指南。” excalidraw-diagrams：“……创建或更新 Excalidraw 图表。提供 Excalidraw 最佳实践指南。”

冲突——一项触发条件是另一项的逐字子集，且没有用于区分的“在……时使用”：

domain-model：“挑战你的计划并对照现有领域模型进行检验的讨论环节。在用户希望根据其项目的语言对计划进行压力测试时使用……” grill-with-docs：“挑战你的计划并对照现有领域模型进行检验的讨论环节……”（开头相同，没有用于区分的触发条件）

发生实际冲突时，选择最轻量的修正方式：完善其中一项描述的“在……时使用”，指出其独特之处；缩小一项技能的范围；或合并真正相同的技能。对于已经能够清楚路由的描述，即使措辞相似，也不要改动。

测试技能触发条件

技能是否激活完全取决于其 description——Agent 会阅读描述，并据此判断要加载哪些技能。若要衡量某项描述是否能在适当请求中触发，并在其他请求中保持安静——尤其是在存在过度触发或触发不足风险时——请编写触发评估：设计真实的查询，为每条查询标注该技能是否应激活，并根据实际描述进行评分。

在技能旁边的 evals/<set>.json 中放置一组评估，并使用随附的 scripts/eval_triggering.py 运行。编写或运行技能评估前，请阅读 references/trigger-evals.md。

自由度

根据任务的脆弱性和可变性调整具体程度：

高自由度（文本说明）：有多种可行方法，决策取决于上下文，启发式规则用于指导操作。

中等自由度（伪代码/参数化脚本）：存在首选模式，但允许一定变化；配置会影响行为。

低自由度（特定脚本、参数很少）：操作脆弱且容易出错，一致性至关重要，必须遵循特定顺序。

可以把 Agent 想象成在探索一条路径：狭窄且两侧是悬崖的桥需要护栏（低自由度），而开阔地带可以有多种路线（高自由度）。

技能编写技巧

选择内容

• 不要陈述显而易见的内容。 Agent 已经很懂编码，也有自己的默认判断。技能内容应聚焦于能让 Agent 跳出常规思维的信息。如果没有这项技能，Agent 也能可靠地做对，那么这部分内容就是在浪费令牌。
• 知道不等于做到。 判断是否删减的标准不是“Agent 知道这个吗？”，而是“如果不告诉它，Agent 能否每次都按顺序可靠地做到？”删掉训练数据中已有的陈述性知识（广为人知的 API、设计模式、标准语法）——这些内容通常能被可靠回忆。保留必要的工作流：Agent 可能知道每个步骤，却仍会默认采用自己的做法，或跳过顺序，除非技能明确要求它执行。约束、顺序要求、关卡和检查清单之所以值得占用令牌，是因为它们能改变 Agent 做什么，而不是教它新知识。
• 不要预先记录工具的失败情况。 列出验证器的错误代码供 Agent 规避，会让技能负责维护验证器的变更记录；而不完整的列表比没有更糟——Agent 会把遗漏的内容理解为“未检查”。应提供运行并读取结果的循环。当失败代价高到让人忍不住想预先规避时，应该改进工具：添加一种能报告尚待处理事项的模式，让 Agent 可以主动询问，而不是被动告知。
• 添加 Gotchas 部分。 任何技能中最有价值的内容，都是列出 Agent 使用该技能时常遇到的失败点的 Gotchas 部分。随着时间推移，根据实际失败不断完善。优秀的 Gotchas 部分往往比数页通用指引更有价值。

构建技能结构

• 重结构，轻行文。 将指令写成编号步骤或项目符号，每条只写一个动作，用一句简短的话表达；概念说明则保留段落。行文会掩盖 Agent 必须执行的逻辑。frontmatter、argument-hint 和 JSON-schema 描述字段也一样：用几个精准的词，不要写成段落。电报式短语（省略冠词、错误 -> 修复）适用于注意事项、检查清单和事实列表；如果短语会模糊概念、顺序或引导细节，就应避免。参见“示例”下的第二组对照。
• 将同一概念的各部分放在一起。 将一个概念的定义、规则和注意事项放在同一标题下，而不是分散各处，这样读完一部分就能一并了解相关内容。检验标准：技能读起来应像是写给 Agent 的文档。这与重复不同（同一含义在两处重复）；应避免把同一含义拆散到多处。
• 考虑子 Agent 的使用方式。 子 Agent 可以并行处理相互独立的工作，并避免大量中间结果挤占主对话。当步骤可以拆分并行处理时（逐项检查、独立研究问题、只读扫描），应标明交接内容：每个子 Agent 需要什么，以及应返回什么（摘要、结论或文件路径，而非原始数据）。建议拆分并行处理的切入点，而不是规定具体的编排方式；运行技能的模型可能比编写技能的模型更善于协调。
• 仔细考虑设置流程。 某些技能需要用户专属配置（例如 Slack 频道、数据库、API 密钥）。建议采用以下模式：首次运行时检查配置文件；如果缺失，就询问用户并保存其回答。这样可以避免将不同用户或环境的配置值硬编码进去。
• 不要在 Markdown 中添加内嵌脚本。 单条命令或简单的一行命令可以，但脚本应单独存放为文件；验证器会标记超过 10 行的围栏代码块。技能包含脚本时，应妥善编写（见下文“编写脚本”）。
• 避免过深的引用嵌套。
• 对于超过 100 行的参考文件（references/*.md），应在顶部添加简洁的目录，让 Agent 即使只读取部分内容，也能了解全文范围。

引导 Agent

• 避免把 Agent 限制得过死。 技能会在许多提示词和上下文中重复使用，因此过于僵化的指令（大量使用 MUST、规定精确步骤顺序）会在上下文变化时失效。提供 Agent 所需的信息，并留出灵活调整的空间。请参照上文的“自由度”校准指令的严格程度。
• 避免提及反而强化不想要的行为。 点名具体的不想要的行为会激活这种行为（“永远不要使用 delve”会让 Agent 想到 delve）。优先使用正向指令，说明期望的行为。如果必须禁止某种行为，请同时给出具体的替代方案，让 Agent 有明确的方向。列出具体的禁用项（例如要避免的确切短语）时，也可以同时提供替代说法。
• 用引导词来引导。 每个概念选用一个简单、预训练语料中含义明确的词，并始终重复使用（始终说“字段”，不要混用“字段”“框”“元素”）；Agent 会在推理中复用这个词，其先验也会引导行为——新造的词没有先验。当技能不遵从指令（忽略指令、跳过步骤或提前结束）、需要选择或强化引导词，或多步流程需要完成标准时，请阅读 references/steering.md——其中涵盖引导词、完成标准，以及如何防止过早结束。
• 将任务跟踪作为任何编码工作流的第一步。 将工作流的第一步写成给 Agent 的指令：为每个步骤创建一项任务（待办事项），并写明该任务的完成标准，然后逐项完成——这与本指南自身采用的防止过早结束的方法相同（见“将每个步骤跟踪为任务”）。

编写脚本

当技能包含脚本时：

• 解决问题，不要推给 Agent。 在脚本中处理错误情况，而不是让脚本失败后由 Agent 临场应对。能创建缺失文件或采用合理默认值的脚本，比直接抛出错误的脚本更可靠。
• 不要使用来历不明的常量。 在注释中说明配置值的依据。如果无法解释为什么超时设为 30 秒，Agent 也无法解释。
• 文件头注释只写一行。 脚本名称、--help 和代码本身已经说明了脚本的用途，开头再用注释块重复说明会增加每位读者的阅读负担。顶部只写一行用途说明；对于不明显的限制或所选常量，应在相关代码行旁说明原因。
• 在 --help 中说明用法，而不是写在技能里。 为脚本设置具名参数，并用 --help 解释每个参数；技能只需说明脚本名称和运行时机，其余内容由 Agent 通过阅读 --help 获取。SKILL.md 中的参数说明总会被加载，而且脚本一旦更改，这些说明就会过时。
• 明确说明是否要执行。 说明是要运行脚本（“运行 extract_fields.py 提取表单字段”），还是将其作为参考（“参阅 extract_fields.py 了解提取算法”）。通常优先执行。
• 优先使用标准库；确有需要时，再就地声明依赖项。仅使用标准库的脚本无需设置即可在任何地方运行，因此应优先选择。若脚本确实需要第三方包，请使用 uv 运行，并在脚本顶部的内联元数据中通过 PEP-723 声明依赖项，让依赖项随文件一同分发。

Token 预算指南

逐项审视：“Agent 需要这个吗？它值得占用这些 Token 吗？”

• 尽量将主 SKILL.md 控制在 4k Token 以内；详细内容移至参考文件。
• 触发分支时，参考文件会整体加载：许多由分支按需加载的小型参考文件成本很低；一个庞大的参考文件会让其分支承担全部成本——应像处理过大的 SKILL.md 一样，将其拆分或精简。
• 质量标准（信息块、删除测试、失败模式）同样适用于每个被引用的文件。
• 4k 的目标适用于按分支组织的内容：如果几乎每次激活都需要几乎所有章节，那么更大的 SKILL.md 才是合理选择；是否保留应通过删除测试判断，而非看数量（本入门指南就符合这一情况；参见“分支决定披露哪些内容”）。
• 使用捆绑的验证器进行测量（参见“验证技能”）。

示例

好的示例（简洁、可执行）：

## Extract PDF text

Use pdfplumber for text extraction:

`python scripts/extract_pdf_text.py <pdf-file>`

不好的示例（冗长、包裹在正文中）：

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

好的示例（以结构组织说明）：

1. Run the skill's evals if present.
2. On failure, tune the description and re-run.

不好的示例（相同说明埋在正文中，且包裹在正文里）：

When you begin the review you should first check whether the skill has evals,
and if it does, run them before anything else, keeping in mind that failures
may mean the description needs tuning, in which case you should revisit it
and run them again.

捆绑文件布局

统一捆绑文件的存放位置，让各项技能在整个工具包中保持一致：

• references/ - Agent 读取的 Markdown 参考资料（渐进式披露中按需加载的部分）。
• scripts/ - Agent 运行的可执行脚本。
• assets/ - Agent 复制或填写的模板，以及 SVG 和图标等非文本资源。优先从外部来源引用这些文件，而不是将其提交到项目中；捆绑二进制文件会增加体积和上下文开销，却不会给 Agent 带来好处。
• CHANGELOG.md - 技能属于非代码项目，因此使用日期标题（## YYYY-MM-DD，最新日期在前），不要使用版本号。这样可将技能的历史记录保留在正文之外（参见“固化的差异”）。更新规则应同时写入文件的 `` 注释和技能自身的 CLAUDE.md：只记录读者可见的更改，每项一行；同一天的编辑合并记录。如果有可用的变更日志设置技能，请使用它。
• 当 references/ 包含许多并列领域时，为每个领域提供相同的文件集合（例如 <domain>/patterns.md、<domain>/gotchas.md，省略内容为空的文件），这样 Agent 无需阅读索引，就能了解下一层有哪些内容。

技能中不应包含的内容

技能只应包含直接支持其功能的文件。

不要创建：

• README.md 或其他面向用户的文档、设置步骤（除非用户要求）
• 关于创建过程本身的背景信息
• 不支持技能功能执行的浮夸、填充或其他无关紧要的内容
• 主 SKILL.md 内容的目录或索引
• “何时使用”章节——正文只会在描述触发后读取，因此“是否使用”这个问题已经有了答案。将触发条件移入描述中。保留“何时不使用”和“何时用 X 替代 Y”：这些内容仍会影响后续操作
• Agent 可以轻易推断出来，或无需技能也知道去哪里获取的内容
• 丰富的文件格式（例如 zip、pptx、png、pdf 等），除非它们是模板（AI 使用文本和工具的效率最高，捆绑文件格式会增加开销和复杂性）

编写可跨 Agent 使用的技能

技能应能在任何支持标准 Agent Skills 的工具中使用。Claude Code 是我们的主要目标，但 GitHub Copilot 等工具也读取相同的格式，因此措辞和工具应保持通用，避免不经说明就仅限 Claude Code：

• 提及运行技能的对象时，请说“Agent”，不要说“Claude Code”或“Copilot”。
• 优先使用规范中的标准 frontmatter 和可移植命令；只有技能确实需要以下 Claude Code 专属扩展字段时才使用。
• 默认省略 compatibility:。只有当技能确实绑定某个工具时才添加该字段，并在 frontmatter 中声明，而不要在正文中暗中假设，例如：compatibility: claude-code、github-copilot 或 microsoft-cowork。与工具无关的技能应将此字段留空。

Claude Code Frontmatter 与扩展

以下是 Agent Skills 规范未涵盖的 Claude Code 专用字段。仅在确有需要时添加：

• argument-hint：自动补全时显示的预期参数提示，例如 [issue-number] 或 [filename] [format]。仅当技能接受参数时添加
• arguments：用于在技能正文中进行 $name 替换的具名位置参数。接受以空格分隔的字符串或 YAML 列表；名称按顺序映射到位置。仅当技能使用具名替换时添加
• model：覆盖模型。设为 "inherit"（默认值）或特定模型 ID，例如 "claude-sonnet-5"。仅当用户提出要求时添加
• effort：覆盖技能激活时的工作量级别。可选值：low、medium、high、xhigh、max。仅当用户提出要求时添加
• context：设为 "fork"，以在分叉的子 Agent 上下文中运行。适用于需要大量探索或会生成大量输出的技能。仅当用户提出要求时添加
• disable-model-invocation：设为 true，以防止 Claude 自动加载技能。用于用户应手动触发的副作用工作流。应根据上文“调用模式是一种权衡”（以及自我审查步骤 6）谨慎选择此模式，而不应只在用户提出要求时使用
• user-invocable：技能默认显示为斜杠命令。设为 false 可将其从菜单中隐藏。仅当用户提出要求时添加
• agent：设置 context: "fork" 时使用的子 Agent 类型（默认为通用型）；未设置 context: "fork" 时无效。仅当用户提出要求时添加
• paths：限制技能何时激活的 Glob 模式。仅当技能限定用于特定文件或目录时添加
• hooks：限定于此技能生命周期的钩子。仅当技能激活期间需要钩子时添加
• shell：用于内联 bang-backtick 命令块的 Shell（bash 或 powershell）。仅当技能使用此类命令块时添加
• allowed-tools：以空格分隔的预先批准工具。尽可能限定范围，例如 "Read Write Bash(uv run scripts/*.py *) Grep WebFetch(domain:code.claude.com)"（不要使用已弃用的 : 语法，例如 Bash(command:*)，改用 Bash(command *)）
• disallowed-tools：技能激活期间从可用工具池中移除的工具（在下一条用户消息时清除）。用于绝不能调用工具的自主技能，例如后台循环中的 AskUserQuestion。仅当用户提出要求时添加
• when_to_use：不要使用。

---

验证技能

使用随附的 validate_skill.py 根据官方 Agent Skills 规范进行验证。只有在调用时才会运行规范检查；Primer 处于活动状态时，PostToolUse hook 会在每次编辑技能的 SKILL.md 或引用文件后重新运行令牌报告（--report-only）：

uv run <skill-creator-primer>/scripts/validate_skill.py <skill-dir> [<skill-dir> ...]

可以一次传入多个技能：每份报告都以其路径为标题，并在末尾列出通过数。如果任何技能未通过，退出代码就会报错。

对于有效技能，除了规范检查外，它还会打印令牌预算估算和评级。它只统计 SKILL.md 实际引用的 Markdown（包括传递引用），因此未被引用的文件不会抬高数值。计数采用经 tiktoken 校准的 chars/4.12 启发式算法；添加 --tiktoken（通过 uv run --with tiktoken 运行）即可使用真正的分词器计数。

• 很好：1k-5k 个令牌

• 良好：5k-9k 个令牌

• 尚可：9k-12k 个令牌

• 较差：12k+ 个令牌

• 评级评估的是最坏情况负载（SKILL.md + 最大的单个引用文件——这是某个分支触发时负载的下限；如果分支串联多个引用文件，成本会更高），而非所有文件的总量，因此不会惩罚渐进式披露。通过退出代码强制执行——较差会失败，尚可会警告，并指出导致问题的文件。

• 如果技能的分支测试确实要求几乎所有内容都保留在行内，可以在其 frontmatter 中声明 metadata.skill-lint.max-load-tokens: <int>，并添加说明上限依据的行尾 # 注释。它限制的是最坏情况负载（SKILL.md 加最大引用文件），而非仅 SKILL.md。未超出上限的负载会通过，并注明上限且不提供整改建议；超过上限则按常规区间处理。若未声明却添加了注释，上限将无效——说明依据至关重要，因此只有在完成删除测试后才应考虑设置上限。

• 检查结果分为事实项和信号项。事实项包括描述过长、负载超出预算、SKILL.md 中的内容块（始终加载的成本），必须修复；信号项包括大型引用文件、其中的内容块或包含 10 行以上代码的代码围栏（按分支加载），应判断冗长内容是否有其必要性。引用文件中有 3 个或更多内容块时会发出警告——负载评级默认相信引用文件会保持精简。

• 内容块指任何 100 个或更多单词的文本单元，形式不限（段落、列表项、引用、表格行）：这类散文足以掩盖指令（参见“故障模式”中的“被埋没的指令”）。内容块列表会用于自我审查协议中的压缩环节。

• 密集段落指连续 3 个或更多各含 90 个或更多单词的单元（或连续 2 个或更多各含 70 个或更多单词的列表项），并非每个单元都是内容块：这是一堵让人无处喘息的文字墙。报告会标注 ? 作为提示，因为内容可能使用美式拼写：修改前请先阅读，因为每个单元都可能包含独立指令。

• 隐形字符（不换行空格、零宽空格、私用区字形，通常从网页复制而来）无论出现在哪里都属于事实项：命令或描述中出现一个就可能导致其失效，而且没有编辑器能显示它。

当用户要求技能报告、页面或发现结果的可视化时，请阅读 references/html-report.md，并运行其中说明的渲染器。其他情况下，以上文本报告已涵盖所有内容。

上游验证器的 frontmatter 允许列表可能不完整

skills-ref（以及 skill-creator 的 quick_validate.py，它会通过 python -m scripts.package_skill 控制打包——失败时会显示“Validation failed”）可能只识别 6 个核心规范属性（name、description、license、allowed-tools、metadata、compatibility），并对每个有效的 Claude Code 扩展字段（when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、disallowed-tools、model、effort、context、agent）报错。如果技能只因其中某个字段而未通过，它仍然有效。

附带的 validate_skill.py 只会针对真正违反规范的情况报错，并将未知字段降级为警告，因此已记录的扩展字段和比该检查器更新的字段都能通过。它还使用 PyYAML 而非 skills-ref 的 StrictYAML 解析 frontmatter，因此流式数组（allowed-tools: [Read, Write]）也能通过。

https://code.claude.com/docs/en/skills#frontmatter-reference 上的官方文档是权威且版本最新的字段列表。

失败模式

根据以下模式诊断过大或不可靠的技能，并采取相应的修正措施。

• 过早完成——某个步骤尚未完成就结束。修正：明确完成标准，然后隐藏后续步骤（参见 references/steering.md）。
• 重复——同一含义出现在多个位置：在 SKILL.md 内、正文与参考资料之间，或正文与脚本的 --help 或标头之间；也包括重复陈述正文引用为权威来源的内容。修正：每个步骤和参考条目只保留一个事实来源。
• 沉积——因为添加内容感觉比删除更安全，过时内容层层累积。修正：建立精简机制——重构为分支，然后删除所有分支都不需要的内容。
• 膨胀——即使每一行都仍然有用且不重复，整体也只是太长。修正：渐进式披露——按分支拆分（参见“How Skills Actually Work”中的分支判断），或拆分为单独且按顺序执行的技能。
• 工具补偿——用正文弥补工具模式的缺失；这通常是技能臃肿的根本原因。只能评判最终产物的工具，会迫使技能预先描述整个产物。能根据部分产物报告进度的工具，则只需让技能描述 Agent 提供的判断。修正：为工具添加报告模式，然后删除被它取代的正文。压缩长技能前，先检查这一点。
• 无效指令——模型默认已经会遵循的内容；即使相关，也可能是无效指令。它取决于模型——通过运行技能进行测试。修正：换用更有力的引导词，或删除（执行删除测试）。
• 人设凌驾于方法之上——使用“扮演 X 专家”之类的框架：Agent 会采用相关术语，却仍沿用默认方法。修正：将实践者使用的工具、原始输入和操作流程写成步骤（写“查询数据库并拟合模型”，而不是“扮演数据科学家”）。
• 自我评分——对于可检查的输出，技能唯一的检查方式是 Agent 自己判断，而 Agent 往往会判定自己的工作合格。修正：指定由 Agent 运行的外部评判方式（测试、验证器、渲染并检查、使用全新上下文的子 Agent），并循环检查直至通过。
• 指令埋藏——指令或逻辑藏在段落正文或过长的列表项中，也可能位于正文、description/frontmatter/schema 字段中。修正：按照（Skill Writing Tips 中的）“Structure over prose”进行转换；验证器的内容块列表可定位问题。
• 僵化的差异记录——正文讲述自身历史：工单 ID、修订说明、已被取代的机制、写给审阅者的理由。修正：只说明当前行为，让从未看过旧版本的 Agent 也能理解；来源信息应留在变更日志和 git 中。

自我审查流程

当一个技能涉及 3 个或更多参考文件时，将每个文件的只读审查分配给并行子 Agent（每个子 Agent 审查自己的文件，检查低价值文字和文件内重复内容，并返回摘要）——读取不会相互冲突。跨文件检查（例如 SKILL.md 与参考文件之间的重复内容）无法拆分；主 Agent 根据摘要进行协调。编辑工作由一个 Agent 负责，或者为每个子 Agent 分配互不重叠的文件。

创建或更新技能后，必须始终使用 primer 进行严格的自我审查。针对以下每项创建并完成任务 / TODO：

1. 检查 SKILL.md 内部、SKILL.md 与参考文件之间，以及文本与脚本之间的重复信息（脚本的 --help、文档字符串和文件头注释也需要检查）。保留一份，放在加载时机最晚的位置，并提供指向它的引用。
2. 删除低价值文字和填充内容。执行删除测试：删去这段内容；如果 Agent 的行为不会改变，那么这段内容就没有实际作用——应将其删除（见“失败模式”）。对于对比句式（“不是 X，而是 Y”），执行互换测试：如果反过来写也同样通顺，那么这种对比没有传达实质内容——直接陈述观点。
3. 精简语言——减少字数，同时突出重要信息。
4. 运行验证器（见“验证技能”）；若评级为 OK 或 Poor，先排除“工具补偿”（见“失败模式”），再进行压缩：
   • 从当前草稿中提取所有规则、步骤和注意事项，整理成检查清单。
   • 将草稿交给拥有新上下文的子 Agent（绝不能使用起草时的上下文——它会对自己的文字产生偏向），改写为原字数的约 75%（OK）或 60%（Poor），将包含指令的段落改为步骤和项目符号，删除来源说明和理由补充，并且只返回改写后的内容。若环境中有 compression-editor Agent，优先使用。
   • 只有在确认检查清单中的每一项均得以保留后，才接受改写。默认进行一轮。在变更摘要中注明 token 数量变化。
5. 确认描述简洁（篇幅短），同时足以触发技能（见“编写有效描述”检查清单）。
6. 确定调用模式：用于任务过程中发现技能时，采用模型调用；用于偶尔使用且由用户记得调用的技能，采用用户调用（disable-model-invocation: true）；如有疑问，向用户提供两种选择（见“调用模式权衡”）。
7. 确保未创建多余文件。
8. 以正向方式撰写指导，避免“粉红大象效应”（见“技能编写技巧”）。将“不要做 X”改为“做 Y”，或在禁止某行为的同时给出具体替代方案。
9. 对确定性结果使用确定性工具。如果脚本能完成任务，就让 Agent 调用该脚本，而不是依赖解读指令。
10. 如果技能包含评估用例，确保其内容为最新且运行正常。
11. 对于新建技能：完成以上步骤并通过后，分配一个拥有全新上下文的子 Agent（不是分支，见“技能与自定义 Agent”），让其启用 skill-creator-primer 和 skill-creator，并按照下文“审查技能”中的说明，以只读方式审查新技能并返回分级结果。处理所有违反规范和 primer 的问题，并逐一决定其他判断项，然后重新验证；默认进行一轮。如果没有子 Agent，请让用户在新会话中运行审查。
12. 如果步骤 4 之后的任何步骤修改了技能，请重新运行验证器；只有通过验证后，审查才算完成。

不以冗长取胜，知识质量才是关键。

审查技能

无论技能是你自己的还是别人的，审查标准都相同。评判任何差异之前，请通读整个技能（SKILL.md 和所有引用的文件）——看似干净的编辑，可能会与尚未读过的参考内容重复或矛盾。然后：

1. 先进行机械验证——参见“验证技能”（规范和令牌预算）。
2. 根据“失败模式”进行诊断；按模式报告每项发现，并给出修正方法。
3. 如果描述发生变化，请依据“技能描述检查清单”和“检查描述触发冲突”进行核查；只有在存在过度触发或触发不足疑问时，才运行技能的触发评估——它们只是调优工具，不是准入门槛。
4. 对于差异，请确认描述和参考指针在变更后仍与技能的分支相符（参见“技能的实际工作方式”）。
5. 对每项发现进行评级：规范违规、指南违规（注明章节）或判断意见。只有前两者会阻止通过。

默认修复发现的问题；如果当前属于仅审查情形，则报告评级后的发现——例如你没有写入工具（作为批判性审查子 Agent），或修复应由贡献者完成。自我审查会沿袭作者的假设——请用全新的视角或新上下文 Agent（参见“技能与自定义 Agent”）。

请牢记：少即是多。技能必须简洁！拿不准时，就用 TLDR 格式编写技能内容。