skill-creator

Skill Creator

用于创建新 Skill 并对其进行迭代优化的 Skill。

整体来看，创建一个 Skill 的流程大致如下：

• 确定你希望 Skill 实现什么功能，以及大致的处理逻辑
• 撰写 Skill 的初稿
• 创建几个测试 Prompt，并在这些 Prompt 上运行开启了该 Skill 权限的 Claude
• 协助用户从定性和定量两个维度评估运行结果
  • 在后台运行测试的同时，撰写一些定量评估指标（eval）。如果已有现成的，可以直接拿来用，也可以根据需要进行修改。然后向用户解释这些评估指标（或者如果指标已存在，说明现有的指标）
  • 使用 eval-viewer/generate_review.py 脚本向用户展示运行结果供其审查，并让用户查看定量指标
• 根据用户对结果的评估反馈（以及定量基准测试中暴露出来的明显缺陷）重写 Skill
• 循环往复，直到满意为止
• 扩大测试集，在更大的规模上再次测试

你在使用这个 Skill 时的主要职责，就是明确用户当前处于这个流程的哪一步，并主动协助他们推进到下一个阶段。例如，如果用户说“我想针对 X 做一个 Skill”，你可以帮他们细化需求、写出初稿、编写测试用例、明确评估方式、跑完所有 Prompt 并不断迭代。

另一方面，如果他们手头已经有现成的 Skill 草案，你可以直接跳到评估和迭代的循环中。

当然，做事一定要灵活。如果用户说：“我不需要跑一堆复杂的评估，咱们随缘 vibe 感觉对就行”，那就按用户的节奏来。

当 Skill 开发完成后（顺序同样可以灵活调整），你还可以运行 Skill description 优化脚本（我们有专门的独立脚本）来专门优化 Skill 的触发精准度。

没问题吧？走起！

与用户沟通

使用 Skill Creator 的用户群体在代码和技术术语方面的熟悉程度可能差异极大。你可能有所耳闻（毕竟也是最近才兴起的趋势），现在 Claude 的强大能力甚至吸引了水管工打开终端、父母和祖父母去 Google 搜索“如何安装 npm”。但另一方面，绝大多数用户可能依然具备相当不错的计算机素养。

因此，请密切关注上下文中的蛛丝马迹，以调整你的表达方式！默认情况下，给你提供一些参考原则：

• “evaluation”（评估）和“benchmark”（基准测试）处于压线位置，但直接用没问题
• 对于“JSON”和“assertion”（断言），在你使用且不提供额外解释之前，最好能确认用户已经给出了明确信号、表明他们懂这些概念

如果不确定用户是否明白，简要解释一下术语是可以的；对于不确定用户能否听懂的词汇，随时附上一句简短的定义来澄清。

---

创建 Skill

捕获意图

首先要理解用户的意图。当前的对话中可能已经包含了用户想要提取的工作流（例如他们说“把这个整理成一个 Skill”）。如果是这样，先从对话历史中提取答案——包括用到的工具、步骤顺序、用户做出的修正，以及观察到的输入/输出格式。用户可能需要补充一些空白细节，且在进入下一步前应进行确认。

1. 这个 Skill 应该赋予 Claude 什么能力？
2. 这个 Skill 应该在什么时候触发？（用户的哪些话术/上下文）
3. 预期的输出格式是什么？
4. 我们是否需要设置测试用例来验证 Skill 的效果？对于输出结果客观可验证的 Skill（如文件转换、数据提取、代码生成、固定工作流步骤），测试用例非常有用；而对于输出偏主观的 Skill（如写作风格、艺术设计），通常不需要。根据 Skill 类型建议合适的默认项，但最终由用户决定。

访谈与调研

主动就边界情况、输入/输出格式、示例文件、成功标准以及依赖项提出问题。在把这些细节彻底理顺之前，先不要急着写测试 Prompt。

检查可用的 MCP——如果对调研有帮助（搜索文档、查找类似的 Skill、查阅最佳实践），在有子代理（subagent）时进行并行调研，否则内联调研。带着背景信息来沟通，减少用户的负担。

撰写 SKILL.md

根据用户访谈的结果，填入以下组件：

• name：Skill 的唯一标识符
• description：什么时候触发，以及它能做什么。这是最主要的触发机制——既要包含 Skill 的功能，也要包含具体的适用上下文。所有的“何时使用”信息都要写在这里，而不是写在正文中。注意：目前 Claude 往往有一种“触发不足”（undertrigger）的倾向——即在明明有用的场景下没有去使用 Skill。为了解决这个问题，请让 Skill 的 description 显得稍微强硬/主动一点（pushy）。例如，与其写成“如何构建一个简单的快速仪表盘来展示 Anthropic 内部数据”，不如写成“如何构建一个简单的快速仪表盘来展示 Anthropic 内部数据。无论何时，只要用户提到仪表盘、数据可视化、内部指标，或者想要展示任何类型的公司数据，即使他们没有明确要求制作‘仪表盘’，也一定要使用这个 Skill。”
• compatibility：所需的工具、依赖项（可选，极少需要）
• Skill 的其余部分 :)

