create-skills

创建 Claude 技能

技能是可重复使用的指令集，能教会 Claude 如何稳定、出色地完成特定任务。技能是一个包含 SKILL.md 文件和可选辅助资源的文件夹。触发技能时，Claude 会读取 SKILL.md 并遵循其中的指令。

可以把技能看作是用精确的自然语言为 Claude 编程行为——大模型是解释器，技能则是源代码。

何时创建技能

在以下情况下创建技能：

• 任务需要在多次对话中稳定、可重复地执行
• 任务涉及 Claude 默认不会掌握的特定工具、步骤或输出格式
• 你已手动迭代过某个工作流，并希望记录有效做法
• 指令过于详细，不适合每次重复，但又重要到不能依赖运气

在以下情况下不要创建技能：

• 简单的提示词就能完成任务
• 任务只需执行一次
• Claude 已内置相关行为

工作流

1. Capture Intent → 2. Research & Interview → 3. Draft SKILL.md →
4. Test with real prompts → 5. Refine → 6. Package & deliver

---

第 1 步：明确意图

首先了解用户的需求。回答以下四个问题：

1. 技能应该让 Claude 能做什么？ 尽量具体：“创建带有公司信头、像素级精准的 Word 文档”比“制作文档”更好。

2. 何时触发？ 哪些短语、文件类型或上下文应该触发此技能？请具体说明——触发不足是最常见的失败模式。

3. 预期输出是什么？ 是文件、代码片段，还是结构化回复？请明确定义交付内容。

4. 输出能否客观验证？ 文件转换、数据提取和代码生成都可以测试。写作风格和创意作品通常无法测试。这决定了是否需要设置测试用例。

如果当前对话已经包含用户希望记录的工作流（例如“把这个做成技能”），请从对话历史中提取答案，包括使用的工具、步骤顺序、做出的修正以及观察到的输入／输出格式。针对缺失的信息提出有针对性的问题。

---

第 2 步：技能结构

每项技能都遵循以下结构：

skill-name/
├── SKILL.md              ← Required. The instruction file.
│   ├── YAML frontmatter   (name + description — always in context)
│   └── Markdown body      (instructions — loaded when skill triggers)
│
└── Optional resources/
    ├── scripts/           Executable code for deterministic tasks
    ├── references/        Docs loaded into context as needed
    └── assets/            Templates, icons, fonts used in output

不要包含：README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 或任何面向人类的文档。技能是供 AI Agent 读取的，而不是供人阅读的。

渐进式披露（三级加载）

技能分层加载信息，以便高效管理上下文：

级别	内容	加载时机	大小建议
1. 元数据	YAML frontmatter 中的 name + description	始终载入上下文	约 100 个词
2. SKILL.md 正文	完整的 Markdown 指令	技能触发时	最好少于 500 行
3. 打包资源	脚本、参考资料、素材	通过显式读取按需加载	不限

描述是最重要的部分——它是触发机制。正文是操作手册。资源则是深入的参考资料。

---

第 3 步：编写 YAML Frontmatter

name 字段

一个简短的标识符。使用小写字母，并以连字符分隔。示例：docx、pdf、frontend-design、deploy-aws。

description 字段（至关重要）

描述是主要触发机制。Claude 是否使用某项技能，几乎完全取决于描述是否与用户请求匹配。描述写得不好，技能就永远不会触发。

常见问题：触发不足。 Claude 往往会谨慎地激活技能。可以让描述稍微“积极”一些来应对这一问题——明确列出技能适用的场景，即使其中一些场景看起来显而易见。

模板：

description: >
  [What the skill does — 1 sentence].
  Use this skill when [primary triggers].
  Also use when [secondary triggers that might be missed].
  Covers [key capabilities].
  Do NOT use for [explicit exclusions to prevent false triggers].

优秀示例：

