最佳实践

好的 Skills 简洁、结构良好且经过实际使用测试。本指南提供实用的编写决策，帮助您编写 Claude 可以发现并有效使用的 Skills。

有关 Skills 工作原理的概念背景，请参阅 Skills 概述。

核心原则

简洁是关键

上下文窗口是公共资源。您的 Skill 与 Claude 需要知道的其他所有内容共享上下文窗口，包括：

• 系统提示词
• 对话历史
• 其他 Skills 的元数据
• 您的实际请求

并非 Skill 中的每个 token 都有即时成本。在启动时，只有所有 Skills 的元数据（名称和描述）被预加载。Claude 仅在 Skill 变得相关时才读取 SKILL.md，并且仅在需要时才读取其他文件。但是，在 SKILL.md 中保持简洁仍然很重要：一旦 Claude 加载它，每个 token 都会与对话历史和其他上下文竞争。

默认假设：Claude 已经非常聪明

只添加 Claude 还不知道的上下文。质疑每条信息：

• "Claude 真的需要这个解释吗？"
• "我可以假设 Claude 知道这个吗？"
• "这段话值得它的 token 成本吗？"

好例子（简洁，约 50 tokens）：

## 提取 PDF 文本
使用 pdfplumber 提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

**坏例子**（太冗长，约 150 tokens）：

```markdown
## 提取 PDF 文本
PDF（便携式文档格式）文件是一种常见的文件格式，包含文本、图像和其他内容。要从 PDF 中提取文本，您需要使用一个库。有很多可用于 PDF 处理的库，但我们推荐 pdfplumber，因为它易于使用并能处理大多数情况...

简洁版本假设 Claude 知道什么是 PDF 以及库是如何工作的。

设置适当的自由度

将特异性级别与任务的脆弱性和可变性相匹配。

高自由度（基于文本的指令）：

适用于：

• 多种方法都有效
• 决策取决于上下文
• 启发式方法指导方法

中等自由度（伪代码或带参数的脚本）：

适用于：

• 存在首选模式
• 可以接受一些变化
• 配置影响行为

低自由度（特定脚本，很少或没有参数）：

适用于：

• 操作脆弱且容易出错
• 一致性至关重要
• 必须遵循特定顺序

使用您计划使用的所有模型进行测试

Skills 作为模型的补充，因此有效性取决于底层模型。使用您计划使用的所有模型测试您的 Skill。

按模型测试考虑因素：

• Claude Haiku（快速、经济）：Skill 是否提供足够的指导？
• Claude Sonnet（平衡）：Skill 是否清晰高效？
• Claude Opus（强大的推理能力）：Skill 是否避免过度解释？

Skill 结构

YAML Frontmatter：SKILL.md frontmatter 需要两个字段：

name：

• 最多 64 个字符
• 必须仅包含小写字母、数字和连字符
• 不能包含 XML 标签
• 不能包含保留字："anthropic"、"claude"

description：

• 必须非空
• 最多 1024 个字符
• 不能包含 XML 标签
• 应描述 Skill 做什么以及何时使用它

命名约定

使用一致的命名模式使 Skills 更易于引用和讨论。我们建议使用动名词形式（动词 + -ing）作为 Skill 名称。

好的命名示例（动名词形式）：

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code
• writing-documentation

避免：

• 模糊的名称：helper、utils、tools
• 过于通用：documents、data、files
• 保留字：anthropic-helper、claude-tools

编写有效的描述

description 字段启用 Skill 发现，应包括 Skill 做什么以及何时使用它。

始终使用第三人称。描述被注入系统提示词，不一致的视角会导致发现问题。

• 好："处理 Excel 文件并生成报告"
• 避免："我可以帮助您处理 Excel 文件"
• 避免："您可以使用它来处理 Excel 文件"

渐进式披露模式

SKILL.md 作为概述，根据需要将 Claude 指向详细材料，就像入职指南中的目录一样。

实用指导：

• 保持 SKILL.md 正文在 500 行以下以获得最佳性能
• 当接近此限制时，将内容拆分为单独的文件

避免深度嵌套引用

当文件从其他引用的文件中被引用时，Claude 可能会部分读取文件。保持从 SKILL.md 只有一级深度的引用。

工作流程和反馈循环

对复杂任务使用工作流程

将复杂操作分解为清晰的顺序步骤。对于特别复杂的工作流程，提供一个清单，Claude 可以将其复制到响应中并在进行时勾选。

实现反馈循环

常见模式：运行验证器 → 修复错误 → 重复

这种模式大大提高了输出质量。

内容指南

避免时间敏感信息

不要包含会过时的信息。

使用一致的术语

选择一个术语并在整个 Skill 中使用它。

常见模式

模板模式

提供输出格式的模板。将严格程度与您的需求相匹配。

示例模式

对于输出质量取决于查看示例的 Skills，提供输入/输出对，就像在常规提示中一样。

条件工作流程模式

引导 Claude 通过决策点。

评估和迭代

首先构建评估

在编写大量文档之前创建评估。这确保您的 Skill 解决实际问题，而不是记录想象的问题。

与 Claude 迭代开发 Skills

最有效的 Skill 开发过程涉及 Claude 本身。与一个 Claude 实例（"Claude A"）合作创建将由其他实例（"Claude B"）使用的 Skill。

要避免的反模式

避免 Windows 风格的路径

始终在文件路径中使用正斜杠，即使在 Windows 上：

• ✓ 好：scripts/helper.py、reference/guide.md
• ✗ 避免：scripts\helper.py、reference\guide.md

避免提供太多选项

除非必要，否则不要提供多种方法。提供一个默认值和一个逃生舱口。

高级：带有可执行代码的 Skills

解决问题，而不是推卸

在为 Skills 编写脚本时，处理错误条件而不是推给 Claude。

提供实用脚本

即使 Claude 可以编写脚本，预制脚本也有优势：

• 比生成的代码更可靠
• 节省 tokens（无需在上下文中包含代码）
• 节省时间（无需生成代码）
• 确保跨使用的一致性

技术说明

YAML frontmatter 要求

• name：最多 64 个字符，仅限小写字母/数字/连字符，无 XML 标签，无保留字
• description：最多 1024 个字符，非空，无 XML 标签

Token 预算

保持 SKILL.md 正文在 500 行以下以获得最佳性能。

有效 Skills 的清单

在分享 Skill 之前，请验证：

核心质量

• ✓ 描述是具体的并包含关键术语
• ✓ 描述包括 Skill 做什么以及何时使用它
• ✓ SKILL.md 正文在 500 行以下
• ✓ 额外的详细信息在单独的文件中（如果需要）
• ✓ 没有时间敏感信息
• ✓ 整个过程中术语一致
• ✓ 示例是具体的，而不是抽象的

代码和脚本

• ✓ 脚本解决问题而不是推给 Claude
• ✓ 错误处理是明确和有帮助的
• ✓ 没有"巫术常量"（所有值都有理由）
• ✓ 所需的包已列出并验证
• ✓ 没有 Windows 风格的路径

测试

• ✓ 至少创建了三个评估
• ✓ 使用 Haiku、Sonnet 和 Opus 进行了测试
• ✓ 使用真实使用场景进行了测试