skill-creator

技能创建器

用于创建新技能并迭代改进技能的技能。

总体而言，创建技能的流程如下：

• 确定你希望技能实现什么，以及大致应该如何实现
• 编写技能草稿
• 创建几个测试提示词，并使用 claude-with-access-to-the-skill 运行
• 帮助用户从定性和定量两个方面评估结果
  • 在后台运行测试时，如果还没有定量评估，就先起草一些；如果已有评估，可以直接使用，也可以在认为有必要时修改。然后向用户说明这些评估（如果已有评估，则说明现有评估）
  • 使用 eval-viewer/generate_review.py 脚本展示结果，供用户查看，同时也让他们查看定量指标
• 根据用户对结果的评估反馈重写技能（如果定量基准测试发现明显缺陷，也要据此改进）
• 重复以上步骤，直到满意为止
• 扩大测试集，再进行一次更大规模的测试

使用此技能时，你的任务是判断用户目前处于这一流程的哪个阶段，然后着手帮助他们推进后续步骤。例如，用户可能会说：“我想为 X 创建一个技能。”你可以帮他们明确目标、编写草稿、撰写测试用例、确定评估方式、运行所有提示词，并反复迭代。

另一方面，用户也可能已经有了技能草稿。这种情况下，你可以直接进入评估和迭代环节。

当然，你应该始终灵活应对。如果用户说：“我不需要运行一堆评估，只要和我随意聊聊就行”，那也可以照做。

技能完成后（不过流程顺序可以灵活调整），你还可以运行技能描述优化器，以优化技能的触发效果。我们有一个单独的脚本专门用于此目的。

明白了吗？很好。

步骤完成报告

每完成一个主要步骤后，都要按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据实际验证的步骤调整检查项名称。通过用 √，失败用 ×，简要说明用 —。“Criteria”一行概述已满足的验收标准数量。“Result”一行给出总体结论。

意图收集阶段检查项： 目标已定义、触发条件已识别、输出格式已达成一致

技能编写阶段检查项： SKILL.md 已编写、README 已生成、子 Agent 已设计

测试阶段检查项： 评估已创建、运行已完成、查看器已启动

迭代阶段检查项： 已纳入反馈、基准测试已改进、描述已优化

与用户沟通

技能创建器可能会被各种编程术语熟悉程度的用户使用。你可能还没听说过（这怎么可能呢，毕竟这只是最近才出现的趋势）：Claude 的强大能力正激励着水管工打开终端，也让父母和祖父母上网搜索“如何安装 npm”。另一方面，大多数用户的计算机知识可能还算丰富。

因此，请留意上下文线索，判断该如何措辞！举个默认情况下的例子：

• “评估”和“基准测试”这两个词勉强可以直接使用
• 对于“JSON”和“断言”，除非用户有明显迹象表明他们了解这些概念，否则应先解释再使用

如果你不确定，可以简要解释术语；如果不确定用户是否理解，也可以用简短的定义加以说明。

---

修改仓库的技能必须遵守的规则

创建或更新任何会修改 git 仓库中文件的技能（代码、文档、配置、提交、发布）时，必须在该技能的 SKILL.md 中加入以下规则：

• 在靠近顶部的位置添加 “编辑前同步仓库（强制）” 部分。
• 要求在修改前拉取远程分支的最新内容：
  • branch="$(git rev-parse --abbrev-ref HEAD)"
  • git fetch origin
  • git pull --rebase origin "$branch"
• 如果工作树有未提交的更改：先暂存更改，再同步，然后恢复暂存内容。
• 如果缺少 origin 或发生冲突：停止操作并在继续前询问用户。

没有此预同步防护措施，不得发布会修改仓库的技能。

版本管理（强制）

每个技能的 YAML frontmatter 中都必须有 metadata.version 字段，并使用语义化版本号（MAJOR.MINOR.PATCH）。此版本用于追踪技能本身的演进，告知用户和工具当前运行的是哪个迭代版本。

