当前位置：首页 > news >正文

Claude Skill 编写最佳实践

news 2025/10/21 8:37:38

原文链接：https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices

原文标题：《Skill authoring best practices》

作者：Anthropic

文章内容很好，翻译。

学习如何编写有效的 Skill，以便 Claude 能够成功发现和使用它们。

优秀的 Skill 应简洁、结构良好，并经过实际使用测试。本指南提供了实用的编写决策，帮助您编写出能让 Claude 有效发现和使用的 Skill。

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

核心原则

简洁是关键

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

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

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

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

只添加 Claude 尚不具备的上下文。对每一条信息都要进行审视：

• “Claude 真的需要这个解释吗？”
• “我能假设 Claude 知道这个吗？”
• “这段话的 token 成本合理吗？”

好的例子：简洁（约 50 个 token）：

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

坏的例子：过于冗长（约 150 个 token）：

## 提取 PDF 文本PDF（便携式文档格式）文件是一种常见的包含文本、图像和其他内容的文件格式。要从 PDF 中提取文本，您需要使用一个库。有许多可用于 PDF 处理的库，但我们推荐 pdfplumber，因为它易于使用且能很好地处理大多数情况。首先，您需要使用 pip 安装它。然后您可以使用下面的代码...

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

设置适当的自由度

根据任务的脆弱性和可变性，匹配相应的特异性水平。

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

使用场景：

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

例子：

## 代码审查流程1.  分析代码结构和组织
2.  检查潜在的错误或边缘情况
3.  提出提高可读性和可维护性的建议
4.  验证是否遵守项目约定

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

使用场景：

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

例子：

