generate-skill

生成 Skill

概述

根据 agentskills.io 的 Skill 创建页面、Anthropic 的 skill-creator、平台提示指南和实证激活研究中的惯例，生成一份可直接交付的 SKILL.md（以及可选的 references/、scripts/、assets/）。第 4 阶段的校准清单针对 Claude 5 一代进行了调整；每当模型更新时，都要根据当前模型的提示指南重新检查。

一个 Skill，只做一件事。 此 Skill 的工作是编写 SKILL.md 及其 frontmatter，而不是编写文档、发布内容或辅助文件。

以下两项原则贯穿每个阶段：

• 描述就是产品。 Claude 只会通过描述判断是否调用 Skill。请像调整提示词一样打磨它。
• 补充 Agent 缺少的内容，省略 Agent 已知的内容。 对每条指令都要问：没有它，Agent 会不会做错？ 如果不会，就删掉。只编码无法推断、以流程为核心且特定于 Skill 的知识。

导航

加载	时机
references/PATTERNS.md	第 4 阶段——所选类型的正文模板
references/FRONTMATTER.md	第 3 阶段——可选字段、反模式、三级可移植性
references/EXAMPLES.md	描述和正文步骤的 ✅/❌ 示例
references/SOURCES.md	用户质疑某条规则，需要引用规范时

工作流

使用 AskUserQuestion，每次只问一个问题——绝不要一次性抛出整套问题。每个阶段结束后，展示产物并确认，再继续下一阶段。

第 1 阶段——探索需求

1. 用途。 用一句话说明此 Skill 要完成什么任务。
2. 类型，决定正文模板：methodology（多步骤工作流——code-review、track-session）· technical（API、格式或工具——docx、semantic-release）· auditing（评估产物——rate-skill、security-review）· reference（架构、惯例、查阅表——bigquery）· automation（脚本或外部命令——screenshot-local）。
3. 触发短语。 至少 5 个真实用户会逐字说出的短语。应使用自然的表达，例如：“create a skill”，而不是“scaffold skill artifact”。
4. 负面范围。 哪些相近用途不应被此 Skill 抢占？这将决定 Do NOT use… 子句，以及第 8 阶段评估集中的“不应触发”部分。
5. 约束级别。 建议、引导式（检查清单）或严格式（设有门控的阶段）。默认值：methodology 和 auditing 为引导式，technical/reference/automation 为建议式。

第 2 阶段——起草描述

官方建议的长度是“几句话到一小段”，硬性上限为 1024 个字符。结构如下：

<Third-person noun phrase>. Use whenever the user <wants/asks to> <trigger 1>, "<trigger 2>", or <trigger 3> — even if they don't explicitly mention <domain term>. Do NOT use this skill for <near-neighbor> — see <other-skill>.

展示草稿并测量长度（python3 scripts/measure.py <path/to/SKILL.md> 会报告描述字符数、正文行数，以及相对于上限估算的正文 token 数），然后反复修改。

• ✅ 前 50 个字符中包含有辨识度的名词
• ✅ 使用面向 Agent 的祈使性第三人称表达——主语是 Skill，而不是“I”
• ✅ 至少包含一个用户逐字说出的短语
• ✅ 针对间接请求加入覆盖说明（“即使他们没有明确提到 X”）——官方建议
• ❌ 使用第一人称（“I help you create skills”）——会降低激活率（Seleznov，n=650）
• ❌ 表述含糊（“A skill for creating skills”），或使用项目符号列表式描述——调查中没有一个顶级 Skill 使用这种格式
• ❌ 逐步升级语气强度（“CRITICAL: you MUST invoke this”）——模型会因激进措辞而过度触发；官方建议的修正方法是使用正常语气。要提高召回率，应增加字面触发词和覆盖说明，而不是提高语气强度。

阶段 3 — Frontmatter

按以下顺序输出这些字段，除非技能需要其他内容，否则不要输出任何其他内容：

