构建 Claude 技能完全指南

重要提示：本指南面向希望为 Claude Code 创建高质量、生产级技能的技能作者。它涵盖完整的技能开发生命周期——从最初的概念设计到部署——并提供详细的最佳实践、测试策略和部署工作流。

本指南的目标读者：本指南面向希望创建可靠、文档完善的生产级技能的开发者、提示工程师和技术写作者。如果您是技能开发的新手，请从介绍开始，按顺序阅读各章节。有经验的作者可以直接跳转到特定主题。

您将学到的内容：如何设计解决实际问题的技能、如何构建最优性能的提示模板、如何全面测试技能、如何有效编写文档，以及如何自信地将技能部署到生产环境。

第一章：Claude Code 技能简介

1.1 什么是 Claude Code 技能？

Claude Code 技能（通常简称为"技能"）是可重用的提示模板，可扩展 Claude 在特定领域的能力。技能将领域知识、最佳实践和专业工作流封装成一个 cohesive（内聚的）单元，Claude 可以在处理相关任务时自动调用。

可以把技能想象成一个专业专家，Claude 在需要时可以"咨询"它。不必反复解释相同的上下文，只需创建一次技能，Claude 就会在相关情况下自动应用它。

1.2 为什么要构建技能？

技能提供几个关键优势：

一致性：技能确保 Claude 在处理相关任务时始终遵循既定的最佳实践和领域约定。这对于需要跨不同项目和团队成员获得可预测输出的团队尤其有价值。

效率：一旦创建了技能，Claude 就可以应用专业知识，而无需您重复提供上下文。这节省了时间，并减少了管理复杂需求的认知负担。

知识捕获：技能可以捕获组织知识并使其可重用。当专家创建技能时，他们的知识就对所有使用该技能的人可用。

质量保证：设计良好的技能包含内置的质量检查和最佳实践，有助于确保输出符合专业标准，无需进行大量审查。

1.3 技能类型

技能可以服务多种目的。以下是最常见的类型：

流程技能指导 Claude 如何处理任务。例如：调试工作流、代码审查流程和测试策略。这些技能定义了处理不同类型问题的"方法"。

领域技能提供特定领域的专业知识。例如：针对特定编程语言、框架或技术领域的技能。这些技能赋予 Claude 在一般训练可能不足的领域的深度知识。

集成技能将 Claude 与外部工具和服务连接起来。例如：针对特定 API、部署平台或开发工具的技能。这些技能使 Claude 能够与更广泛的开发工具生态系统进行交互。

辅助技能提供 Claude 可以调用的实用功能。例如：用于格式化输出、生成特定类型内容或执行常见转换的技能。

1.4 技能生态系统

技能不是孤立存在的——它们是更广泛生态系统的一部分，包括：

技能注册表：存储和发现技能的中央目录。注册表使查找现有技能变得容易，并了解每个技能的用途。

技能元数据：每个技能都包含描述其用途、使用方式和配置的元数据。这些元数据帮助 Claude 了解何时应用技能以及如何与之交互。

技能依赖：技能可以依赖其他技能，创建一种组合模型，使复杂能力从更简单的构建块中涌现。

版本控制：技能遵循语义化版本控制，允许作者在保持向后兼容性的同时改进技能。

第二章：技能架构与设计模式

2.1 技能的核心组件

每个技能都由几个核心组件组成：

清单文件（skill.yaml）：清单定义了技能的元数据，包括其名称、描述、版本和配置选项。清单告诉 Claude 何时技能是相关的，以及应该如何应用。

提示模板：提示模板是技能的核心——一个精心设计的提示，在技能激活时指导 Claude 的行为。模板包含动态内容的占位符，以及处理不同场景的说明。

支持文件：技能可以包含支持文件，如参考文档、输入输出示例、测试用例和配置模板。这些文件提供技能可以使用的额外上下文和资源。

测试：全面的测试确保技能在不同场景下都能正常工作。测试对于随着时间推移保持技能质量至关重要。