## 生成报告使用此模板并根据需要进行自定义：```python
def generate_report(data, format="markdown", include_charts=True):# 处理数据# 以指定格式生成输出# 可选择性地包含可视化图表
```

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

使用场景：

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

例子：

## 数据库迁移严格运行此脚本：```bash
python scripts/migrate.py --verify --backup
```不要修改命令或添加额外的标志。

类比：将 Claude 想象成一个正在探索路径的机器人：

• 两边是悬崖的窄桥：只有一条安全的前进道路。提供具体的护栏和精确的指令（低自由度）。例如：必须按确切顺序运行的数据库迁移。
• 没有危险的开阔田野：条条大路通罗马。给出大致方向，并相信 Claude 能找到最佳路线（高自由度）。例如：代码审查，其中上下文决定了最佳方法。

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

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

按模型划分的测试注意事项：

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

对 Opus 来说完美的作品可能需要为 Haiku 提供更多细节。如果您计划在多个模型中使用您的 Skill，请力求编写适用于所有模型的指令。

Skill 结构

YAML Frontmatter：SKILL.md 的 frontmatter 支持两个字段：

• name - Skill 的人类可读名称（最多 64 个字符）
• description - 关于 Skill 功能和使用时机的单行描述（最多 1024 个字符）

有关完整的 Skill 结构详细信息，请参阅 Skill 概述。

命名约定

使用一致的命名模式，使 Skill 更易于引用和讨论。我们建议对 Skill 名称使用动名词形式（动词 + -ing），因为这清楚地描述了 Skill 提供的活动或能力。

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

• "Processing PDFs" (处理 PDF)
• "Analyzing spreadsheets" (分析电子表格)
• "Managing databases" (管理数据库)
• "Testing code" (测试代码)
• "Writing documentation" (编写文档)

可接受的替代方案：

• 名词短语："PDF Processing" (PDF 处理), "Spreadsheet Analysis" (电子表格分析)
• 面向动作："Process PDFs" (处理 PDF), "Analyze Spreadsheets" (分析电子表格)

避免：

• 模糊的名称："Helper" (助手), "Utils" (工具), "Tools" (工具)
• 过于通用："Documents" (文档), "Data" (数据), "Files" (文件)
• 在您的技能集合中不一致的模式

一致的命名使得以下操作更容易：

• 在文档和对话中引用 Skill
• 一目了然地了解 Skill 的功能
• 组织和搜索多个 Skill
• 维护一个专业、有凝聚力的 Skill 库

编写有效的描述

description 字段用于 Skill 发现，应同时包含 Skill 的功能和使用时机。

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

• 好的： "处理 Excel 文件并生成报告"
• 避免： "我可以帮你处理 Excel 文件"
• 避免： "你可以用这个来处理 Excel 文件"

具体并包含关键词。同时包括 Skill 的功能和使用的具体触发器/上下文。

每个 Skill 只有一个描述字段。描述对于技能选择至关重要：Claude 使用它从可能超过 100 个可用 Skill 中选择正确的 Skill。您的描述必须提供足够的细节，以便 Claude 知道何时选择此 Skill，而 SKILL.md 的其余部分则提供实现细节。

有效示例：

PDF 处理 Skill：

description: 从 PDF 文件中提取文本和表格、填写表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。

Excel 分析 Skill：

description: 分析 Excel 电子表格、创建数据透视表、生成图表。在分析 Excel 文件、电子表格、表格数据或 .xlsx 文件时使用。

Git 提交助手 Skill：

description: 通过分析 git diff 生成描述性的提交信息。在用户请求帮助编写提交信息或审查暂存更改时使用。

避免像下面这样模糊的描述：

description: 帮助处理文档

description: 处理数据

description: 对文件进行操作

渐进式披露模式

SKILL.md 作为一个概述，根据需要将 Claude 指向详细材料，就像入职指南中的目录一样。有关渐进式披露工作原理的解释，请参阅概述中的 Skill 工作原理。

实用指南：

• 为获得最佳性能，请将 SKILL.md 主体保持在 500 行以下
• 当接近此限制时，将内容拆分为单独的文件
• 使用以下模式有效组织指令、代码和资源

可视化概述：从简单到复杂

一个基本的 Skill 从一个仅包含元数据和指令的 SKILL.md 文件开始：

显示 YAML frontmatter 和 markdown 主体的简单 SKILL.md 文件

随着您的 Skill 的增长，您可以捆绑 Claude 仅在需要时加载的其他内容：

捆绑其他参考文件，如 reference.md 和 forms.md。

完整的 Skill 目录结构可能如下所示：

pdf/
├── SKILL.md              # 主要说明（触发时加载）
├── FORMS.md              # 表单填写指南（根据需要加载）
├── reference.md          # API 参考（根据需要加载）
├── examples.md           # 用法示例（根据需要加载）
└── scripts/├── analyze_form.py   # 实用程序脚本（执行，不加载）├── fill_form.py      # 表单填写脚本└── validate.py       # 验证脚本

模式 1：带引用的高级指南

---
name: PDF 处理
description: 从 PDF 文件中提取文本和表格、填写表单和合并文档。在处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。
---# PDF 处理## 快速入门使用 pdfplumber 提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:text = pdf.pages[0].extract_text()
```## 高级功能**表单填写**：完整指南请参阅 [FORMS.md](FORMS.md)
**API 参考**：所有方法请参阅 [REFERENCE.md](REFERENCE.md)
**示例**：常见模式请参阅 [EXAMPLES.md](EXAMPLES.md)

Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：特定领域的组织

对于具有多个领域的 Skill，按领域组织内容以避免加载不相关的上下文。当用户询问销售指标时，Claude 只需要读取与销售相关的模式，而不需要财务或营销数据。这可以保持较低的 token 使用量和集中的上下文。

bigquery-skill/
├── SKILL.md (概述和导航)
└── reference/├── finance.md (收入、计费指标)├── sales.md (机会、渠道)├── product.md (API 使用情况、功能)└── marketing.md (活动、归因)

# BigQuery 数据分析## 可用数据集**财务**：收入、ARR、计费 → 请参阅 [reference/finance.md](reference/finance.md)
**销售**：机会、渠道、客户 → 请参阅 [reference/sales.md](reference/sales.md)
**产品**：API 使用情况、功能、采用率 → 请参阅 [reference/product.md](reference/product.md)
**营销**：活动、归因、电子邮件 → 请参阅 [reference/marketing.md](reference/marketing.md)## 快速搜索使用 grep 查找特定指标：```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