创建新技能时，在 frontmatter 中设置 metadata.version: 1.0.0：

---
name: my-skill
description: ...
metadata:
  version: 1.0.0
---

更新或修改现有技能时，保存前务必提升版本号。从 frontmatter 中读取当前版本并递增：

• Patch（x.y.Z）：修复错误、更正拼写、进行不会改变行为的轻微措辞调整
• Minor（x.Y.0）：新增功能、添加部分内容、增加子 Agent、扩展触发短语
• Major（X.0.0）：对技能工作流进行破坏性更改、更改输出格式、重构架构

如果 frontmatter 中没有 metadata.version 字段，则添加该字段，并从 1.0.0 开始。

每次编写或编辑 SKILL.md 时都适用此规则——无论是从头创建、根据评测反馈改进、优化描述，还是进行任何其他修改。提升版本号是编辑的一部分，并非单独步骤。

YAML Frontmatter 安全性（强制）

YAML 很容易出错。未加引号且包含冒号（:）的值会导致许多解析器将该行剩余部分视为新的映射，从而悄无声息地产生错误输出或直接解析失败。真实技能曾因此出现问题——cli-builder 和 code-review 的 frontmatter 都曾损坏。

规则：如果 frontmatter 字符串值包含以下任一字符，务必加引号：:、#、{、}、[、]、,、&、*、?、|、-、<、>、=、!、%、@、`。

实际操作中，最安全的做法是默认给 frontmatter 中所有多词字符串值加引号——这样毫无成本，却能避免此类问题。

问题示例及修复方法：

# BROKEN — the : after "workflow" starts a new mapping in strict parsers
description: Follows a 5-step workflow: Analyze -> Design -> Plan -> Execute -> Summarize.

# FIXED
description: "Follows a 5-step workflow: Analyze -> Design -> Plan -> Execute -> Summarize."

# BROKEN — the : after "B+C" breaks strict parsers
architecture: subagent (Pattern B+C: Parallel Workers + Review Loop)

# FIXED
architecture: "subagent (Pattern B+C: Parallel Workers + Review Loop)"

编写或编辑任何 SKILL.md frontmatter 时，请检查每个值是否包含冒号或其他特殊字符；如果包含，请用双引号括起该值。如果值本身包含双引号，请用 \" 转义。

创建技能

捕获意图

首先了解用户的意图。当前对话中可能已经包含了用户想要捕获的工作流（例如，用户说“把这个做成一个技能”）。如果是这样，请先从对话历史中提取答案，包括使用的工具、步骤顺序、用户做出的更正，以及观察到的输入／输出格式。用户可能需要补充缺失信息，并应在进入下一步前确认。

1. 这个技能应该让 Claude 能做什么？
2. 应在什么时候触发这个技能？（用户会使用哪些短语／处于哪些情境）
3. 预期的输出格式是什么？
4. 是否应设置测试用例来验证技能是否有效？对于输出客观可验证的技能（文件转换、数据提取、代码生成、固定工作流步骤），测试用例很有帮助。对于输出较主观的技能（写作风格、艺术创作），通常不需要测试用例。请根据技能类型建议合适的默认选项，但由用户决定。
5. 这个技能是否应使用子 Agent？ 评估通过 Agent 工具将工作委派给子 Agent 是否能让技能受益。请阅读 references/subagent-patterns.md 获取完整指南，以下是主要信号：
   • 技能是否会读取大量文件或扫描大型代码库？→ Explorer 子 Agent
   • 是否可以并行处理部分工作？→ 并行工作者子 Agent
   • 技能是否需要独立的质量审核？→ 使用全新子 Agent 进行审核循环
   • 技能是否会生成需要集中推理的大型产物？→ Executor 子 Agent 如果符合其中任何一项，请将技能设计为由主 Agent 负责协调：主 Agent 处理与用户的沟通和协调，子 Agent 负责繁重工作。这样可以保持主对话上下文清晰。

访谈与调研

主动询问边界情况、输入／输出格式、示例文件、成功标准和依赖项。弄清这些内容后再编写测试提示词。

