wwsun

构建 Claude 技能完整指南

36分钟阅读

原文: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

构建 Claude 技能完整指南

目录

  • 引言
  • 第 1 章：基础概念
  • 第 2 章：规划与设计
  • 第 3 章：测试与迭代
  • 第 4 章：分发与分享
  • 第 5 章：模式与故障排除
  • 第 6 章：资源与参考

引言

技能（Skill） 是一组指令——打包为一个简单的文件夹——教 Claude 如何处理特定任务或工作流。技能是满足特定需求定制 Claude 的最强大方式之一。无需在每次对话中反复解释你的偏好、流程和领域专业知识，技能让你教 Claude 一次，每次都能受益。

当你有可重复的工作流时，技能尤其强大：根据设计稿生成前端设计、以一致的方法进行研究、创建遵循团队风格指南的文档，或编排多步骤流程。它们与 Claude 的内置能力（如代码执行和文档创建）配合得很好。

对于构建 MCP 集成的人来说，技能增加了另一个强大的层面——帮助将原始工具访问转变为可靠、优化的流程。

本指南涵盖了构建有效技能所需的一切——从规划和结构到测试和分发。无论你是为自己、团队还是社区构建技能，你都能在全书找到实用模式和真实案例。

你将学到：

  • 技能结构的技术要求 and 最佳实践
  • 独立技能和 MCP 增强工作流的模式
  • 我们在不同用例中有效运用的模式
  • 如何测试、迭代和分发你的技能

适用人群：

  • 希望 Claude 一致遵循特定工作流的开发者
  • 希望 Claude 遵循特定工作流的深度用户
  • 希望在组织内标准化 Claude 工作方式的团队

阅读本指南的两条路径

构建独立技能？ 重点关注基础概念、规划与设计，以及类别 1-2。

增强 MCP 集成？ “技能 + MCP”部分和类别 3 适合你。

两条路径共享相同的基础技术要求，你只需选择与你的用例相关的内容。

你能从这本指南中获得什么：

读完本指南，你将能够在一个工作会话中构建一个功能性的技能。使用 skill-creator 工具，构建和测试你的第一个可用技能大约需要 15-30 分钟。

让我们开始吧。

第 1 章：基础概念

什么是技能？

一个技能是一个包含以下内容的文件夹：

  • SKILL.md（必需）：带有 YAML frontmatter 的 Markdown 指令
  • scripts/（可选）：可执行代码（Python、Bash 等）
  • references/（可选）：按需加载的文档
  • assets/（可选）：输出中使用的模板、字体、图标

核心设计原则

渐进式披露

技能使用三级系统：

  • 第一级（YAML frontmatter）： 始终加载在 Claude 的系统提示中。仅提供足够的信息让 Claude 知道每个技能应在何时使用，而无需将所有内容加载到上下文中。
  • 第二级（SKILL.md 正文）： 当 Claude 认为该技能与当前任务相关时加载。包含完整的指令和指导。
  • 第三级（链接文件）： 技能目录内捆绑的其他文件，Claude 可以按需导航和发现。

这种渐进式披露最大限度地减少 token 消耗，同时保持专业化的能力。

可组合性

Claude 可以同时加载多个技能。你的技能应该能与其他技能良好配合，不要假设它是唯一可用的能力。

可移植性

技能在 Claude.ai、Claude Code 和 API 上运行一致。创建一个技能，就能在所有平台上无需修改地工作，只要环境支持该技能所需的任何依赖。

给 MCP 构建者：技能 + 连接器

构建不涉及 MCP 的独立技能？

跳到规划与设计——你可以随时回来看这部分。

如果你已经有了一个可用的 MCP 服务器，你已经完成了最困难的部分。技能是位于其上的知识层——捕获你已经知道的工作流和最佳实践，让 Claude 能够一致地应用它们。

厨房类比

MCP 提供了专业厨房：对工具、食材和设备的访问。

技能提供了食谱：关于如何创造有价值内容的逐步说明。

它们共同使用户能够完成复杂任务，而无需自己摸索每一步。

它们如何协作：