模式 3：条件性细节

显示基本内容，链接到高级内容：

# DOCX 处理## 创建文档对新文档使用 docx-js。请参阅 [DOCX-JS.md](DOCX-JS.md)。## 编辑文档对于简单的编辑，直接修改 XML。**对于跟踪的更改**：请参阅 [REDLINING.md](REDLINING.md)
**对于 OOXML 详细信息**：请参阅 [OOXML.md](OOXML.md)

只有当用户需要这些功能时，Claude 才会读取 REDLINING.md 或 OOXML.md。

避免深度嵌套的引用

当文件从其他被引用的文件中被引用时，Claude 可能会部分读取这些文件。遇到嵌套引用时，Claude 可能会使用 head -100 之类的命令来预览内容，而不是读取整个文件，从而导致信息不完整。

保持引用距离 SKILL.md 一层深度。所有引用文件都应直接从 SKILL.md 链接，以确保 Claude 在需要时能读取完整的文件。

坏的例子：太深：

# SKILL.md
请参阅 [advanced.md](advanced.md)...# advanced.md
请参阅 [details.md](details.md)...# details.md
这是实际信息...

好的例子：一层深度：

# SKILL.md**基本用法**：[SKILL.md 中的说明]
**高级功能**：请参阅 [advanced.md](advanced.md)
**API 参考**：请参阅 [reference.md](reference.md)
**示例**：请参阅 [examples.md](examples.md)

使用目录构建较长的参考文件

对于超过 100 行的参考文件，请在顶部包含目录。这可以确保 Claude 即使在通过部分读取进行预览时也能看到可用信息的全部范围。

例子：

# API 参考## 目录
- 身份验证和设置
- 核心方法（创建、读取、更新、删除）
- 高级功能（批量操作、webhook）
- 错误处理模式
- 代码示例## 身份验证和设置
...## 核心方法
...

然后，Claude 可以读取完整文件或根据需要跳转到特定部分。

有关这种基于文件系统的架构如何实现渐进式披露的详细信息，请参阅下面高级部分中的运行时环境部分。

工作流和反馈循环

对复杂任务使用工作流

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

示例 1：研究综合工作流（对于没有代码的 Skill）：