---
name: <kebab-case, ≤64 chars, no "anthropic"/"claude" reserved words>
description: <string from Phase 2>
license: MIT
argument-hint: "[<short-token>]"    # top-level, not nested — and QUOTED: bare [x] is a YAML list, not a string
effort: high                        # optional Claude Code key; overrides the session level while the skill runs
metadata:
  author: <user-supplied>
  version: "1.0.0"
---

effort 按类型默认为：自动化和参考类为 low，技术类为 medium，审计和方法论类为 high，多源综合和 Agentic 编码为 xhigh。如果技能的交付物是长文件，则保持为 high——在 xhigh/max 下，模型会起草两次，一次在推理中，一次作为输出。省略该键即可继承默认值；原因说明和实时验证说明见 FRONTMATTER.md。

其他可选字段、frontmatter 反模式和三层可移植性规则：references/FRONTMATTER.md。

阶段 4 — 正文内容

完整模板见 references/PATTERNS.md——仅在生成正文时加载。本节列表是由 rate-skill Category 4 评估的共享规范；请确保两项技能保持一致。

类型	必需内容	可选内容
方法论	Overview、Workflow（分阶段，每阶段一项任务）、Examples、Gotchas	Quality Signals / Anti-Patterns
技术	Overview、Quick Start / Setup（一个最简代码块）、Quick Reference 或 API surface、Examples、Gotchas	Troubleshooting——将较长的 API surface 移至 references/API.md
审计	Overview、Workflow、Rubric（信号 → 权重 → 检查）、Output Format、高质量/低质量制品示例、Gotchas	—
参考	Overview、Navigation（何时加载表格）、Gotchas	Core Concepts——SKILL.md 作为路由文件；不要内嵌数据
自动化	Overview、Command Surface 表格、Sample Invocation、Failure Modes、Gotchas	Troubleshooting——实际脚本位于 scripts/

内容规则，适用于所有类型：

• 始终包含 ## Gotchas——原文：“许多技能中，最有价值的内容就是一份易错点清单。”将它们保留在 SKILL.md 中，绝不要放入参考文件，因为 Agent 必须在遇到相关情况之前读到它们。每次你必须纠正已部署技能中的 Agent，都要新增一条易错点。
• 除易错点外，还有五种官方指令模式：输出格式模板（Agent 对具体结构的模式匹配效果优于对格式的文字描述）、多步骤工作流的检查清单、验证循环（执行 → 验证 → 修正 → 重复）、适用于批量或破坏性操作的先规划、再验证、后执行，以及在 Agent 每次运行时都会重新编写相同逻辑的情况下使用的内置脚本。选择合适的模式即可，无需全部使用。
• 提供默认方案，而非菜单——选定一种方法，并简要提及其他方案。
• 优先提供流程，而非原则声明——教会 Agent 如何处理某一类问题，而不是针对单个实例说明应输出什么。
• 每条“不要做 X”都要配上正向指引。 官方建议：“告诉 Claude 应该做什么，而不是告诉它不要做什么。”

Agentic 校准——不要写入以下内容。 模型已经会执行这些行为，重复指示只会强化行为并浪费令牌，不会提升质量。