MCP（连接性）技能（知识）
将 Claude 连接到你的服务（Notion、Asana、Linear 等）教 Claude 如何有效使用你的服务
提供实时数据访问和工具调用捕获工作流和最佳实践
Claude 能做什么Claude 应该如何做

这对你的 MCP 用户为什么重要

没有技能时：

  • 用户连接了你的 MCP 但不知道接下来该做什么
  • 支持工单问”我该怎么用你的集成做 X”
  • 每次对话从零开始
  • 因为用户每次提示不同，结果不一致
  • 用户归咎于连接器，但真正的问题是缺少工作流指导

有了技能时：

  • 预构建的工作流在需要时自动激活
  • 一致、可靠的工具使用
  • 最佳实践融入每次交互
  • 降低集成的学习曲线

第 2 章：规划与设计

从用例开始

在写任何代码之前，确定 2-3 个你的技能应该支持的具通用例。

好的用例定义：

用例：项目冲刺规划
触发条件：用户说"帮我规划这次冲刺"或"创建冲刺任务"
步骤：
  1. 通过 MCP 获取当前项目状态（来自 Linear）
  2. 分析团队速度和容量
  3. 建议任务优先级排序
  4. 在 Linear 中创建带有适当标签 and 预估的任务
结果：完全规划的冲刺，已创建相应任务

问自己：

  • 用户想要完成什么？
  • 这需要哪些多步骤工作流？
  • 需要哪些工具（内置或 MCP）？
  • 应该嵌入什么领域知识或最佳实践？

常见技能用例类别

在 Anthropic，我们观察到三种常见用例：

类别 1：文档与资产生成

用途： 创建一致、高质量的输出，包括文档、演示文稿、应用程序、设计、代码等。

真实示例： frontend-design 技能（另见 docx、pptx、xlsx 和 ppt 技能，参见 Anthropic Skills 示例集合）

“创建独特、生产级的前端界面，具有高设计质量。用于构建 Web 组件、页面、artifacts、海报或应用程序时。”

关键技术：

  • 嵌入的风格指南和品牌标准
  • 一致的输出模板结构
  • 最终确定前的质量检查清单
  • 无需外部工具——使用 Claude 的内置能力

类别 2：工作流自动化

用途： 受益于一致方法的多步骤流程，包括跨多个 MCP 服务器的协调。

真实示例： skill-creator 技能

“创建新技能的交互式指南。引导用户完成用例定义、frontmatter 生成、指令编写和验证。”

关键技术：

  • 带验证关卡的分步工作流
  • 常用结构的模板
  • 内置审查和改进建议
  • 迭代优化循环

类别 3：MCP 增强

用途： 工作流指导，增强 MCP 服务器提供的工具访问能力。

真实示例： sentry-code-review 技能（来自 Sentry）

“使用 Sentry 的错误监控数据，通过 MCP 服务器自动分析和修复 GitHub Pull Request 中检测到的 Bug。”

关键技术：

  • 按顺序协调多个 MCP 调用
  • 嵌入领域专业知识
  • 提供用户原本需要自行指定的上下文
  • 常见 MCP 问题的错误处理

定义成功标准

你如何知道你的技能是否有效？以下是一些预期目标——粗略的基准而非精确阈值。力求严谨，但接受会存在一定的主观性评估。我们正在积极开发更稳健的测量指导和工具。

量化指标：

  • 技能在 90% 的相关查询中触发
    • 如何衡量： 运行 10-20 个应触发技能的测试查询。追踪自动加载的次数 vs 需要显式调用的次数。
  • 在 X 次工具调用内完成工作流
    • 如何衡量： 比较启用和未启用技能时相同任务的差异。统计工具调用次数 and 总 token 消耗量。
  • 每次工作流零失败 API 调用
    • 如何衡量： 在测试运行期间监控 MCP 服务器日志。追踪重试率和错误码。

质量指标：

  • 用户无需提示 Claude 下一步做什么
    • 如何评估： 在测试期间，记录你需要重定向或澄清的频率。向 beta 用户征求反馈。
  • 工作流在无需用户纠正的情况下完成
    • 如何评估： 对同一请求运行 3-5 次。比较输出的结构一致性和质量。
  • 跨会话结果一致
    • 如何评估： 新用户能否在第一次尝试时以最少指导完成任务？