## 研究综合工作流复制此清单并跟踪您的进度：```
研究进度：
- [ ] 步骤 1：阅读所有源文档
- [ ] 步骤 2：确定关键主题
- [ ] 步骤 3：交叉引用声明
- [ ] 步骤 4：创建结构化摘要
- [ ] 步骤 5：验证引文
```**步骤 1：阅读所有源文档**查看 `sources/` 目录中的每个文档。注意主要论点和支持证据。**步骤 2：确定关键主题**在各个来源中寻找模式。哪些主题反复出现？来源在哪些方面达成一致或存在分歧？**步骤 3：交叉引用声明**对于每个主要声明，验证它是否出现在源材料中。注意哪个来源支持每个观点。**步骤 4：创建结构化摘要**按主题组织发现。包括：
- 主要声明
- 来自来源的支持证据
- 冲突的观点（如果有）**步骤 5：验证引文**检查每个声明是否引用了正确的源文档。如果引文不完整，请返回步骤 3。

此示例显示了工作流如何应用于不需要代码的分析任务。清单模式适用于任何复杂的多步骤过程。

示例 2：PDF 表单填写工作流（对于有代码的 Skill）：

## PDF 表单填写工作流复制此清单并在完成项目时勾选：```
任务进度：
- [ ] 步骤 1：分析表单（运行 analyze_form.py）
- [ ] 步骤 2：创建字段映射（编辑 fields.json）
- [ ] 步骤 3：验证映射（运行 validate_fields.py）
- [ ] 步骤 4：填写表单（运行 fill_form.py）
- [ ] 步骤 5：验证输出（运行 verify_output.py）
```**步骤 1：分析表单**运行：`python scripts/analyze_form.py input.pdf`这将提取表单字段及其位置，并保存到 `fields.json`。**步骤 2：创建字段映射**编辑 `fields.json` 为每个字段添加值。**步骤 3：验证映射**运行：`python scripts/validate_fields.py fields.json`在继续之前修复任何验证错误。**步骤 4：填写表单**运行：`python scripts/fill_form.py input.pdf fields.json output.pdf`**步骤 5：验证输出**运行：`python scripts/verify_output.py output.pdf`如果验证失败，请返回步骤 2。

清晰的步骤可防止 Claude 跳过关键的验证。清单可帮助 Claude 和您跟踪多步骤工作流的进度。

实现反馈循环

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

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

示例 1：样式指南合规性（对于没有代码的 Skill）：

## 内容审查流程1.  根据 STYLE_GUIDE.md 中的指南起草您的内容
2.  对照清单进行审查：*   检查术语一致性*   验证示例是否遵循标准格式*   确认所有必需部分都存在
3.  如果发现问题：*   用具体的章节引用记录每个问题*   修改内容*   再次审查清单
4.  只有在满足所有要求时才继续
5.  最终确定并保存文档

这显示了使用参考文档而不是脚本的验证循环模式。“验证器”是 STYLE_GUIDE.md，Claude 通过阅读和比较来执行检查。

示例 2：文档编辑过程（对于有代码的 Skill）：

## 文档编辑过程1.  对 `word/document.xml` 进行编辑
2.  **立即验证**：`python ooxml/scripts/validate.py unpacked_dir/`
3.  如果验证失败：*   仔细查看错误消息*   修复 XML 中的问题*   再次运行验证
4.  **只有在验证通过后才继续**
5.  重建：`python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6.  测试输出文档

验证循环可以及早发现错误。

内容指南

避免时间敏感信息

不要包含会过时的信息：

坏的例子：时间敏感（会变得错误）：

如果你在 2025 年 8 月之前执行此操作，请使用旧的 API。
2025 年 8 月之后，请使用新的 API。

好的例子（使用“旧模式”部分）：

## 当前方法使用 v2 API 端点：`api.example.com/v2/messages`## 旧模式<details>
<summary>旧版 v1 API（已于 2025-08 弃用）</summary>v1 API 使用：`api.example.com/v1/messages`此端点不再受支持。
</details>

旧模式部分提供了历史背景，而不会使主要内容变得混乱。

使用一致的术语

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

好的 - 一致：

• 始终是“API 端点”
• 始终是“字段”
• 始终是“提取”

坏的 - 不一致：

• 混合使用“API 端点”、“URL”、“API 路由”、“路径”
• 混合使用“字段”、“框”、“元素”、“控件”
• 混合使用“提取”、“拉取”、“获取”、“检索”

一致性有助于 Claude 理解和遵循指令。

常见模式

模板模式

为输出格式提供模板。根据您的需求匹配严格程度。

对于严格的要求（如 API 响应或数据格式）：