2.2 技能清单

技能清单（skill.yaml）是一个 YAML 文件，提供关于技能的基本元数据。以下是示例清单：

name: debugging
description: 一个用于识别和解决软件 bug 的综合调试工作流
version: 1.2.0
author: Claude Team
tags:
  - debugging
  - troubleshooting
  - workflow
categories:
  - process
configuration:
  - name: severityLevel
    type: string
    default: medium
    description: 要关注的问题严重程度
  - name: includeTests
    type: boolean
    default: true
    description: 是否包含测试文件分析
dependencies: []
examples:
  - input: 'Debug a null pointer exception in my Python application'
    expected_behavior: 'Claude should follow a systematic debugging workflow'

清单有多个用途：

1. 发现：名称、描述和标签帮助用户在搜索注册表时找到技能。
2. 配置：配置部分定义技能接受的选项，允许用户自定义行为。
3. 文档：清单本身作为文档，提供技能用途的快速参考。
4. 验证：Claude 使用清单来验证技能是否被正确使用。

2.3 设计模式

几种经过验证的设计模式有助于创建有效的技能：

模板模式：最常见的模式涉及创建一个带有占位符的提示模板。当技能被调用时，Claude 用相关上下文填充占位符。这种模式灵活，适用于大多数技能类型。

示例：

你是 {language} 专家，专门研究 {framework}。

当用户询问 {topic} 时，你应该：
1. 首先，{first_step}
2. 然后，{second_step}
3. 最后，{third_step}

始终优先考虑 {priority} 而不是 {alternative}。

工作流模式：对于指导多步骤过程的技能，工作流模式将复杂任务分解为顺序阶段。每个阶段都有明确的输入、输出和成功标准。

示例：

调试工作流：

第一阶段：问题识别
- 收集有关错误的信息
- 识别错误类型和位置
- 记录复现步骤

第二阶段：根因分析
- 检查相关代码
- 检查常见原因
- 形成关于根因的假设

第三阶段：解决方案开发
- 提出潜在解决方案
- 评估权衡
- 选择最佳方法

第四阶段：验证
- 实施解决方案
- 测试修复
- 验证问题已解决

护栏模式：护栏确保技能在安全范围内运行。此模式包含明确的检查和约束，防止不需要的行为。

示例：

在继续之前，验证：
- 用户已提供足够的上下文
- 请求在技能范围内
- 提议的操作是安全的且可逆

如果任何检查失败，说明限制并请求澄清。

示例模式：包含具体示例有助于 Claude 理解期望的行为。示例应涵盖典型情况和边界情况。

示例：

好的示例：
用户：如何在 Python 中排序列表？
回答：使用 sorted() 函数……

不好的示例：
用户：如何在 Python 中排序列表？
回答：你需要考虑算法……

2.4 技能组合

技能可以组合在一起以创建更强大的能力。这种组合模型允许您：

分层技能：顺序应用多个技能，每个技能增加一层专业化。例如，一个 "Python" 技能可能与 "testing" 技能分层，然后再与 "debugging" 技能分层。

并行技能：将多个技能应用于同一上下文，每个技能贡献不同的专业知识。例如，"security" 技能和 "performance" 技能可能同时分析相同的代码。

条件技能：根据特定条件应用技能。例如，"react" 技能可能只在用户使用 React 组件时才被应用。

有效组合技能：

1. 定义清晰的接口：技能应该有明确定义的输入和输出，其他技能可以与之配合。
2. 尽量减少冲突：避免提供矛盾指令或可能相互干扰的技能。
3. 战略性排序：考虑应用技能的顺序，以及每一层如何在前一层的基础上构建。
4. 测试组合：彻底测试技能组合，确保它们能良好协作。

第三章：技能的提示工程

3.1 有效技能提示的原则

提示模板是技能最关键的部分。精心设计的提示引导 Claude 产生高质量、一致的输出。以下是关键原则：