技术要求

文件结构

your-skill-name/
├── SKILL.md              # 必需 - 主技能文件
├── scripts/              # 可选 - 可执行代码
│   ├── process_data.py   # 示例
│   └── validate.sh       # 示例
├── references/           # 可选 - 文档
│   ├── api-guide.md      # 示例
│   └── examples/         # 示例
└── assets/               # 可选 - 模板等
    └── report-template.md # 示例

关键规则

SKILL.md 命名：

  • 必须精确命名为 SKILL.md（区分大小写）
  • 不接受任何变体（SKILL.MD、skill.md 等）

技能文件夹命名：

  • 使用 kebab-case：notion-project-setup ✅
  • 不要用空格：Notion Project Setup ❌
  • 不要用下划线：notion_project_setup ❌
  • 不要用大写：NotionProjectSetup ❌

不要有 README.md：

  • 不要在技能文件夹内包含 README.md
  • 所有文档放在 SKILL.md 或 references/ 中
  • 注意：通过 GitHub 分发时，你仍然需要仓库级别的 README 供人类用户阅读——参见分发与分享章节。

YAML Frontmatter：最重要的部分

YAML frontmatter 是 Claude 决定是否加载你的技能的依据。一定要做对。

最小必需格式

---
name: your-skill-name
description: 描述它的功能。当用户要求 [具体短语] 时使用。
---

这就是你开始所需的一切。

字段要求

name（必需）：

  • 仅限 kebab-case
  • 不能有空格或大写字母
  • 应与文件夹名称匹配

description（必需）：

  • 必须同时包含：
    • 技能的功能
    • 何时使用（触发条件）
  • 少于 1024 个字符
  • 不能有 XML 标签（< 或 >）
  • 包含用户可能说的具体任务
  • 如果相关，注明文件类型

license（可选）：

  • 技能开源时使用
  • 常见：MIT、Apache-2.0

compatibility（可选）：

  • 1-500 个字符
  • 指示环境要求：例如适用的产品、必需的系统包、网络访问需求等

metadata（可选）：

  • 任何自定义键值对
  • 建议：author、version、mcp-server
  • 示例：
metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

安全限制

Frontmatter 中禁止的内容：

  • XML 尖括号（< >）
  • 名称中包含 “claude” 或 “anthropic” 的技能（保留）

原因： Frontmatter 出现在 Claude 的系统提示中。恶意内容可能注入指令。

编写有效的技能

Description 字段

根据 Anthropic 工程博客：

“这些元数据……仅提供足够的信息，让 Claude 知道每个技能应在何时使用，而无需将所有内容加载到上下文中。”

这是渐进式披露的第一级。

结构： [功能] + [何时使用] + [关键能力]

好的 description 示例：

# 好 - 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求"设计规范"、"组件文档"或"设计到代码交接"时使用。
# 好 - 包含触发短语
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态追踪。当用户提到"sprint"、"Linear 任务"、"项目规划"或要求"创建工单"时使用。
# 好 - 清晰的价值主张
description: PayFlow 端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说"入职新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

不好的 description 示例：

# 太模糊
description: 帮助项目。
# 缺少触发器
description: 创建复杂的多页文档系统。
# 太技术化，没有用户触发条件
description: 实现具有层级关系的 Project 实体模型。

编写主要指令

在 frontmatter 之后，用 Markdown 编写实际指令。

推荐结构：

---
name: your-skill
description: [---]
---
 
# 你的技能名称
 
## 指令
 
### 第 1 步：[第一个主要步骤]
 
清晰的说明。
 