## 报告结构始终使用此确切的模板结构：```markdown
# [分析标题]## 执行摘要
[关键发现的一段概述]## 关键发现
- 发现 1 及支持数据
- 发现 2 及支持数据
- 发现 3 及支持数据## 建议
1.  具体的、可操作的建议
2.  具体的、可操作的建议
```

对于灵活的指导（当适应性有用时）：

## 报告结构这是一个合理的默认格式，但请根据分析使用您的最佳判断：```markdown
# [分析标题]## 执行摘要
[概述]## 关键发现
[根据您的发现调整部分]## 建议
[根据具体情况量身定制]
```根据具体的分析类型按需调整部分。

示例模式

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

## 提交信息格式按照以下示例生成提交信息：**示例 1：**
输入：使用 JWT 令牌添加了用户身份验证
输出：
```
feat(auth): 实现基于 JWT 的身份验证添加登录端点和令牌验证中间件
```**示例 2：**
输入：修复了报告中日期显示不正确的错误
输出：
```
fix(reports): 纠正时区转换中的日期格式在报告生成中始终使用 UTC 时间戳
```**示例 3：**
输入：更新了依赖项并重构了错误处理
输出：
```
chore: 更新依赖项并重构错误处理- 将 lodash 升级到 4.17.21
- 在所有端点中标准化错误响应格式
```遵循此样式：类型(范围): 简要说明，然后是详细解释。

示例比单独的描述更能帮助 Claude 理解所需的风格和细节层次。

条件工作流模式

引导 Claude 通过决策点：

## 文档修改工作流1.  确定修改类型：**创建新内容？** → 遵循下面的“创建工作流”**编辑现有内容？** → 遵循下面的“编辑工作流”2.  创建工作流：*   使用 docx-js 库*   从头开始构建文档*   导出为 .docx 格式3.  编辑工作流：*   解包现有文档*   直接修改 XML*   每次更改后进行验证*   完成后重新打包

如果工作流变得庞大或复杂，包含许多步骤，请考虑将它们推送到单独的文件中，并告诉 Claude 根据手头的任务读取适当的文件。

评估和迭代

首先构建评估

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

评估驱动的开发：

1. 识别差距：在没有 Skill 的情况下，让 Claude 执行代表性任务。记录具体的失败或缺失的上下文
2. 创建评估：构建三个测试这些差距的场景
3. 建立基线：在没有 Skill 的情况下衡量 Claude 的性能
4. 编写最少的指令：创建刚好足够的内容来解决差距并通过评估
5. 迭代：执行评估，与基线进行比较，并进行优化

这种方法可确保您解决的是实际问题，而不是预测可能永远不会出现的需求。

评估结构：

{"skills":["pdf-processing"],
"query":"从这个 PDF 文件中提取所有文本并将其保存到 output.txt",
"files":["test-files/document.pdf"],
"expected_behavior":["使用适当的 PDF 处理库或命令行工具成功读取 PDF 文件","从文档的所有页面中提取文本内容，不遗漏任何页面","以清晰、可读的格式将提取的文本保存到名为 output.txt 的文件中"
]
}

此示例演示了使用简单测试标准的数据驱动评估。我们目前不提供运行这些评估的内置方法。用户可以创建自己的评估系统。评估是衡量 Skill 有效性的真实来源。

与 Claude 迭代开发 Skill

最有效的 Skill 开发过程本身就涉及 Claude。与一个 Claude 实例（“Claude A”）合作创建一个将由其他实例（“Claude B”）使用的 Skill。Claude A 帮助您设计和优化指令，而 Claude B 则在实际任务中测试它们。这是因为 Claude 模型既了解如何编写有效的智能体指令，也了解智能体需要哪些信息。

创建一个新的 Skill：

1. 在没有 Skill 的情况下完成任务：使用常规提示与 Claude A 一起解决问题。在工作过程中，您会自然地提供上下文、解释偏好并分享程序性知识。注意您反复提供的信息。
2. 识别可重用模式：完成任务后，确定您提供的哪些上下文对将来的类似任务有用。
示例：如果您完成了 BigQuery 分析，您可能提供了表名、字段定义、过滤规则（如“始终排除测试帐户”）和常见的查询模式。
3. 要求 Claude A 创建一个 Skill：“创建一个 Skill，捕获我们刚刚使用的这个 BigQuery 分析模式。包括表模式、命名约定和关于过滤测试帐户的规则。” Claude 模型本身就理解 Skill 的格式和结构。您不需要特殊的系统提示或“编写技能”的技能来让 Claude 帮助创建 Skill。只需请求 Claude 创建一个 Skill，它就会生成结构正确的 SKILL.md 内容，并带有适当的 frontmatter 和主体内容。
4. 审查简洁性：检查 Claude A 是否添加了不必要的解释。问：“删除关于胜率含义的解释——Claude 已经知道了。”
5. 改进信息架构：要求 Claude A 更有效地组织内容。例如：“将此内容组织起来，使表模式位于一个单独的参考文件中。我们以后可能会添加更多表。”
6. 在类似任务上进行测试：在相关的用例上使用带有 Skill 的 Claude B（一个加载了 Skill 的新实例）。观察 Claude B 是否能找到正确的信息，正确应用规则，并成功处理任务。
7. 根据观察进行迭代：如果 Claude B 遇到困难或遗漏了某些内容，请向 Claude A 提供具体信息：“当 Claude 使用此 Skill 时，它忘记了按日期筛选第四季度的数据。我们是否应该添加一个关于日期筛选模式的部分？”

迭代现有 Skill：

在改进 Skill 时，同样的层次模式仍在继续。您在以下两者之间交替进行：

• 与 Claude A 合作（帮助优化 Skill 的专家）
• 使用 Claude B 进行测试（使用 Skill 执行实际工作的智能体）
• 观察 Claude B 的行为 并将见解带回给 Claude A

1. 在实际工作流中使用 Skill：给 Claude B（加载了 Skill）实际任务，而不是测试场景
2. 观察 Claude B 的行为：注意它在哪些方面遇到困难、成功或做出意外的选择
观察示例：“当我向 Claude B 索要区域销售报告时，它编写了查询但忘记了过滤掉测试帐户，尽管 Skill 中提到了这个规则。”
3. 返回 Claude A 进行改进：分享当前的 SKILL.md 并描述您的观察。问：“我注意到当我索要区域报告时，Claude B 忘记了过滤测试帐户。Skill 中提到了过滤，但也许不够突出？”
4. 审查 Claude A 的建议：Claude A 可能会建议重新组织以使规则更突出，使用更强的语言如“必须过滤”而不是“总是过滤”，或者重组工作流部分。
5. 应用和测试更改：使用 Claude A 的优化更新 Skill，然后再次使用 Claude B 在类似请求上进行测试
6. 根据使用情况重复：随着您遇到新场景，继续这个观察-优化-测试的循环。每次迭代都会根据观察到的真实智能体行为而不是假设来改进 Skill。

收集团队反馈：

1. 与团队成员分享 Skill 并观察他们的使用情况
2. 问：Skill 是否在预期时激活？指令是否清晰？缺少什么？
3. 采纳反馈以解决您自己使用模式中的盲点

为什么这种方法有效：Claude A 了解智能体需求，您提供领域专业知识，Claude B 通过实际使用揭示差距，而迭代优化则根据观察到的行为而不是假设来改进 Skill。

观察 Claude 如何导航 Skill

在迭代 Skill 时，请注意 Claude 在实践中实际如何使用它们。注意：

• 意外的探索路径：Claude 是否以您未预料到的顺序读取文件？这可能表明您的结构不像您想象的那么直观
• 错过的连接：Claude 是否未能遵循对重要文件的引用？您的链接可能需要更明确或更突出
• 对某些部分的过度依赖：如果 Claude 反复读取同一个文件，请考虑该内容是否应放在主 SKILL.md 中
• 被忽略的内容：如果 Claude 从未访问过捆绑的文件，那么它可能是不必要的或在主要说明中信号不佳

根据这些观察而不是假设进行迭代。您的 Skill 元数据中的“名称”和“描述”尤其重要。Claude 在决定是否响应当前任务触发 Skill 时会使用这些信息。确保它们清楚地描述了 Skill 的功能和使用时机。

要避免的反模式

避免使用 Windows 风格的路径

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

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

Unix 风格的路径适用于所有平台，而 Windows 风格的路径在 Unix 系统上会导致错误。

避免提供太多选项

除非必要，否则不要提供多种方法：

**坏的例子：太多选择**（令人困惑）：
“你可以使用 pypdf、pdfplumber、PyMuPDF、pdf2image 或...”**好的例子：提供默认值**（带有备用方案）：
“使用 pdfplumber 进行文本提取：
```python
import pdfplumber
```对于需要 OCR 的扫描 PDF，请改用 pdf2image 和 pytesseract。”

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

以下部分重点介绍包含可执行脚本的 Skill。如果您的 Skill 仅使用 markdown 指令，请跳至有效 Skill 清单。

解决问题，而不是推卸责任

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

好的例子：明确处理错误：

def process_file(path):"""处理文件，如果文件不存在则创建它。"""try:withopen(path) as f:return f.read()except FileNotFoundError:# 创建具有默认内容的文件而不是失败print(f"文件 {path} 未找到，正在创建默认文件")withopen(path, 'w') as f:f.write('')return''except PermissionError:# 提供替代方案而不是失败print(f"无法访问 {path}，使用默认值")return ''

坏的例子：推给 Claude：

def process_file(path):# 直接失败，让 Claude 自己解决return open(path).read()

配置参数也应进行论证和记录，以避免“巫毒常量”（Ousterhout 定律）。如果您不知道正确的值，Claude 将如何确定它？

好的例子：自文档化：

# HTTP 请求通常在 30 秒内完成
# 更长的超时时间考虑了慢速连接
REQUEST_TIMEOUT = 30# 三次重试在可靠性与速度之间取得了平衡
# 大多数间歇性故障在第二次重试时解决
MAX_RETRIES = 3

坏的例子：魔法数字：

TIMEOUT = 47  # 为什么是 47？
RETRIES = 5   # 为什么是 5？

提供实用程序脚本

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

实用程序脚本的好处：

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

将可执行脚本与指令文件捆绑在一起

上图显示了可执行脚本如何与指令文件一起工作。指令文件 (forms.md) 引用脚本，Claude 无需将其内容加载到上下文中即可执行它。

重要区别：在您的指令中明确指出 Claude 应该：

• 执行脚本（最常见）：“运行 analyze_form.py 以提取字段”
• 将其作为参考阅读（对于复杂逻辑）：“有关字段提取算法，请参阅 analyze_form.py”

对于大多数实用程序脚本，首选执行，因为它更可靠、更高效。有关脚本执行工作原理的详细信息，请参阅下面的运行时环境部分。

例子：

## 实用程序脚本**analyze_form.py**：从 PDF 中提取所有表单字段```bash
python scripts/analyze_form.py input.pdf > fields.json
```输出格式：
```json
{"field_name": {"type": "text", "x": 100, "y": 200},"signature": {"type": "sig", "x": 150, "y": 500}
}
```**validate_boxes.py**：检查重叠的边界框```bash
python scripts/validate_boxes.py fields.json
# 返回：“OK”或列出冲突
```**fill_form.py**：将字段值应用于 PDF```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