description: >
  Use this skill whenever the user wants to create, read, edit, or
  manipulate Word documents (.docx files). Triggers include: any mention
  of "Word doc", "word document", ".docx", or requests to produce
  professional documents with formatting like tables of contents,
  headings, page numbers, or letterheads. Also use when extracting or
  reorganizing content from .docx files, inserting or replacing images
  in documents, performing find-and-replace in Word files, working with
  tracked changes or comments, or converting content into a polished
  Word document. If the user asks for a "report", "memo", "letter",
  "template", or similar deliverable as a Word or .docx file, use this
  skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general
  coding tasks unrelated to document generation.

有效原因：

• 明确列出了主要触发短语
• 包含可能被忽略的次要触发场景
• 设定了排除条件，避免误触发
• 提及用户可能使用的词汇，而不只是技术术语

不佳示例：

description: Creates Word documents.

**无效原因：**过于含糊，没有触发短语，也没有排除条件。Claude 不知道何时应该激活它。

描述编写检查清单：

• 在第一句话中说明技能的作用
• 列出用户可能会说的明确触发短语
• 包含次要或不明显的触发场景
• 提及相关文件类型或扩展名
• 设定排除条件，避免误触发
• 稍微“积极”一些，以应对触发不足

---

第 4 步：编写 SKILL.md 正文

结构模式

选择符合技能用途的结构。大多数技能会结合多种模式：

模式	适用场景	示例结构
基于工作流	顺序执行的流程	概述 → 决策树 → 步骤 1 → 步骤 2……
基于任务	包含不同操作的工具集合	概述 → 快速开始 → 任务 A → 任务 B……
参考/指南	标准、规范、品牌指南	概述 → 指南 → 规范 → 用法
基于功能	具有相关功能的集成系统	概述 → 核心功能 → 功能 1 → 功能 2……

编写原则

使用祈使句。 将说明写成命令，而不是描述。

# Good
Read the input file. Extract the header row. Validate each column type.

# Bad
The skill should read the input file and then it would extract the header row...

解释原因，而不只是说明做什么。 如今的大模型很聪明。当它们理解指令背后的理由时，就能更好地举一反三，并处理指令未明确涵盖的边缘情况。

# Good
Use pandoc for text extraction because it preserves tracked changes
and handles nested formatting that raw XML parsing misses.

# Bad
ALWAYS use pandoc for text extraction. NEVER use raw XML parsing.

避免过于强硬地使用 MUST 和 NEVER。 如果你发现自己在用全大写字母写 ALWAYS 或 NEVER，就要提高警惕。试着通过解释理由来重新表述，让模型理解其重要性。过于强硬的限制会让技能变得脆弱且适用范围狭窄。

加入少样本示例。 展示良好的输入→输出是什么样的。示例是塑造行为最有力的工具之一。

## Commit message format

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

**Example 2:**
Input: Fixed crash when uploading files over 10MB
Output: fix(upload): handle large file uploads without crash

当输出结构很重要时，明确规定输出格式：

## Report structure
Use this exact template:

# [Title]
## Executive summary
[2-3 sentence overview]
## Key findings
[Bulleted list of findings with evidence]
## Recommendations
[Numbered actionable recommendations]

组织大型技能

如果 SKILL.md 即将达到 500 行，请将内容拆分到参考文件中：

my-skill/
├── SKILL.md                  (core workflow + pointers to references)
└── references/
    ├── aws-deployment.md      (read when deploying to AWS)
    ├── gcp-deployment.md      (read when deploying to GCP)
    └── troubleshooting.md     (read when errors occur)

在 SKILL.md 中说明 Claude 应在何时读取各个参考文件：

## Deployment
Read the appropriate reference file based on the target platform:
- AWS: `references/aws-deployment.md`
- GCP: `references/gcp-deployment.md`

If you encounter errors during deployment, consult `references/troubleshooting.md`.

对于超过 300 行的参考文件，请在顶部添加目录。

脚本

对确定性、重复性的操作使用脚本。脚本执行时不会加载到上下文中（从而节省令牌），但 Claude 可以在需要理解或修改逻辑时读取它们。

适合使用脚本的场景：