示例：
 
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
```

预期输出：[描述成功的结果]

（根据需要添加更多步骤）

示例

示例 1：[常见场景]

用户说： “设置一个新的营销活动”

操作：

  1. 通过 MCP 获取现有活动
  2. 使用提供的参数创建新活动

结果： 活动已创建，附带确认链接

（根据需要添加更多示例）

故障排除

错误： [常见错误信息]

原因： [为什么会发生]

解决方案： [如何修复]

（根据需要添加更多错误情况）


### 指令编写最佳实践

**要具体且可操作**

✅ **好的：**

运行 python scripts/validate.py --input {filename} 检查数据格式。

如果验证失败，常见问题包括：

  • 缺少必需字段（添加到 CSV 中）
  • 无效的日期格式（使用 YYYY-MM-DD）

❌ **不好的：**

在继续之前验证数据。


**包含错误处理**

```markdown
## 常见问题

### MCP 连接失败

如果你看到 "Connection refused"：
1. 验证 MCP 服务器正在运行：检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重新连接：设置 > 扩展 > [你的服务] > 重新连接

清晰地引用捆绑资源

在编写查询之前，查阅 `references/api-patterns.md` 了解：
- 速率限制指导
- 分页模式
- 错误码 and 处理方式

使用渐进式披露

保持 SKILL.md 专注于核心指令。将详细文档移到 references/ 并链接到它。（参见核心设计原则了解三级系统的工作原理。）

第 3 章：测试与迭代

技能可以根据你的需求以不同的严谨程度进行测试：

  • 在 Claude.ai 中手动测试 —— 直接运行查询并观察行为。快速迭代，无需设置。
  • 在 Claude Code 中脚本化测试 —— 自动化测试用例，实现跨变更的可重复验证。
  • 通过 Skills API 进行程序化测试 —— 构建评估套件，针对定义的测试集系统性运行。

选择与你的质量要求和技能可见性相匹配的方法。小型团队内部使用的技能与部署给数千企业用户的技能有不同的测试需求。

专业提示：先在单个任务上迭代，再扩展

我们发现最有效的技能创建者会在单个有挑战性的任务上迭代，直到 Claude 成功完成，然后将成功的方法提取为技能。这利用了 Claude 的上下文学习能力，并提供比广泛测试更快的信号。一旦有了可用的基础，再扩展到多个测试用例以提高覆盖率。

推荐的测试方法

根据早期经验，有效的技能测试通常涵盖三个领域：

1. 触发测试

目标： 确保你的技能在正确的时机加载。

测试用例：

  • ✅ 在明确任务上触发
  • ✅ 在改写请求上触发
  • ❌ 不在无关话题上触发

示例测试集：

应该触发：
- "帮我设置一个新的 ProjectHub 工作区"
- "我需要在 ProjectHub 中创建一个项目"
- "初始化 Q4 规划的 ProjectHub 项目"

不应触发：
- "旧金山的天气如何？"
- "帮我写 Python 代码"
- "创建一个电子表格"（除非 ProjectHub 技能处理表格）

2. 功能测试

目标： 验证技能产生正确的输出。

测试用例：

  • 生成有效的输出
  • API 调用成功
  • 错误处理正常工作
  • 边界情况被覆盖

示例：

测试：创建带有 5 个任务的项目

给定：项目名称 "Q4 规划"，5 个任务描述
当：技能执行工作流时
那么：
- 项目在 ProjectHub 中已创建
- 5 个具有正确属性的任务已创建
- 所有任务链接到项目
- 无 API 错误

3. 性能对比

目标： 证明技能相比基线改进了结果。

使用定义成功标准中的指标。以下是对比示例：

基线对比没有技能有技能
用户每次提供指令✅-
自动工作流执行-✅
15 轮来回消息✅-
仅 2 个澄清问题-✅
3 次失败的 API 调用需重试✅-
0 次失败的 API 调用-✅
消耗 12,000 token✅-
消耗 6,000 token-✅

使用 skill-creator 技能

skill-creator 技能——可通过 Claude.ai 插件目录或下载用于 Claude Code——可以帮助你构建 and 迭代技能。

如果你有一个 MCP 服务器并且知道你的前 2-3 个工作流，你可以在一个工作会话中构建和测试一个可用技能——通常 15-30 分钟。

创建技能：

  • 从自然语言描述生成技能
  • 生成格式正确的 SKILL.md 及 frontmatter
  • 建议触发短语和结构