• 不添加通用的自我复查步骤 — 删除“再次检查答案”“回复前重新验证”“为任何非简单任务添加最后的验证步骤”。解决方法是删除，而不是改写。保留三类做法，后两类适用于长时间运行的工作：针对外部状态进行检查（运行测试套件、确认文件可解析、根据架构验证）；采用写作者—验证者模式，让具有全新上下文的 Agent 评判另一位 Agent 的输出；以及在报告进度前审查证据（“只报告有工具结果可佐证的工作”）。问题在于 Agent 反复阅读自己生成的内容，却没有外部依据可供核验。
• 绝不要指示 Agent 复述推理过程（“展示你的思考过程”“在回复中解释你的推理”）——这可能触发 reasoning_extraction 拒绝响应，并导致模型回退。应要求给出结论和证据。
• 绝不要指示 Agent 不要思考或推理——这会增加内部 XML 标签泄漏到可见输出中的情况。完全不要提及推理；改为规定输出（“聊天中只发一行，文件才是交付物”）。
• 不要抑制叙述（“把所有发现留到最终回复”“不要叙述”“不要发送中途更新”），也不要限制格式（“绝不要使用项目符号”“不要用标题”“不要加粗”）。这些内容是针对叙述和格式过度的模型编写的；模型现在表现相反，因此这类要求只会让输出变得沉默、平淡。应说明需要特定更新或格式的时机（“派发前报告范围”“比较三项或更多内容时使用表格”）。规定最终消息的形式——聊天中只发一行，文件才是交付物——没有问题。
• 如果技能会使用子 Agent，限定委派范围：指出哪些情形需要使用子 Agent，并设定上限；在一条消息中派发相互独立的 Agent；它们运行期间继续工作，而不是等待各自完成。无边界的委派会成倍增加成本；等待式委派会成倍增加总耗时。
• 如果技能会写入文件，限定交付物——输出模板需要有这样一句：“篇幅应与任务相称，不要添加填充章节、重复摘要或样板内容。”书面交付物默认会写得过长。
• 说明范围较窄的技能到何处为止——模型会自行扩大范围，添加无人要求的步骤。如果技能会生成代码，还要加上代码方面的要求：“如果发现任务未提及的既有缺陷或行为，应作为后续事项报告，而不是在此处修复。只有任务提出要求，或仓库中已有此类变更的测试时，才提交测试；测试规模应与相邻测试文件相当。临时检查不属于测试文件。”加入这句话后，未经要求的额外修改和提交的测试代码都会大幅减少，任务成功率则不受影响。
• 不要重复描述运行环境已注入的内容——每个 Claude Code 会话都已包含自主工作说明、交付范围说明、进度更新要求、避免过度规划的提示、隐藏工具输出说明、批量调用工具的提示以及可读性规则；再用另一种说法重复这些内容，会让模型不得不协调两套要求。

阶段 5 — 示例

准备 3–5 个覆盖不同情境的示例，而不是对同一情境反复改述——要让示例足够多样，避免 Agent 误以为存在未预期的规律。至少有一个 ❌ 反例。先展示 ✅；如果篇幅允许，最后以 ✅ 收尾（近因偏差）。每个示例都要有一行结论：

### Example: <one-line task>

✅ Desired

<short code or transcript>

Why it works: <one sentence>.

### Counter-example

❌ Anti-pattern

<short code or transcript>

Why it fails: <one sentence>.

质量标签使用 ✅/❌——受调查的 8 个顶级社区技能中，没有一个使用 <Good>/<Bad> XML 形式。这说的是标签，不是 XML：官方推荐用 <example>/<examples> 作为结构分隔符，完全没问题。一旦正文超过 300 行，就将这些示例移至 references/EXAMPLES.md，并用一条说明其内容的指引指向该文件；评分时会将其完整计入。

阶段 6 — 易错点

只列出此技能特有的失败模式，不要提供通用的技能编写建议。每项包含：一行症状、一行原因、一行修复方法。

阶段 7 — 渐进式披露检查

使用 scripts/measure.py 进行测量。SKILL.md 超过 300 行后提取内容；无论如何，联合上限 500 行 / 约 5,000 个词元都是硬性上限。

1. 按从大到小的顺序列出候选提取章节。
2. 提议使用 references/<TOPIC>.md 文件。规范文档中规定的名称是复数形式，但没有任何内容会验证目录名称——不要为了格式风格重命名现有的单数 reference/ 目录。
3. 提取的文件必须严格保持一层深；更深层的嵌套会在预览读取时被静默截断。
4. 在 SKILL.md 中为每个文件添加一行指引：说明何时加载以及文件包含什么。例外情况：注意事项保留在原处。

阶段 8 — 评估集（定稿前必需）