使用视觉分析

当输入可以呈现为图像时，让 Claude 对其进行分析：

## 表单布局分析1.  将 PDF 转换为图像：```bashpython scripts/pdf_to_images.py form.pdf```2.  分析每个页面图像以识别表单字段
3.  Claude 可以直观地看到字段位置和类型

在此示例中，您需要编写 `pdf_to_images.py` 脚本。

Claude 的视觉能力有助于理解布局和结构。

创建可验证的中间输出

当 Claude 执行复杂、开放式的任务时，它可能会犯错。“计划-验证-执行”模式通过让 Claude 首先以结构化格式创建计划，然后在执行之前使用脚本验证该计划来及早发现错误。

示例：想象一下，要求 Claude 根据电子表格更新 PDF 中的 50 个表单字段。如果没有验证，Claude 可能会引用不存在的字段、创建冲突的值、遗漏必填字段或错误地应用更新。

解决方案：使用上面显示的（PDF 表单填写）工作流模式，但添加一个在应用更改之前进行验证的中间 changes.json 文件。工作流变为：分析 → 创建计划文件 → 验证计划 → 执行 → 验证。

为什么这种模式有效：

• 及早发现错误：验证在应用更改之前发现问题
• 机器可验证：脚本提供客观验证
• 可逆的规划：Claude 可以在不接触原始文件的情况下迭代计划
• 清晰的调试：错误消息指向具体问题