检查可用的 MCP；如果有适合调研的 MCP（例如搜索文档、查找类似技能或了解最佳实践），请使用子 Agent 并行调研（如果可用），否则直接调研。提前准备好相关信息，减轻用户的负担。

编写 SKILL.md

根据与用户的访谈，填写以下组成部分：

• name：技能标识符。必须为 1–64 个字符，且只能包含小写字母、数字和连字符，不得出现连续连字符，并且必须与父目录名称完全一致。例如，位于 skills/my-skill/SKILL.md 的技能必须设置 name: my-skill。这些规则由 scripts/quick_validate.py 强制执行，不匹配将导致验证失败。
• description：何时触发、技能的功能。这是主要的触发机制——既要说明技能的功能，也要写明具体的使用情境。所有“何时使用”信息都应放在这里，而不是正文中。description 必须为单行（不能包含换行符或换行）——这是外部工具和自动化程序正确解析技能元数据所必需的。Claude 目前往往会触发不足，即在技能有用时也跳过它，因此 description 应写得更“积极”一些。不过，积极触发也要搭配相应的负面触发条件（见下文）。
• effort（可选）：技能所需的推理力度。有效值为：low、medium、high、max。省略时默认为 high。简单查询或填充模板时使用 low，中等复杂度的多步骤任务使用 medium，需要深入推理的复杂工作流使用 high，需要穷尽分析的任务使用 max。这是可选属性——目前并非所有工具都支持。
• metadata.version：语义化版本字符串（例如 1.0.0）。请参阅上文的“版本管理”——创建时必须设置此项，每次更新时都必须递增版本。
• compatibility：所需工具、依赖项（可选，极少需要）
• 技能的其余部分 :)

编写出色的描述：积极触发 + 排除触发

描述有两个作用：吸引那些应该触发技能的查询，并排除来自相邻领域、不应该触发技能的查询。大多数技能作者都能做好第一部分（“积极触发”），却忘了第二部分。结果就会出现误触发——例如，在 Vue 项目中运行 Tailwind 技能，或在用户询问 shell 脚本时触发 Python 技能。

解决办法是加上一句“不要用于……”。 指出那些共享关键词或意图、但并不适合该技能的相邻领域。如果你的技能与市场中的其他技能相近，或只涵盖某个广泛主题中的狭窄部分，这一点尤其重要。

示例 1——只有积极触发条件（不够充分）：

使用 Tailwind CSS 创建 React 组件。

示例 1——加入排除触发条件（好得多）：

使用 Tailwind CSS 创建 React 组件。用户要求创建新的 React 组件、UI 元素或样式布局时，务必使用。不要用于 Vue、Svelte、原生 CSS 或纯 HTML 项目。

示例 2——只有积极触发条件：

为 Postgres 架构生成 SQL 迁移。

示例 2——加入排除触发条件：

为 Postgres 架构生成 SQL 迁移。用户需要修改架构、新建表或添加索引时，务必触发。不要用于 MySQL、SQLite、MongoDB 或一次性的临时查询。

将积极触发和排除触发部分写成一个连贯的句子，或前后紧接的两个句子，不要写成结构化列表。描述字段是模型在判断是否触发时读取的文字；目标是让它自然地排除相近但不适用的情况，而不显得像合同条款。

如果描述似乎缺少排除触发条款，scripts/quick_validate.py 会发出非致命警告。这只是提醒，不会阻止使用——有时技能领域确实没有相近领域，这也没问题。

技能编写指南

技能的构成

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
├── docs/ (optional — human-only, never auto-loaded)
│   └── README.md (optional — catalog-browsing docs with AI-skip notice)
├── references/ (optional — loaded into agent context when SKILL.md points to them)
│   └── *.md (optional — additional docs loaded as needed)
├── agents/ (optional — subagent prompt files)
│   ├── explorer.md   - Codebase analysis subagent
│   ├── executor.md   - Implementation subagent
│   └── reviewer.md   - Quality review subagent
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    └── assets/     - Files used in output (templates, icons, fonts)