• 文件格式转换
• 验证和 lint 检查
• 模板搭建
• 数据提取或转换

#!/usr/bin/env python3
"""
Extract form fields from a PDF.
Usage: python scripts/extract_fields.py input.pdf
"""

资源文件

资源文件用于输出中出现的静态文件：模板、字体、图标、图片、CSS 文件。资源文件会被复制或引用，而不会被解读。

第 5 步：测试

起草技能后，创建 2-3 条真实的测试提示词——像真实用户会说的话，而不是精心设计的测试输入。

好的测试提示词：

• “能帮我把这些数据整理成一份 Word 文档吗？”（随意、模糊）
• “创建一份专业报告，包含目录和页码”（具体）
• “修复这个 .docx 文件的格式”（编辑任务）

需要验证的内容：

1. 技能是否会根据测试提示词正确触发？
2. Claude 是否会遵循 SKILL.md 中的指示？
3. 输出质量是否合格？
4. 是否能处理边界情况（缺少输入、请求有歧义）？

如果用户需要正式评估，请创建 evals/evals.json：

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "The user's actual request",
      "expected_output": "What success looks like",
      "files": [],
      "assertions": [
        "Output includes a table of contents",
        "All headings use Heading 1 style",
        "Page numbers appear in the footer"
      ]
    }
  ]
}

反馈循环

每当用户提供示例或输入时，立即运行，而不是等到拿到完整规格说明后再运行。展示输出并让用户反馈。查看 Claude 实际会做什么，是完善需求最快的方式。

---

第 6 步：常见陷阱

陷阱	修复方法
技能从不触发	让描述更加明确和“主动”——列出更多触发短语
技能在不适用的请求上触发	在描述中添加排除项（“不要用于……”）
Claude 忽略指示	添加示例，展示期望的行为——少样本示例 > 规则
输出格式不一致	提供结构准确的明确模板
SKILL.md 太长	将详细内容移到 references/ 文件中，并添加明确的指引
技能过于死板	将 MUST/NEVER 规则替换为对原因的解释
技能只适用于测试示例	根据具体反馈进行泛化——解释原则，而不只是修复方法
Claude 在无效步骤上浪费时间	阅读执行记录，删除导致时间浪费的指示

---

第 7 步：打包与交付

技能定稿后：

1. 验证结构——SKILL.md 存在且包含有效的 YAML frontmatter
2. 检查所有文件引用——脚本、参考资料和资源均已就位，路径正确
3. 复制到输出目录，方便用户访问
4. 向用户展示文件，并简要说明技能的功能和安装方法

如果有 package_skill.py 脚本，请使用它创建 .skill 归档文件：

scripts/package_skill.py <path/to/skill-folder>

---

快速参考：SKILL.md 模板

如需现成模板，请阅读此技能目录中的 templates/skill-template.md。

---

给技能作者的建议

这些原则源自对生产级技能的广泛迭代：

1. 描述至关重要。 花在描述上的时间要比你认为需要的更多。优秀的技能如果描述写得不好，就不会被发现。

2. 解释原因，而不只是规则。 “使用 pandoc，因为它能处理修订”胜过“始终使用 pandoc”。模型理解原因后，才能更好地泛化。

3. 先写草稿，再用全新的视角审视。 初稿要么过于详细（过拟合示例），要么过于模糊（在你不希望有歧义的地方留下了自行解读的空间）。以全新的视角进行修改。

4. 根据具体反馈进行泛化。 用户说“这个输出不对”时，不要只修复这个具体案例。弄清楚违反了什么原则，并将该原则写进去。

5. 保持精简。 删除没有实际作用的指示。如果技能中的某些内容让模型在无效工作上浪费时间，就删掉。

6. 技能要适用于数百万种情况。 实际操作中，你会根据少数几个示例进行迭代，但技能必须适用于许多不同的提示词。避免过拟合测试用例。

7. 不要有所保留。 Claude 能够完成非凡的工作。设定高标准并说明其重要性的技能，效果远胜于谨小慎微的技能。