清晰的角色定义：首先清晰定义 Claude 的角色。这为接下来的一切设定上下文。角色应该足够具体以提供指导，但不应该太狭窄，以免限制有用的响应。

好的示例："你是一位拥有 15 年分布式系统经验的高级软件架构师。"

太模糊："你是一个有用的助手。"

太狭窄："你是一个只回答 Spring Boot 问题的 Java 开发者。"

明确的指令：明确说明 Claude 应该做什么。不要依赖隐含的假设或常识——清楚地说明期望的行为。

不要说："写好代码。"

要说："编写遵循以下原则的代码：1) 使用有意义的变量名，2) 保持函数在 30 行以内，3) 为所有公共函数添加 JSDoc 注释。"

结构化输出：当您需要特定的输出格式时，明确描述它们。使用示例、模板或模式使期望的格式清晰。

示例：

将您的响应格式化为 JSON，结构如下：
{
  "summary": "问题的一句话说描述",
  "severity": "low|medium|high|critical",
  "root_cause": "问题的根本原因",
  "recommended_fix": "建议的解决方案"
}

边界条件：明确定义技能应该和不应该做什么。这可以防止 Claude 超出预期范围或产生不需要的输出。

示例：

如果用户询问与 {domain} 无关的话题，请回应说这个问题超出您的专业范围，并提供帮助 {domain} 相关问题的选项。

3.2 提示结构

有效的技能提示通常遵循结构化格式：

# 角色定义
你是 [角色]，拥有 [专业知识]。

# 上下文
[关于任务的背景信息]

# 任务描述
当 [触发条件] 时，你应该 [期望行为]。

# 具体指南
- [指南 1]
- [指南 2]
- [指南 3]

# 示例
[示例输入和期望输出]

# 输出格式
[期望的输出结构]

# 约束
- [约束 1]
- [约束 2]

这个结构提供了一个清晰的框架，Claude 可以一致地遵循。

3.3 处理动态内容

技能通常需要包含动态内容——根据具体情况变化的信息。以下是处理动态内容的技术：

占位符：使用清晰的占位符来填充运行时内容。

示例：

在分析 {language} 代码时，你应该：
1. 检查 {common_issues}
2. 寻找 {best_practices}
3. 验证 {performance_considerations}

条件部分：仅在某些条件下激活的部分。

示例：

{if user_experience_level == "beginner"}
用简单的术语和类比解释概念。
{endif}

{if user_experience_level == "expert"}
使用技术术语，无需解释。
{endif}

迭代细化：对于复杂任务，将其分解为有细化机会的阶段。

示例：

首先，提供初步分析：[analysis_prompt]

然后，根据用户的反馈，细化您的分析：[refinement_prompt]

3.4 避免常见陷阱

几个常见错误会削弱技能的效果：

过度规范化：太多具体的规则可能使技能过于僵化，无法处理新情况。在具体性和灵活性之间取得平衡。

规范不足：太少的指南留下太多解释空间，导致不一致的输出。提供足够的结构以确保一致性。

矛盾指令：确保提示的不同部分不会相互冲突。检查整个提示的逻辑一致性。

隐含假设：不要假设 Claude 知道您的意思——让一切变得明确。如果某事很重要，直接说明。

过时信息：技能可能随着工具和最佳实践的发展而变得过时。定期审查和更新技能以确保它们保持最新。

3.5 测试您的提示

在部署技能之前，彻底测试提示：

1. 使用典型输入测试：验证技能对常见用例产生预期输出。
2. 使用边界情况测试：检查技能如何处理不寻常或极端的输入。
3. 使用边界条件测试：验证技能在其应该处理的限制范围内的行为。
4. 根据结果迭代：根据测试结果细化提示。

第四章：技能测试策略

4.1 为什么测试很重要

测试对于保持技能质量至关重要。没有全面的测试，就无法知道技能是否正常工作，或者更改是否引入了回归。测试提供：