构建官方描述优化循环所使用的集合：

1. 约 20 条查询——8–10 条应触发（阶段 1 的短语及其改写和间接请求），以及 8–10 条不应触发（阶段 1 的近似项及不相关任务）。
2. 按 60/40 划分训练集 / 验证集，两部分都保持比例均衡。只随机打乱一次，之后各轮迭代都固定划分。
3. 保存为 references/EVAL.md，标明数据集划分并说明测试流程：每条查询在全新会话中运行约 3 次；触发率 = 调用该技能的运行次数占总运行次数的比例；应触发的通过标准为高于 0.5，不应触发的通过标准为低于 0.5。
4. 仅针对训练集中的失败进行迭代——绝不要查看验证集来选择措辞。之后检查验证集并选取验证得分最高的版本，因为后续迭代容易过拟合，较早的草稿也可能胜出。“通常迭代五次就够了。”
5. 定稿前，请用户在全新 Claude 会话中抽查 3–5 条查询。

注意事项（官方）：对于 Agent 单独无法处理的任务，它们也会参考技能，因此，即使技能描述得再完善，极其简单的查询也可能不会触发。不要因此反复修改描述。

若要衡量正文是否提升了输出质量，而不只是触发技能，请运行官方输出质量循环：使用和不使用该技能分别测试 2–3 个案例，并依据首次运行后编写的、要求证据的断言进行评分；删除在两种配置下都通过的任何断言。这种方法适用于方法论和审计类技能；对于小型参考技能则过于繁琐。

输出布局

<skill-name>/
├── SKILL.md                       # <300 lines, one job
├── references/                    # plural — load on demand
│   ├── PATTERNS.md                # optional: body templates by type
│   └── EVAL.md                    # train/validation eval set (Phase 8)
├── scripts/                       # optional: deterministic helpers (this skill bundles measure.py)
└── assets/                        # optional: templates copied into output

示例

方法论和技术描述的✅/❌配对示例、一个将四项缺陷反向处理的反例，以及检查外部状态与重新检查 Agent 自身工作正文步骤的示例：references/EXAMPLES.md。

常见问题

• 现象： 新技能从不自动调用。原因： 描述含糊，没有具体的触发条件。解决方法： 按“当用户想要……时使用”的形式重写，并添加 3 个以上带引号的触发短语。
• 现象： 单独使用时正常，但用户安装的技能超过 20 个后就会出问题。原因： 有辨识度的触发词出现在第 50 个字符之后，列表预算导致其被截断。解决方法： 将有辨识度的名词移到 description 开头。
• 现象： 对精确短语有效，但无法识别间接请求（例如用户为 CSV 技能说“清理这个数据文件”）。原因： 缺少覆盖范围条款。解决方法： 添加“即使用户没有明确提及 X”。
• 现象： 描述在训练集上的评分不错，但在验证集上表现退步。原因： 过拟合——每轮都针对相同查询调整措辞。解决方法： 根据验证分数进行选择，并保持数据集划分不变；较早的迭代结果可能更好。
• 现象： 加载时出现“意外的键”警告。原因： 顶层包含 version、author 或 tags。解决方法： 将它们移到 metadata 下。argument-hint 和 hooks 是 有效的 Claude Code 顶层键，应保留在原处——只有 Anthropic 的打包验证器会拒绝它们。
• 现象： 两个技能对同一个提示词都触发了。原因： 触发条件重叠，且没有排除范围。解决方法： 在不适用的技能中添加 Do NOT use this skill for X — see Y。
• 现象： SKILL.md 有 700 行，Agent 引用了错误的章节。原因： 单文件内容过多——Claude 会读取开头而漏掉结尾。解决方法： 将内容提取到 references/ 中，最多深入一层，并明确注明“在……时加载”。

集成

• rate-skill — 生成后运行，以评估结果。generate-skill 负责生成，rate-skill 负责审核；Phase 4 表格与 rate-skill 的 Category 4 表格共用同一份规范。