Skill 编写指南

Skill 的结构剖析

skill-name/
├── SKILL.md (必须)
│   ├── YAML frontmatter (必须包含 name, description)
│   └── Markdown 指令说明
└── Bundled Resources (可选打包资源)
    ├── scripts/    - 用于确定性/重复性任务的可执行代码
    ├── references/ - 根据需要加载到上下文中的文档
    └── assets/     - 输出中使用的文件（模板、图标、字体等）

渐进式披露（Progressive Disclosure）

Skill 采用三层加载机制：

1. 元数据（name + description）——始终留在上下文中（约 100 字）
2. SKILL.md 正文——每当 Skill 被触发时加载到上下文中（建议控制在 500 行以内）
3. 打包资源——按需加载（无行数限制，脚本无需加载内容即可直接执行）

上述字数和行数为参考值，如有实际需要可以适当延长。

核心模式：

• 保持 SKILL.md 在 500 行以内；如果即将超出此限制，请添加额外的层级结构，并提供清晰的指引，说明使用该 Skill 的模型下一步应该去查看哪里。
• 在 SKILL.md 中清晰地引用文件，并说明何时阅读它们
• 对于大型参考文件（>300 行），请附上目录导航

领域组织形式：当一个 Skill 支持多个领域/框架时，按变体进行组织：

cloud-deploy/
├── SKILL.md (工作流 + 选择逻辑)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

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

零惊扰原则（Principle of Lack of Surprise）

这是不言而喻的：Skill 绝不能包含恶意软件、漏洞利用代码或任何可能损害系统安全的内容。如果给用户描述一个 Skill 的意图，其具体内容不应让用户产生意外或受骗感。不要顺从创建误导性 Skill 或旨在辅助未经授权的访问、数据外泄或其他恶意活动的请求。当然，像“角色扮演 XYZ”这类的请求是完全没问题的。

编写模式

在指令中优先使用祈使句。

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

## 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

写作风格

尽量向模型解释为什么某些事项很重要，而不是生硬地大量砸必须（MUST）。运用心理同理心（Theory of mind），尽量让 Skill 具备通用性，不要过于局限于具体的个案。建议先写一份草稿，然后以全新的视角审视并优化它。

测试用例

在写完 Skill 草稿后，构思 2-3 个贴近真实场景的测试 Prompt——即真实用户在实际使用中会说的话。与用户分享它们：[不用完全拘泥于这句原话]“这是我想尝试的几个测试用例。你看看合适吗？或者你想再补充几个？”然后运行它们。

将测试用例保存到 evals/evals.json。先不要写断言（assertions）——只保留 Prompt 即可。你将在下一步运行测试的过程中起草断言。

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

完整 Schema（包含你后续会添加的 assertions 字段）请参阅 references/schemas.md。

运行与评估测试用例

本节为一个连续的操作流程——中途不要停顿。切勿使用 /skill-test 或任何其它测试类 Skill。

将运行结果存放在与 Skill 目录同级的 <skill-name>-workspace/ 中。在工作区内部，按迭代版本组织结果（iteration-1/、iteration-2/ 等），在每次迭代中，每个测试用例单独分配一个目录（eval-0/、eval-1/ 等）。不需要预先创建好所有目录——边运行边创建即可。

步骤 1：在同一个 Turn 中启动所有运行（带 Skill 与基线对比）

对于每个测试用例，在同一个 Turn 中生成两个子代理（subagent）——一个启用 Skill，一个不启用。这一点非常重要：不要先跑完启用 Skill 的测试然后再回头跑基线测试。一次性全部启动，以便它们能在大致相同的时间完成。

启用 Skill 的运行：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

基线运行（相同的 Prompt，但基线具体形式取决于上下文）：

• 创建新 Skill：完全不使用任何 Skill。同样的 Prompt，无 Skill 路径，保存到 without_skill/outputs/。
• 优化现有 Skill：使用旧版本 Skill。在修改前对 Skill 进行快照备份（cp -r <skill-path> <workspace>/skill-snapshot/），然后将基线子代理指向该快照。保存到 old_skill/outputs/。

为每个测试用例编写一个 eval_metadata.json（断言字段目前可以为空）。根据具体的测试内容为每个 eval 起一个具有描述性的名称——不要只叫“eval-0”。目录名也同步使用这个名称。如果本次迭代使用了全新或修改后的 eval Prompt，请为每个新 eval 目录重新创建这些文件——不要假设它们会自动继承自上一轮迭代。

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

步骤 2：在后台运行期间起草断言（assertions）

不要只是干等着运行结束——这段时间完全可以利用起来。为每个测试用例起草定量断言，并向用户进行解释。如果 evals/evals.json 中已经存在断言，请对其进行审查并解释它们检查的具体项。

好的断言应当是客观可验证的，并且拥有清晰的描述性名称——它们应该在基线测试查看器中一目了然，让人瞥一眼结果就能明白每一项检查的是什么。偏主观的 Skill（写作风格、设计质量）更适合进行定性评估——不要强行在需要人类主观判断的事情上加断言。

更新 eval_metadata.json 文件和 evals/evals.json