何时使用：批量操作、破坏性更改、复杂的验证规则、高风险操作。

实施技巧：使验证脚本具有详细的错误消息，例如“未找到字段‘signature_date’。可用字段：customer_name、order_total、signature_date_signed”，以帮助 Claude 修复问题。

打包依赖项

Skill 在具有平台特定限制的代码执行环境中运行：

• claude.ai：可以从 npm 和 PyPI 安装软件包，并从 GitHub 存储库中拉取
• Anthropic API：没有网络访问权限，也没有运行时软件包安装

在您的 SKILL.md 中列出所需的软件包，并验证它们在代码执行工具文档中可用。

运行时环境

Skill 在具有文件系统访问、bash 命令和代码执行能力的代码执行环境中运行。有关此架构的概念性解释，请参阅概述中的Skill 架构。

这对您的创作有何影响：

Claude 如何访问 Skill：

1. 预加载元数据：启动时，所有 Skill 的 YAML frontmatter 中的名称和描述都会加载到系统提示中
2. 按需读取文件：Claude 在需要时使用 bash Read 工具从文件系统访问 SKILL.md 和其他文件
3. 高效执行脚本：实用程序脚本可以通过 bash 执行，而无需将其全部内容加载到上下文中。只有脚本的输出会消耗 token
4. 大文件没有上下文惩罚：参考文件、数据或文档在实际读取之前不会消耗上下文 token