agents/ 目录用于存放借助 Agent 工具将工作委派给子 Agent 的技能。每个文件都包含特定子 Agent 角色的完整提示词模板（其工作内容、接收内容和返回内容）。SKILL.md 会引用这些文件，例如：“阅读 agents/explorer.md 获取完整的 explorer 提示词”，这样主技能就能保持精简，而子 Agent 则能获得详细说明。有关何时以及如何使用此模式，请参阅 references/subagent-patterns.md。

渐进式披露

技能使用三级加载系统：

1. 元数据（名称 + 描述）——始终处于上下文中（约 100 个词）
2. SKILL.md 正文——技能触发时处于上下文中（保持在 500 行以内）
3. 捆绑资源——按需加载（数量不限，脚本无需加载即可执行）

关键模式：

• 将 SKILL.md 控制在 500 行以内。这是此处编写的技能必须遵守的硬性规则，而非建议——较长的 SKILL.md 文件每次调用都会浪费 token，还容易埋没重要指引。如果接近上限，请增加一层层级（将内容密集的部分移至 references/），并用一行指引替代，例如“需要 X 时，请阅读 references/foo.md。”
• 在 SKILL.md 中清晰地注明参考文件，并说明何时阅读
• 对于较大的参考文件（超过 300 行），请加入目录

领域组织：当技能支持多个领域/框架时，应按变体组织：

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude 只会读取相关的参考文件。

不令人意外原则

这不言而喻，但技能不得包含恶意软件、漏洞利用代码，或任何可能危害系统安全的内容。如果如实描述技能的意图会让用户感到意外，就不应在技能内容中包含这些内容。不要顺从创建误导性技能，或旨在协助未经授权访问、数据外泄或其他恶意活动的请求。不过，诸如“扮演某某角色”之类的内容是可以的。

编写模式

在说明中优先使用祈使句。

定义输出格式 — 可以这样写：

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

示例模式 — 加入示例很有帮助。可以按以下方式设置格式（不过，如果示例中包含“Input”和“Output”，可以稍作调整）：

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

捆绑脚本和错误消息

当技能包含 scripts/ 下的脚本时，这些脚本就成为 Agent 执行环境的一部分——Agent 会运行脚本并对其输出做出响应。这意味着，简短且没有解释的 exit 1 实际上会让 Agent 陷入死路：Agent 看到非零退出状态，却不知道出了什么问题，也不知道如何恢复。

规则：脚本退出前，必须在 stderr（或 stdout）上输出清晰易懂的错误消息。 刚运行完脚本的 Agent 应当能够自行纠正，无需用户介入。

错误示例：

if [ -z "$FIELD" ]; then
  exit 1
fi

if not frontmatter.get('name'):
    sys.exit(1)

正确示例：

if [ -z "$FIELD" ]; then
  echo "Error: missing required field 'name' in SKILL.md frontmatter." >&2
  echo "Expected format: name: my-skill-name" >&2
  exit 1
fi

if not frontmatter.get('name'):
    print(
        "Error: missing required field 'name' in SKILL.md frontmatter. "
        "Expected format: name: my-skill-name",
        file=sys.stderr,
    )
    sys.exit(1)

好的错误消息应说明三件事：出了什么问题、哪个输入导致了问题，以及如何修复。 如果修复方法涉及文件名、配置键或命令，请明确写出——Agent 会原样复制。

步骤完成报告（必需）

每项技能都必须在每个主要阶段结束后生成结构化状态报告——使用紧凑的等宽字体区块，列出带勾选标记的行并附上总结结果行，以便立即查看通过或失败情况。参照本文顶部“步骤完成报告”部分所示的格式。根据每个步骤实际验证的内容调整检查项名称（例如，代码审查技能可以使用 Correctness、Test coverage、Security、Edge cases；部署技能可以使用 Build、Tests、Lint、CI status）。

写作风格