信心：经过良好测试的技能可以放心部署，因为它们会按预期执行。

回归预防：测试在技能更新时捕获回归，防止以前工作的功能被破坏。

文档：测试作为可执行的文档，显示技能在不同场景下应该如何行为。

协作：测试帮助其他贡献者理解技能的预期行为，并安全地进行更改。

4.2 测试类型

不同类型的测试服务不同的目的：

单元测试验证技能的单个组件是否正常工作。例如，单元测试可能验证特定的提示模板对于给定输入是否产生预期输出。

集成测试验证技能与其他组件（如 Claude 执行环境或外部服务）是否正常工作。

端到端测试验证技能在真实场景中是否产生预期结果，从输入到最终输出。

回归测试验证更改没有破坏以前工作的功能。这些测试应涵盖所有已知的用例和边界情况。

4.3 测试覆盖

争取全面的测试覆盖：

Happy Path 测试：测试技能设计处理的典型、预期用例。

边界情况测试：测试不常见但仍应正确处理的异常或极端输入。

错误处理测试：测试技能如何处理错误、无效输入和意外情况。

边界测试：测试技能可以处理的限制。

负面测试：测试技能正确拒绝或处理其范围之外的请求。

4.4 编写有效的测试

有效的测试具有某些特征：

明确的目的：每个测试应该有明确的目的，易于理解。

独立性：测试应该相互独立，允许它们以任何顺序运行。

确定性：测试应该产生一致的结果，不因外部因素而变化。

快速：测试应该快速运行，以实现快速迭代。

有意义的断言：断言应该验证输出的有意义方面，而不是微不足道的细节。

示例测试结构：

test:
  name: '优雅地处理空输入'
  input:
    user_message: null
  expected_behavior:
    - '不应该崩溃'
    - '应该请求澄清'
    - '应该保持有帮助的语气'
  validation:
    - '响应是一个字符串'
    - '响应包含问题'
    - '没有抛出错误'

4.5 技能的测试驱动开发

考虑为技能遵循测试驱动开发（TDD）方法：

1. 先写测试：在实现技能之前，写下描述预期行为的测试。
2. 运行测试验证它们失败：测试最初应该失败，因为技能还不存在。
3. 实现技能：创建技能使测试通过。
4. 重构：在确保测试继续通过的同时改进技能。
5. 重复：为附加功能添加更多测试。

这种方法确保技能从一开始就被设计为可测试的。

第五章：文档编写最佳实践

5.1 为什么文档很重要

良好的文档对于技能的采用和可用性至关重要。文档帮助用户理解：

• 技能做什么
• 何时使用技能
• 如何有效使用技能
• 任何限制或注意事项
• 如何排查问题

没有良好的文档，即使出色的技能也可能未被使用或被误用。

5.2 文档类型

技能受益于几种类型的文档：

自述文件（README）：自述文件提供技能的概述，包括其用途、基本用法和基本示例。这是用户首先看到的，应该清晰且有吸引力。

API 文档：对于与外部服务交互或提供特定功能的技能，API 文档描述可用的操作、参数和返回值。

示例：具体示例展示技能的实际应用，展示如何将其用于不同任务。示例应涵盖典型用例并突出有趣的功能。

故障排除指南：故障排除指南帮助用户解决使用技能时可能遇到的常见问题。

更新日志：更新日志记录每个版本的变化，帮助用户理解技能的演进并决定是否升级。

5.3 编写有效的自述文件

自述文件通常是最重要的文档。良好的自述文件包括：

清晰的标题和描述：从清晰的名称和一两句描述开始，解释技能的作用。

快速开始：提供快速开始指南，展示使用技能的最简单方法。这应该足够简单，让用户在几分钟内入门。

详细用法：在快速开始之后，为需要更多背景信息的用户提供详细的使用信息。

示例：包含几个展示不同用例和配置的示例。

配置选项：记录所有配置选项，包括其用途、可接受的值和默认值。