审查技能：

  • 标记常见问题（模糊的 description、缺少触发器、结构问题）
  • 识别潜在的过度/不足触发风险
  • 根据技能声明的目的建议测试用例

迭代改进：

  • 在使用技能并遇到边界情况或失败后，将这些示例带回 skill-creator
  • 示例：“使用此对话中识别的问题和解决方案来改进技能如何处理 [特定边界情况]”

使用方法：

使用 skill-creator 技能帮助我构建一个用于 [你的用例] 的技能

Note

skill-creator 帮助你设计和优化技能，但不执行自动化测试套件或产生量化评估结果。

基于反馈的迭代

技能是活的文档。计划根据以下因素迭代：

问题类型信号解决方案
触发不足技能在应该加载时没有加载；用户手动启用它；支持问题增多在 description 中添加更多触发短语；在 SKILL.md 正文中扩展触发上下文
触发过度技能在无关任务上加载；用户禁用它；与其他技能冲突缩小 description 以更具体；添加负面触发条件；包含”不用于”声明
功能失败API 调用失败；输出缺少必需字段；用户纠正技能添加错误处理步骤；包含输入验证；记录常见失败模式
不一致的结果相同的输入产生不同的输出；用户报告变化；跨会话行为漂移添加更明确的步骤；删除模糊语言；添加质量检查清单
技能与其他技能冲突使 description 更具体以区分；添加负面触发条件（“不用于……“）；缩小范围到特定用例；如果是平台特定的，检查 compatibility 字段

第 4 章：分发与分享

分发选项

个人使用：

  • 放在本地技能目录中
  • 开机即用，无需分发

团队使用：

  • 通过 Git 仓库共享（GitHub、GitLab 等）
  • 使用版本控制追踪变更
  • 考虑使用 GitHub Releases 进行版本化分发

社区分发：

  • 发布到 Anthropic Skills Registry
  • 在 GitHub 上开源
  • 通过社区论坛分享

打包最佳实践

仓库结构：

your-skill-repo/
├── README.md                  # 人类可读的概述
├── LICENSE                    # 开源许可证
├── CHANGELOG.md               # 版本历史
├── SKILL.md                   # 主技能文件
├── scripts/                   # 可执行代码
├── references/                # 文档
└── assets/                    # 模板

README.md 的位置

README.md 放在仓库根目录供人类参考，但不在技能文件夹内部——这与技能文件夹不能包含 README.md 的要求不冲突。

版本管理

为技能使用语义化版本控制（SemVer）：

  • 主版本号（MAJOR）： 不兼容的 API 变更或重大行为变化
  • 次版本号（MINOR）： 向后兼容的功能添加
  • 修订号（PATCH）： 向后兼容的 bug 修复

在 frontmatter 中追踪版本：

metadata:
  version: 1.2.0

第 5 章：模式与故障排除

常见模式

模式 1：文档创建技能

创建文档、演示文稿、代码或其他工件的技能遵循一致的结构。

使用此模式的情况：

  • 输出需要遵循一致的格式
  • 必须维护质量标准
  • 支持多种输出格式

结构：

---
name: docx-creator
description: 创建格式一致的专业 Word 文档。当用户要求"创建文档"、"写报告"、"制作提案"或提及 .docx 文件时使用。
---
# 文档创建器
 
## 核心原则
 
- 始终使用 `assets/` 中提供的模板
- 遵循 `references/style-guide.md` 中的风格指南
- 最终确定前运行质量检查清单
 
## 工作流
 
1. **理解需求**
   就以下内容提出澄清问题：
   - 目的和受众
   - 必需的章节
   - 语气（正式/随意）
   - 长度限制
 
2. **选择模板**
   根据文档类型从 `assets/` 中选择：
   - `memo-template.docx`
   - `report-template.docx`
   - `proposal-template.docx`
 
3. **创建文档**
   使用 Claude 的文档创建工具及所选模板
 
4. **质量检查**
   根据 `references/quality-checklist.md` 验证：
   - [ ] 正确的标题层级
   - [ ] 格式一致
   - [ ] 无残留占位文本
   - [ ] 适合受众
 
## 示例
 