尽量向模型解释各项内容为何重要，而不是生硬地反复强调 MUST。运用心智理论，尽量让技能具有普适性，而不是过度局限于具体示例。先写一份草稿，再以全新的视角审阅并改进。

生成 README.md

如果技能附带 README.md，请将其放在专门的 docs/ 目录中。README.md 用于人工浏览目录。它会随 .skill 包一起发布，但不会自动加载到 Agent 上下文中。 运行时加载器只会提取 frontmatter 中的 name + description（始终加载）、SKILL.md 正文（触发时加载），以及 scripts/、references/、assets/ 下的文件（仅当 SKILL.md 指示 Agent 读取这些文件时加载）。docs/ 不属于这四类目录，因此将 README 放在那里不会消耗任何运行时 token。内容应聚焦于帮助人类决定是否安装技能的信息——功能、触发条件、工作流图和用法。

这也意味着，“不要倾倒浪费 token 的面向人类的文字”这一规则适用于 SKILL.md 和 references/（它们确实会被加载），而不适用于 docs/README.md。

重要： 在每个 README.md 文件顶部添加以下警告注释，以防 AI Agent 意外读取：

请使用以下模板：

# [Skill Display Name]

> [One-line description of what the skill does]

## Highlights

- [Key capability 1]
- [Key capability 2]
- [Key capability 3]
- [Key capability 4]

## When to Use

| Say this... | Skill will... |
|---|---|
| "[trigger phrase 1]" | [What happens] |
| "[trigger phrase 2]" | [What happens] |
| "[trigger phrase 3]" | [What happens] |

## How It Works

` ` `mermaid
graph TD
    A["[First Step]"] --> B["[Second Step]"]
    B --> C["[Third Step]"]
    C --> D["[Final Step]"]
    style A fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff
` ` `

## Usage

` ` `
/[skill-name]
` ` `

## Resources

| Path | Description |
|---|---|
| `references/` | [What the references contain] |
| `scripts/` | [What the scripts do] |

## Output

[Description of what the skill produces — files, reports, etc.]

README 规则：

• 标题：使用人类可读的显示名称（例如“Code Optimizer”，而不是“code-optimizer”）
• 标语：使用引用格式（以 > 开头）写一句话
• 亮点：用 3-5 个项目符号列出主要功能
• 适用场景：使用表格列出 3-4 个触发短语及其对应操作
• 工作原理：使用 Mermaid graph TD 图展示主要工作流步骤。第一个节点为绿色（#4CAF50），最后一个节点为蓝色（#2196F3）
• 用法：使用代码块展示斜杠命令调用
• 输出：简要说明技能会生成什么
• 可选的 资源 部分：如果技能包含 scripts/、references/ 或 assets/ 目录，则使用包含 | Path | Description | 列的表格

测试用例

编写技能草稿后，设计 2–3 个真实的测试提示词，也就是实际用户可能会说的话。与用户分享：“这里有几个我想尝试的测试用例。你觉得合适吗？还是想再添加一些？”然后运行这些测试。

将测试用例保存到 evals/evals.json。暂时不要编写断言，只保存提示词。运行进行期间，你会在下一步起草断言。

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

完整的架构请参阅 references/schemas.md（包括稍后要添加的 assertions 字段）。

设计输出格式或文件写入行为时，请阅读 references/output-patterns.md。 规划多阶段工作流或迭代循环时，请阅读 references/workflows.md。 如果技能涉及大量探索、并行任务、审查循环或大规模产物生成，请阅读 references/subagent-patterns.md，以设计能让主 Agent 保持上下文整洁的子 Agent 架构。

可选：评测前的 LLM 验证

在耗费 token 进行完整评测运行之前，你可以先执行成本较低的四阶段 LLM 验证，以发现触发失败、逻辑模糊、边界情况盲点和架构臃肿等问题。请阅读 references/validation-prompts.md，其中提供了可直接复制使用的提示词，涵盖：