需求：列出任何需求，如特定工具、权限或依赖项。

限制：诚实面对技能的局限性。这建立信任并帮助用户避免问题。

贡献：如果您欢迎贡献，说明其他人如何帮助改进技能。

5.4 文档模板

使用模板确保文档的一致性：

# 技能名称

## 概述

[一到两句关于技能作用的描述]

## 何时使用此技能

[描述技能设计处理的任务类型]

## 快速开始

[快速入门的步骤]

## 详细用法

### 配置选项

| 选项    | 类型   | 默认值    | 描述 |
| ------- | ------ | --------- | ---- |
| option1 | string | "default" | 描述 |

### 示例

#### 示例 1：[用例]

[描述]

[代码或说明]

#### 示例 2：[用例]

[描述]

[代码或说明]

## 故障排除

### 问题：[常见问题]

解决方案：[如何解决]

### 问题：[常见问题]

解决方案：[如何解决]

## 更新日志

### 版本 1.0.0（YYYY-MM-DD）

- 初始发布

5.5 保持文档最新

文档可能随着技能的演进而变得过时。保持文档最新：

1. 将文档纳入代码审查：与代码更改一起审查文档更改。
2. 每次发布时更新文档：将文档更新作为发布流程的一部分。
3. 版本化文档：使文档与技能版本保持同步。
4. 跟踪问题：使用问题或反馈渠道来识别文档问题。
5. 定期审查：安排定期审查文档的准确性和完整性。

第六章：部署与版本控制

6.1 版本控制策略

语义化版本控制（SemVer）提供清晰的版本控制策略：

主版本（X.0.0）：不兼容的更改，要求用户更新其用法。

次版本（1.X.0）：向后兼容的新功能。

补丁版本（1.0.X）：向后兼容的 bug 修复。

更新技能时：

• 如果进行破坏性更改，增加主版本。
• 如果添加新功能，增加次版本。
• 如果修复 bug，增加补丁版本。

6.2 发布流程

遵循结构化的发布流程：

1. 准备发布：更新版本号、更新日志和文档。
2. 运行全面测试：验证所有测试通过且技能正常工作。
3. 创建发布说明：记录更改内容、新增内容以及任何破坏性更改。
4. 发布技能：使技能在注册表中可用。
5. 宣布发布：让用户知道新版本。

6.3 弃用策略

当停止技能或进行破坏性更改时：

1. 提前宣布弃用：给用户充足的时间来适应。
2. 提供迁移路径：向用户展示如何迁移到新版本或替代技能。
3. 维护旧版本：在合理的时间内继续支持旧版本。
4. 逐步淘汰：逐渐淘汰旧版本，而不是一次性全部淘汰。

6.4 分发渠道

技能可以通过不同的渠道分发：

公共注册表：使技能公开可用，以便任何人都可以发现和使用它。

私人分发：仅与特定用户或团队共享技能。

精选集合：将相关技能分组到特定用例或领域的集合中。

选择最适合您的受众和业务需求的分发渠道。

第七章：高级主题

7.1 技能依赖与组合

高级技能可以依赖并与其他技能组合：

依赖管理：技能可以声明对其他技能的依赖，确保在需要时所需的技能可用。

组合模式：技能可以通过各种方式组合：

• 顺序组合：一个接一个地应用技能
• 并行组合：将多个技能应用于同一上下文
• 条件组合：根据条件应用技能

接口设计：在组合技能时，设计清晰的接口，使技能能够有效地协同工作。

7.2 动态技能选择

技能可以根据上下文动态选择：

上下文匹配：Claude 可以根据当前上下文自动选择相关技能。

用户偏好：用户可以指定针对不同类型任务应用哪些技能。

回退策略：当首选技能不可用时，回退技能可以提供基本功能。

7.3 性能优化

优化技能性能：

提示效率：在保持清晰度的同时保持提示简洁。不必要的冗长可能会减慢处理速度。

缓存：在适当的地方缓存结果以避免冗余处理。