（为你的文档类型添加具体示例）

模式 2：MCP 协调技能

编排多个 MCP 工具的技能遵循此模式。

使用此模式的情况：

  • 需要依次进行多个工具调用
  • 步骤间的错误处理至关重要
  • 领域专业知识指导工具选择

结构：

---
name: incident-response
description: 跨 PagerDuty、Slack and Jira 协调事件响应。当用户提到"incident"、"outage"、"page"或"SEV-1"时使用。
---
# 事件响应技能
 
## 工作流概览
 
1. 在 PagerDuty 中确认事件
2. 在 Slack 中创建作战室
3. 在 Jira 中创建追踪工单
4. 通知利益相关者
5. 发布状态更新
 
## 详细步骤
 
### 第 1 步：确认事件
 
**何时：** 用户确认这是真实事件
**操作：** 使用事件 ID 调用 `pagerduty:incident.acknowledge`
**错误处理：** 如果确认失败，验证事件 ID 并重试一次
 
### 第 2 步：创建作战室
 
**何时：** 事件已成功确认
**操作：** 使用命名约定 `inc-[YYYY-MM-DD]-[service]` 调用 `slack:channel.create`
**必需参数：**
 
- 频道名称（自动生成）
- 私有：false
- 主题：指向 PagerDuty 事件的链接
 
### 第 3 步：创建追踪工单
 
**何时：** 作战室已创建
**操作：** 使用事件详情调用 `jira:ticket.create`
**字段映射：**
 
| PagerDuty 字段       | Jira 字段   |
| -------------------- | ----------- |
| incident.title       | summary     |
| incident.description | description |
| incident.severity    | priority    |
| incident.service     | component   |
 
## 错误恢复
 
常见失败点及响应：
 
**PagerDuty API 超时**
 
1. 等待 5 秒，重试一次
2. 如果仍然失败，继续 Slack/Jira 步骤
3. 在作战室中注明 PagerDuty 未更新
 
**Slack 频道已存在**
 
1. 使用现有频道而不是创建新的
2. 用新事件链接更新主题

模式 3：研究与分析技能

系统性研究、数据分析或调查的技能。

使用此模式的情况：

  • 方法论必须一致
  • 多个来源需要综合
  • 发现需要结构化报告

结构：

---
name: competitive-analysis
description: 以一致的方法论进行结构化竞品分析。当用户要求"竞品分析"、"市场研究"、"比较竞争对手"或"分析 [公司] vs [公司]"时使用。
---
# 竞品分析技能
 
## 研究框架
 
始终遵循这 4 步方法论：
 
1. **全景图谱** —— 识别直接和间接竞争对手；按定位分类
2. **能力分析** —— 功能对比矩阵；定价和包装；优势/劣势
3. **战略评估** —— 市场定位；差异化战略；威胁级别
4. **综合总结** —— 关键发现摘要；战略影响；建议行动
 
## 数据来源
 
按以下优先级顺序：
 
1. `references/our-methodology.md` —— 内部研究标准
2. 公开来源（公司网站、新闻稿、评论）
3. MCP 连接的数据库（如果可用）
 
## 输出格式
 
使用 `assets/analysis-template.md`，包含以下章节：
 
- 执行摘要
- 竞争对手概况（每个竞争对手一个）
- 对比矩阵
- 战略影响
- 附录（数据来源、方法论）

故障排除指南

问题解决方案
技能不触发检查 description 是否包含具体触发短语；验证 name 与文件夹名称精确匹配；确保 frontmatter 中无 XML 字符；用 description 中的精确短语测试
技能触发但产生错误输出在 SKILL.md 正文中添加更具体的指令；包含正确输出的示例；在工作流中添加验证步骤；将详细指导从 frontmatter 移到正文
MCP 调用失败验证 MCP 服务器正在运行并已连接；检查技能指令是否匹配实际工具名称；为常见失败模式添加错误处理；在指令中包含重试逻辑
跨会话结果不一致添加明确的分步工作流；删除模糊语言（“通常”、“一般”）；包含分支逻辑的决策树；在最终输出前添加质量检查清单
技能与其他技能冲突使 description 更具体以区分；添加负面触发条件（“不用于……“）；缩小范围到特定用例；如果是平台特定的，检查 compatibility 字段