• 文件路径很重要：Claude 像文件系统一样导航您的技能目录。使用正斜杠 (reference/guide.md)，而不是反斜杠
• 描述性地命名文件：使用指示内容的文件名：form_validation_rules.md，而不是 doc2.md
• 为发现而组织：按领域或功能构建目录
- • 好的：reference/finance.md、reference/sales.md
- • 坏的：docs/file1.md、docs/file2.md
• 捆绑全面的资源：包括完整的 API 文档、大量示例、大型数据集；在访问之前没有上下文惩罚
• 对确定性操作首选脚本：编写 validate_form.py 而不是要求 Claude 生成验证代码
• 明确执行意图：
- • “运行 analyze_form.py 以提取字段”（执行）
- • “有关提取算法，请参阅 analyze_form.py”（作为参考阅读）
• 测试文件访问模式：通过使用真实请求进行测试，验证 Claude 可以导航您的目录结构

例子：

bigquery-skill/
├── SKILL.md (概述，指向参考文件)
└── reference/├── finance.md (收入指标)├── sales.md (渠道数据)└── product.md (使用情况分析)

当用户询问收入时，Claude 会读取 SKILL.md，看到对 reference/finance.md 的引用，并调用 bash 只读取该文件。sales.md 和 product.md 文件保留在文件系统上，在需要之前消耗零上下文 token。这种基于文件系统的模型是实现渐进式披露的原因。Claude 可以导航并选择性地加载每个任务所需的确切内容。

有关技术架构的完整详细信息，请参阅 Skill 概述中的Skill 工作原理。

MCP 工具参考

如果您的 Skill 使用 MCP（模型上下文协议）工具，请始终使用完全限定的工具名称以避免“找不到工具”的错误。

格式：ServerName:tool_name

例子：

使用 BigQuery:bigquery_schema 工具检索表模式。
使用 GitHub:create_issue 工具创建问题。

其中：

• BigQuery 和 GitHub 是 MCP 服务器名称
• bigquery_schema 和 create_issue 是这些服务器中的工具名称

如果没有服务器前缀，Claude 可能无法找到该工具，尤其是在有多个 MCP 服务器可用的情况下。

避免假设工具已安装

不要假设软件包可用：

**坏的例子：假设已安装**：
“使用 pdf 库处理文件。”**好的例子：明确依赖关系**：
“安装所需的软件包：`pip install pypdf`然后使用它：
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```”