1. 发现验证——frontmatter 在独立情况下能否正确触发？
2. 逻辑验证——通过模拟逐步执行来发现含糊的指令
3. 边界情况测试——使用对抗性提示词发现失败状态
4. 架构优化——确保渐进式披露并控制 token 用量

这是可选步骤——在起草技能后、大幅重写后，或评测失败原因不明时，都很适合使用。

运行和评估测试用例

请阅读 references/eval-loop.md，了解完整的五步流程（启动运行、起草断言、记录耗时、评分／汇总／查看、阅读反馈）。该文件介绍了以下内容：使用技能与基线子 Agent 的模式、eval_metadata.json 格式、timing.json 的记录方式、generate_review.py 的调用方法，以及用户完成后如何读取 feedback.json。

请勿使用 /skill-test 或任何其他测试技能——本技能要求使用 references/eval-loop.md 中的流程。

改进技能

请阅读 references/iteration.md，了解改进循环。该文件介绍了根据反馈修订技能的五项原则（泛化、保持精简、解释原因、识别重复工作、考虑子 Agent），以及迭代循环本身和可选的盲测比较系统。

描述优化

SKILL.md frontmatter 中的 description 字段是决定 Claude 是否调用技能的主要机制。创建或改进技能后，请主动提出优化描述，以提高触发准确性。

请阅读 references/description-optimization.md，了解完整的四步流程：生成触发评测查询、使用 HTML 模板与用户审核、通过 run_loop.py 执行优化循环，以及应用效果最佳的描述。该文件还说明了触发机制本身，以及为何实质性查询比简单查询更适合作为评测材料。

打包并呈现（仅当 present_files 工具可用时）

检查你是否可以使用 present_files 工具。如果无法使用，请跳过此步骤。如果可以使用，请打包技能并向用户呈现 .skill 文件：

python -m scripts.package_skill <path/to/skill-folder>

打包后，告知用户生成的 .skill 文件路径，以便他们安装。

特定环境说明

如果你使用的是 Claude.ai（没有子 Agent）或 Cowork（有子 Agent，但没有浏览器），部分操作方式会有所不同。请阅读 references/environment-modes.md，了解各环境下调整后的流程。核心循环（起草 → 测试 → 审查 → 改进）在所有环境中都相同，只有执行方式有所不同。

---

参考文件

agents/ 目录包含专用子 Agent 的说明。需要启动相关子 Agent 时，请阅读这些说明。

• agents/grader.md — 如何根据输出评估断言
• agents/comparator.md — 如何对两个输出进行盲测 A/B 比较
• agents/analyzer.md — 如何分析某个版本胜出的原因

references/ 目录包含其他文档：

• references/schemas.md — evals.json、grading.json 等文件的 JSON 结构
• references/subagent-patterns.md — 何时以及如何设计使用 Agent 工具委派工作的技能
• references/workflows.md — 用于组织技能说明的工作流模式，包括子 Agent 协调模式（模式 8）。
• references/output-patterns.md — 输出格式和文件编写模式
• references/validation-prompts.md — 可选的 4 阶段大模型验证流程，用于验证技能草稿
• references/eval-loop.md — 完整的 5 步评估运行／评分／查看器流程
• references/iteration.md — 根据反馈改进技能的原则；盲测比较
• references/description-optimization.md — 4 步说明优化工作流
• references/environment-modes.md — Claude.ai 和 Cowork 专属的适配方案

---

为强调核心循环，这里再重复一遍：

• 弄清楚技能的用途
• 起草或编辑技能
• 使用 claude-with-access-to-the-skill 运行测试提示词
• 与用户一起评估输出：
  • 创建 benchmark.json 并运行 eval-viewer/generate_review.py，帮助用户审阅输出
  • 运行定量评估
• 重复以上步骤，直到你和用户都满意
• 打包最终技能并交付给用户。

如果你有 TodoList，请添加相应步骤，确保不会遗漏。如果你在 Cowork 中，请务必在 TodoList 中添加“创建 evals JSON 并运行 eval-viewer/generate_review.py，以便人工审阅测试用例”。

祝你好运！