高级技巧

工作流中的条件逻辑

使用明确的 if/then 结构：

## 决策点：单个 vs 批量
 
**如果** 用户提供单个项目：
 
- 执行立即工作流
- 返回结果
 
**否则如果** 用户提供 3+ 项目的列表：
 
- 与用户确认批量大小
- 每次处理 10 个
- 提供进度更新
 
**否则：**
 
- 要求用户明确范围

多技能组合

设计技能使其能协同工作：

---
name: research-writer
description: 撰写研究报告。在研究分析（research-analysis）技能完成后使用。需要结构化的研究输入。
---
# 研究报告撰写器
 
## 前置条件
 
在开始本技能之前，确保：
 
- 研究分析已完成
- 发现结果在 `references/findings.md` 中
- 关键洞察已总结在 frontmatter 中
 
## 工作流
 
1. 阅读 `references/findings.md`
2. 从 `assets/` 中选择合适的模板
3. 按照风格指南生成报告

版本管理与更新

技能应该演进。推荐方法：

  1. 在版本控制中追踪变更
  2. 在 changelog 中记录破坏性变更
  3. 在发布前测试向后兼容性
  4. 向用户传达更新

带版本的 frontmatter：

---
name: my-skill
description: ...
metadata:
  version: 2.1.0
  last-updated: 2026-01-15
  changelog: "v2.1: 添加了批量处理。v2.0: 破坏性变更 - 新的认证流程。"
---

第 6 章：资源与参考

快速参考：SKILL.md 模板

---
name: [kebab-case-name]
description: [功能描述]。当 [触发条件] 时使用。[可选：关键能力或差异化特性。]
license: [可选 - MIT、Apache-2.0 等]
compatibility: [可选 - 环境要求]
metadata: [可选键值对]
---
# [技能名称]
 
## 概述
 
简要描述目的和价值主张。
 
## 使用场景
 
此技能适用的具体场景。
 
## 工作流
 
[带明确操作的编号步骤]
 
## 示例
 
[具体的场景，包括输入和预期输出]
 
## 故障排除
 
[常见问题及解决方案]
 
## 参考
 
- `references/[file-name].md` —— 描述
- `assets/[file-name]` —— 描述

快速参考：文件结构检查清单

your-skill-name/
├── SKILL.md          ✓ 必需
├── scripts/          ✓ 可选 - 可执行代码
├── references/       ✓ 可选 - 文档
└── assets/           ✓ 可选 - 模板等

命名规则：

  • ✓ 文件夹：kebab-case，无空格/下划线/大写
  • ✓ SKILL.md：精确这个大小写，不接受变体
  • ✓ 技能文件夹内不能有 README.md

推荐工具

  • skill-creator 技能： 构建技能的交互式指南
  • Claude Code： 用于本地开发和测试
  • GitHub： 用于托管和版本控制
  • Claude Console： 用于基于 API 的技能管理

进一步阅读

  • MCP 规范： modelcontextprotocol.io
  • Skills API 文档： console.anthropic.com/docs
  • Agent Skills 开放标准： github.com/anthropics/agent-skills

社区与支持

  • Anthropic 开发者论坛： community.anthropic.com
  • GitHub Discussions： github.com/anthropics/skills
  • 技能示例： github.com/anthropics/skills/tree/main/examples

结语

构建有效的技能是一个迭代过程。从简单开始，充分测试，根据实际使用情况不断改进。最好的技能源于反复解决真实问题——捕获有效的部分，改进无效的部分。

skill-creator 技能可以加速你的第一个技能，但最深的专业知识来自于在实践中使用你的技能并随时间不断完善它们。

我们期待看到你的创造。

译者注

本文翻译自 Anthropic 官方发布的《The Complete Guide to Building Skills for Claude》PDF。翻译力求准确传达原文意思，同时保持中文表达的流畅性。如有翻译不当之处，欢迎指正。

关系图谱

最近更新

查看更多222篇笔记 →

反向链接