延迟加载：仅在需要时加载技能以减少初始加载时间。

并行化：在处理多个任务时，在可能的地方并行化。

7.4 安全注意事项

当技能与敏感系统交互时，安全至关重要：

输入验证：验证所有输入以防止注入攻击。

安全默认：默认使用安全设置；明确选择加入可能存在风险的操作。

审计日志：记录操作以供安全审查和故障排除。

最小权限：仅请求完成任务所需的权限。

第八章：故障排除与优化

8.1 常见问题与解决方案

以下是技能作者遇到的常见问题以及如何解决：

问题：技能产生不一致的输出

解决方案：审查提示的清晰度和具体性。添加更明确的指南和示例。

问题：技能不处理边界情况

解决方案：识别边界情况并为每个添加特定处理。添加测试以验证边界情况处理。

问题：技能太慢

解决方案：优化提示效率。考虑缓存或延迟加载策略。

问题：技能与其他技能冲突

解决方案：审查技能交互。调整技能应用顺序或修改冲突指令。

问题：用户不理解如何使用技能

解决方案：改进文档，添加更多示例和更清晰的说明。

8.2 调试技术

故障排除技能时：

1. 隔离问题：在隔离环境中测试技能，以确定问题是技能本身还是外部因素。

2. 简化输入：从最小输入开始，逐步添加复杂性，以识别导致问题的原因。

3. 检查日志：查看任何可用的日志，以了解技能执行期间发生了什么。

4. 与示例比较：将实际输出与类似场景的预期输出进行比较。

5. 系统迭代：一次做一个更改，并在每次更改后进行测试。

8.3 性能优化

优化技能性能：

1. 分析执行：识别技能执行期间时间花在哪里。

2. 优化提示：删除不必要的说明并简化提示。

3. 减少复杂性：在可能的情况下简化技能逻辑。

4. 缓存结果：缓存常用结果以避免冗余计算。

5. 并行化：将独立操作拆分为并行任务。

8.4 持续改进

技能应该随着时间推移而演进：

1. 收集反馈：收集用户关于什么有效和什么无效的反馈。

2. 分析使用模式：了解技能是如何使用的，并识别改进机会。

3. 监控指标：跟踪性能指标以识别问题并衡量改进。

4. 定期迭代：根据反馈和分析进行定期改进。

5. 保持最新：使技能与它所涉及的工具和领域的变化保持同步。

结论

构建有效的 Claude Code 技能既是一门艺术，也是一门科学。技术方面——提示工程、测试、文档和部署——提供了基础，但成功最终取决于理解您的用户并解决实际问题。

请记住这些关键原则：

1. 从用户需求开始：理解用户试图完成什么，并设计帮助他们成功的技能。

2. 根据反馈迭代：技能通过迭代改进。收集反馈、分析使用情况并不断完善。

3. 严格测试：全面测试对于保持质量和信心至关重要。

4. 清晰文档：良好的文档对于采用和有效使用至关重要。

5. 保持最新：技术发展迅速。让您的技能与最新的工具和最佳实践保持同步。

通过遵循本指南中的原则和实践，您将能够创建真正为用户提供价值并经得起时间考验的技能。

附录 A：技能模板

以下是一个完整的技能模板，您可以用作起点：

skill.yaml
README.md
examples/
  - example1.yaml
  - example2.yaml
tests/
  - test_suite.yaml
docs/
  - detailed_usage.md
  - troubleshooting.md

附录 B：词汇表

Manifest（清单文件）：包含技能元数据的 skill.yaml 文件。

Prompt Template（提示模板）：定义技能行为的核心提示。

Skill Registry（技能注册表）：存储和发现技能的中央目录。

Semantic Versioning（语义化版本控制）：（SemVer）使用主.次.补丁版本号的版本控制方案。

Test-Driven Development（测试驱动开发）：一种在实现之前先写测试的开发方法。

本指南是一份活文档。请定期查看更新。