【万字长文】Agent Skills黄金应用原则，都在Anthropic这篇技能创作最佳实践里

全文约1.2万字，阅读时间15分钟

文/王吉伟

最近Agent Skills（智能体技能）真的很火，因为它确实好用。

并且随着更多Agent构建平台的支持，用起来也越来越简单。现在不用装claude code或者Open Code之类的终端，就能轻松使用它。

比在Coze平台的技能商店选择你需要的技能，安装以后就可以使用。如果感觉商店的技能没有你想用的，也可以从其他技能市场找到你心仪的技能，下载以后在Coze创建技能时上传这个技能，这样就能在线使用这个技能了。就像我安装的这个画布设计技能，用起来还是挺有意思的。

对于如何找到Agent Skills打包资源，这里提供几个来源，大家也可以在评论区补充：

• Skillsmp

  https://skillsmp.com/

• Mcpmarket

  https://mcpmarket.com/zh/tools/skills/n8n-pull-request-creator

• Agent Skills Directory

  https://www.skillsdirectory.com/

• https://skills.sh/

• https://github.com/anthropics/skills/tree/main/skills

• https://github.com/heilcheng/awesome-agent-skills

如果你不怕麻烦，还可以自己创建技能。其实也很简单，对话窗口中输入你的想法，最好是你工作时高频使用的工作流程，提交后等着大模型来给你完善和创建就好了。如果感觉在网页上使用不方便，还可以使用Trae、Cursor等IDE工具直接加载Skills。

用这个方法，你可以把平时积累的提示词或者在提示词市场中找到的提示词做成技能。如果技能需要动态执行脚本一定要写清楚，方便让大模型给你适配。

当然也可以把某个Github仓库直接制作成技能，相当一部分技能应该就是这样制作的，在执行技能时可以明显的看到技能在跑各种代码，等代码安装好以后再执行用户输入的需求。实话讲，这个安装的过程还是不短的。

所以我感觉Agent Skill最好还是用纯提示词加上简单的脚本来实现，不然就不如直接vibe coding去开发带UI界面的应用了，交互感更好一些。

当然，对于不懂代码的小白，这种方式倒是可以拉取一个Github项目了，间接实现了开源项目的在线或者本地化部署，哈哈，蛮有意思。

话说，我在POE平台创建了不少的画布应用，回头也试试把全部HTML代码贴过来做成技能，看看能不能跑起来。

关于skills的应用，最近我也看了一些教程。看完以后会有一种感觉，万物皆可Skill化。

其实Anthropic的相关文档已经讲过，对于非通用的硬性流程、需要确定性工具/代码辅助的场景以及长度太大不能一次性加载涉及多文档的上下文的场景，明确可以使用Skills。而对于角色扮演包装、一次性任务、以及没有流程的纯知识堆砌场景，是不建议滥用Skills的。

如果大家想详细了解Agent Skills，最好还是先看看Anthropic官方以及一些IDE工具商出的相关文档或者教程资源。这里贴几个资源地址：

• Athropic

  Claude Code

• https://code.claude.com/docs/en/skills

• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

• https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

• agentskills.io

  https://agentskills.io/home

• OpenAI

  Codex

  https://developers.openai.com/codex/skills/

• Visual Studio Code

  https://code.visualstudio.com/docs/copilot/customization/agent-skills

• Cursor

  https://cursor.com/docs/context/skills

• Cline

  https://docs.cline.bot/features/skills

• OpenCode

  https://opencode.ai/docs/skills/

• Gemini CLI

  https://geminicli.com/docs/cli/skills/

• Ampcode

  https://ampcode.com/manual#agent-skills

最近Anthropic还出了一篇高质量Skills创作最佳实践文章，旨在使Skills简洁、结构良好且易于被Claude发现和有效使用。核心原则强调高效利用上下文窗口，假设Claude具备基础智能，并根据任务的脆弱性调整指导的详细程度。

该文档强调通过多模型测试、文件系统式渐进式披露架构以及与Claude实例进行迭代开发，持续完善技能的有效性和鲁棒性。

这里也贴上原文，相信对大家高效使用Agent Skills会有所帮助。

省流版：

• 简洁与上下文窗口管理：编写技能时应简洁，避免不必要的解释，因为上下文窗口是共享资源。Claude仅在技能相关时按需加载SKILL.md及其他文件，确保SKILL.md保持在500行以下。

• 智能假设：默认假设Claude已经具备高度智能，只提供Claude缺乏的特定上下文信息。

• 指导详细程度匹配：根据任务的脆弱性和可变性（高自由度、中等自由度、低自由度）调整提供给Claude的指导具体程度。

• 多模型测试：在计划使用的所有Claude模型（Haiku、Sonnet、Opus）上测试技能，因为有效性会因模型而异，并确保说明适用于所有目标模型。

• 技能元数据：SKILL.md的YAML前置事项必须包含name（小写、数字、连字符，无保留字，最多64字符）和description（第三人称、具体、包含功能和使用时机，最多1024字符），这些对技能发现至关重要。

• 渐进式披露架构：将SKILL.md作为概述和导航目录，将详细内容（如指南、API参考、示例）拆分到单独的文件中，Claude仅在需要时按需加载这些文件，以优化令牌使用和上下文集中。

• 结构化工作流与验证：将复杂操作分解为清晰的顺序步骤，提供清单，并实施“运行验证器→修复错误→重复”的验证循环模式，以提高输出质量并防止跳过关键验证步骤。

• 避免过时信息与术语一致性：使用“旧模式”部分来处理可能过时的信息，并确保在整个技能描述和说明中使用一致的术语。

• 输出模板与示例：提供输出格式模板和输入/输出示例，帮助Claude更清楚地理解所需的输出风格和细节程度。

• 评估驱动开发：在大量编写文档之前，通过识别实际差距、创建测试场景和建立基线来构建评估，确保技能解决实际存在的问题。

• 与Claude迭代开发：利用两个Claude实例（一个作为设计和改进技能的“专家”Claude A，另一个作为使用技能执行真实任务的“代理”Claude B）进行迭代开发，根据观察到的Claude B行为持续改进技能。

• 可执行代码技能：对于包含可执行脚本的技能，应在脚本中明确处理错误、文档化配置参数，并优先使用预制脚本。需明确指示Claude是执行脚本还是将其作为参考读取，并推荐使用“计划-验证-执行”模式来处理复杂任务。

• 运行时环境考量：技能在具有文件系统访问和Bash命令的代码执行环境中运行。需注意claude.ai和Anthropic API之间的差异，所有文件路径应使用Unix风格的正斜杠，并为MCP工具使用完全限定的名称。

以下是原文。

【赠书福利见文末】

技能创作最佳实践Skill authoring best practices

学习如何编写有效的技能，使 Claude 能够发现和成功使用。

注：文中skills统一翻译为技能。

好的技能应该简洁、结构良好且经过真实使用测试。本指南提供实用的创作决策，帮助您编写 Claude 能够有效发现和使用的技能。

核心原则简洁是关键

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

• 系统提示

• 对话历史

• 其他技能的元数据

• 您的实际请求

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

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

只添加 Claude 没有的上下文。质疑每一条信息：

• "Claude 真的需要这个解释吗？"

• "我能假设 Claude 知道这个吗？"

• "这段落值得它的 token 成本吗？"

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

```

不好的例子：过于冗长（大约 150 个token）：

首先，您需要使用 pip 安装它。然后您可以使用下面的代码...

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

设置适当的自由度

将具体程度与任务的脆弱性和可变性相匹配。

高自由度（基于文本的说明）：

使用场景：

• 多种方法都有效

• 决策取决于上下文

• 启发式方法指导方法

示例：

4. 验证是否遵守项目约定

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

使用场景：

• 存在首选模式

• 某些变化是可以接受的

• 配置影响行为

示例：

```

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

使用场景：

• 操作脆弱且容易出错

• 一致性至关重要

• 必须遵循特定的序列

示例：

不要修改命令或添加其他标志。

类比：将 Claude 视为探索路径的机器人：

• 两侧都是悬崖的狭窄桥：只有一种安全的前进方式。提供具体的护栏和精确的说明（低自由度）。示例：必须按精确顺序运行的数据库迁移。
• 没有危险的开放田野：许多路径都能成功。给出一般方向并相信 Claude 会找到最佳路线（高自由度）。示例：上下文决定最佳方法的代码审查。

技能作为模型的附加功能，因此有效性取决于底层模型。使用您计划使用的所有模型测试您的技能。

按模型的测试考虑：

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

对 Opus 完美有效的东西可能需要为 Haiku 提供更多细节。如果您计划在多个模型中使用您的技能，请针对所有模型都能很好地工作的说明。

技能结构

**YAML 前置事项**：SKILL.md 前置事项需要两个字段：

name：

• 最多 64 个字符

• 只能包含小写字母、数字和连字符

• 不能包含 XML 标签

• 不能包含保留字："anthropic"、"claude"

description：

• 必须非空

• 最多 1024 个字符

• 不能包含 XML 标签

• 应描述技能的功能和使用时机

有关完整的技能结构详情，请参阅技能概述。

命名约定

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

请记住，name字段必须仅使用小写字母、数字和连字符。

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

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

可接受的替代方案：

• 名词短语：pdf-processing、spreadsheet-analysis

• 面向行动：process-pdfs、analyze-spreadsheets

避免：

• 模糊的名称：helper、utils、tools

• 过于通用：documents、data、files

• 保留字：anthropic-helper、claude-tools

• 技能集合中的不一致模式

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

• 在文档和对话中引用技能

• 一目了然地理解技能的功能

• 组织和搜索多个技能

• 维护专业、统一的技能库

description字段启用技能发现，应包括技能的功能和使用时机。

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

• 好的："处理 Excel 文件并生成报告"

• 避免："我可以帮助您处理 Excel 文件"

• 避免："您可以使用此功能处理 Excel 文件"

具体并包含关键术语。包括技能的功能和使用它的具体触发器/上下文。

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

有效的示例：

PDF 处理技能：

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

Excel 分析技能：

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

Git 提交助手技能：

description: 通过分析 git 差异生成描述性提交消息。当用户要求帮助编写提交消息或审查暂存更改时使用。

避免模糊的描述，如：

description: 帮助处理文档

description: 处理数据

description: 对文件进行各种操作

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

实用指导：

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

• 接近此限制时将内容拆分为单独的文件

• 使用下面的模式有效地组织说明、代码和资源

基本技能仅包含一个 SKILL.md 文件，其中包含元数据和说明：

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

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

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

模式 1：高级指南与参考

**示例**：参阅 [EXAMPLES.md](EXAMPLES.md) 获取常见模式

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

模式 2：特定领域组织

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

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

SKILL.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：条件详情

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

**对于 OOXML 详情**：参阅 [OOXML.md](OOXML.md)

Claude 仅在用户需要这些功能时读取 REDLINING.md 或 OOXML.md。

避免深层嵌套引用

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

保持引用距离 SKILL.md 一级。所有参考文件应直接从 SKILL.md 链接，以确保 Claude 在需要时读取完整文件。

不好的例子：太深：

这是实际信息...

好的例子：一级深：

**示例**：参阅 [examples.md](examples.md)

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

示例：

...

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

有关此基于文件系统的架构如何启用渐进式披露的详情，请参阅下面"高级"部分中的运行时环境部分。

工作流和反馈循环对复杂任务使用工作流

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

示例 1：研究综合工作流（适用于没有代码的技能）：

检查每个声明是否引用了正确的源文档。如果引用不完整，返回步骤 3。

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

示例 2：PDF 表单填充工作流（适用于有代码的技能）：

如果验证失败，返回步骤 2。

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

实现反馈循环

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

此模式大大提高输出质量。

示例 1：风格指南合规性（适用于没有代码的技能）：

5. 完成并保存文档

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

示例 2：文档编辑流程（适用于有代码的技能）：

6. 测试输出文档

验证循环可以及早捕获错误。

内容指南避免时间敏感信息

不要包含会过时的信息：

不好的例子：时间敏感（会变成错误）：

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

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

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

使用一致的术语

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

好的 - 一致：

• 始终"API 端点"

• 始终"字段"

• 始终"提取"

不好的 - 不一致：

• 混合"API 端点"、"URL"、"API 路由"、"路径"

• 混合"字段"、"框"、"元素"、"控件"

• 混合"提取"、"拉取"、"获取"、"检索"

一致性帮助 Claude 理解和遵循说明。

常见模式模板模式

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

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

```

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

根据特定分析类型根据需要调整部分。

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

遵循此风格：type(scope): 简短描述，然后详细说明。

示例帮助 Claude 比单独的描述更清楚地理解所需的风格和细节程度。

条件工作流模式

通过决策点指导 Claude：

   - 完成时重新打包

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

评估和迭代首先构建评估

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

评估驱动的开发：

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

此方法确保您解决实际问题，而不是预期可能永远不会出现的要求。

评估结构：

}

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

与 Claude 一起迭代开发技能

最有效的技能开发流程涉及 Claude 本身。与一个 Claude 实例（"Claude A"）合作创建将由其他实例（"Claude B"）使用的技能。Claude A 帮助您设计和改进说明，而 Claude B 在真实任务中测试它们。这之所以有效，是因为 Claude 模型既理解如何编写有效的代理说明，也理解代理需要什么信息。

创建新技能：

1. 在没有技能的情况下完成任务：与 Claude A 一起使用常规提示来解决问题。在您工作时，您自然会提供上下文、解释偏好并分享程序知识。注意您重复提供的信息。

2. 识别可重用模式：完成任务后，识别您提供的对类似未来任务有用的上下文。

   示例：如果您完成了 BigQuery 分析，您可能提供了表名、字段定义、过滤规则（如"始终排除测试账户"）和常见查询模式。

3. 要求 Claude A 创建技能："创建一个技能来捕获我们刚刚使用的 BigQuery 分析模式。包括表架构、命名约定和关于过滤测试账户的规则。"

Claude 模型本身理解技能格式和结构。您不需要特殊的系统提示或"编写技能"技能来让 Claude 帮助创建技能。只需要求 Claude 创建技能，它就会生成具有适当前置事项和正文内容的正确结构化 SKILL.md。

4. 审查简洁性：检查 Claude A 是否没有添加不必要的解释。问："删除关于赢率意义的解释 - Claude 已经知道这个。"

5. 改进信息架构：要求 Claude A 更有效地组织内容。例如："组织这个，使表架构在单独的参考文件中。我们稍后可能会添加更多表。"

6. 在类似任务上测试：使用技能与 Claude B（一个加载了技能的新实例）进行相关用例。观察 Claude B 是否找到正确的信息、正确应用规则并成功处理任务。

7. 根据观察迭代：如果 Claude B 遇到困难或遗漏了什么，返回 Claude A 并提供具体信息："当 Claude 使用此技能时，它忘记了为 Q4 按日期过滤。我们应该添加关于日期过滤模式的部分吗？"

迭代现有技能：

当改进技能时，相同的分层模式继续。您在以下之间交替：

• 与 Claude A 合作（帮助改进技能的专家）

• 与 Claude B 测试（使用技能执行真实工作的agent）

• 观察 Claude B 的行为并将见解带回 Claude A

1. 在真实工作流中使用技能：给 Claude B（加载了技能）实际任务，而不是测试场景。

2. 观察 Claude B 的行为：注意它在哪里遇到困难、成功或做出意外选择。

   示例观察："当我要求 Claude B 生成区域销售报告时，它编写了查询但忘记了过滤测试账户，即使技能提到了此规则。"

3. 返回 Claude A 进行改进：分享当前的 SKILL.md 并描述您观察到的内容。问："我注意到 Claude B 在要求区域报告时忘记了过滤测试账户。技能提到了过滤，但也许还不够突出？"

4. 审查 Claude A 的建议：Claude A 可能建议重新组织以使规则更突出、使用更强的语言如"必须过滤"而不是"始终过滤"，或重构工作流部分。

5. 应用并测试更改：使用 Claude A 的改进更新技能，然后在类似请求上再次与 Claude B 测试。

6. 根据使用情况重复：当您遇到新场景时继续观察-改进-测试循环。每次迭代都根据真实代理行为而不是假设改进技能。

收集团队反馈：

1. 与队友分享技能并观察他们的使用。

2. 问："技能在预期时激活吗？说明清楚吗？缺少什么？"

3. 合并反馈以解决您自己使用模式中的盲点。

为什么此方法有效：Claude A 理解代理需求，您提供领域专业知识，Claude B 通过真实使用揭示差距，迭代改进根据观察到的行为而不是假设改进技能。

观察 Claude 如何导航技能

当您迭代技能时，注意 Claude 实际上如何在实践中使用它们。观察：

• 意外的探索路径：Claude 是否以您没有预期的顺序读取文件？这可能表明您的结构不如您认为的那样直观。

• 错过的连接：Claude 是否未能遵循对重要文件的引用？您的链接可能需要更明确或突出。

• 对某些部分的过度依赖：如果 Claude 反复读取同一文件，考虑该内容是否应该在主 SKILL.md 中。

• 忽略的内容：如果 Claude 从不访问捆绑文件，它可能是不必要的或在主说明中信号不良。

根据这些观察而不是假设进行迭代。您的技能元数据中的"name"和"description"特别关键。Claude 在决定是否响应当前任务触发技能时使用这些。确保它们清楚地描述技能的功能和使用时机。

要避免的反模式避免 Windows 风格的路径

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

• ✓好的：scripts/helper.py、reference/guide.md

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

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

避免提供太多选项

除非必要，否则不要呈现多种方法：

对于需要 OCR 的扫描 PDF，改用 pdf2image 与 pytesseract。"

下面的部分重点关注包含可执行脚本的技能。如果您的技能仅使用 markdown 说明，请跳到有效技能清单。

解决，不要推卸

编写技能脚本时，处理错误条件而不是推卸给 Claude。

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

        return ''

不好的例子：推卸给 Claude：

    return open(path).read()

配置参数也应该被证明和记录，以避免"巫毒常数"（Ousterhout 定律）。如果您不知道正确的值，Claude 如何确定它？

好的例子：自文档化：

MAX_RETRIES = 3

不好的例子：魔法数字：

RETRIES = 5   # 为什么是 5？

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

实用脚本的优势：

• 比生成的代码更可靠

• 节省 token （无需在上下文中包含代码）

• 节省时间（无需代码生成）

• 确保跨使用的一致性

上面的图表显示了可执行脚本如何与说明文件一起工作。说明文件（forms.md）引用脚本，Claude 可以执行它而无需将其内容加载到上下文中。

重要区别：在您的说明中明确说明 Claude 是否应该：

• 执行脚本（最常见）："运行 analyze_form.py来提取字段"
• 作为参考读取（对于复杂逻辑）："参阅 analyze_form.py了解字段提取算法"

对于大多数实用脚本，执行是首选，因为它更可靠和高效。有关脚本执行如何工作的详情，请参阅下面的运行时环境部分。

示例：

```

当输入可以呈现为图像时，让 Claude 分析它们：

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 修复问题。

打包依赖项

技能在代码执行环境中运行，具有特定于平台的限制：

• claude.ai：可以从 npm 和 PyPI 安装包并从 GitHub 存储库拉取。

• Anthropic API：没有网络访问权限，没有运行时包安装。

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

运行时环境

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

这如何影响您的创作：

Claude 如何访问技能：

1.元数据预加载：启动时，所有技能 YAML 前置事项中的名称和描述被加载到系统提示中。
2.按需读取文件：Claude 在需要时使用 bash 读取工具从文件系统访问 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 可以导航并有选择地加载每个任务所需的内容。

有关技术架构的完整详情，请参阅技能概述中的技能如何工作。

MCP 工具参考

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

格式：ServerName:tool_name

示例：

使用 GitHub:create_issue 工具创建问题。

其中：

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

没有服务器前缀，Claude 可能无法定位工具，特别是当有多个 MCP 服务器可用时。

避免假设工具已安装

不要假设包可用：

```"

SKILL.md 前置事项需要name和description字段，具有特定的验证规则：

• name：最多64个字符，仅小写字母/数字/连字符，无 XML 标签，无保留字。

• description：最多1024个字符，非空，无 XML 标签。

有关完整的结构详情，请参阅技能概述。

Token预算

保持 SKILL.md 正文在500行以下以获得最佳性能。如果您的内容超过此限制，使用前面描述的渐进式披露模式将其拆分为单独的文件。有关架构详情，请参阅技能概述。

有效技能清单

在分享技能之前，验证：

核心质量

• 描述具体并包含关键术语

• 描述包括技能的功能和使用时机

• SKILL.md 正文在 500 行以下

• 其他详情在单独的文件中（如果需要）

• 没有时间敏感信息（或在"旧模式"部分中）

• 整个技能中术语一致

• 示例具体，不抽象

• 文件引用一级深

• 适当使用渐进式披露

• 工作流有清晰的步骤

• 脚本解决问题而不是推卸给 Claude

• 错误处理明确且有帮助

• 没有"巫毒常数"（所有值都有理由）

• 所需的包在说明中列出并验证为可用

• 脚本有清晰的文档

• 没有 Windows 风格的路径（所有正斜杠）

• 关键操作的验证/验证步骤

• 包含质量关键任务的反馈循环

• 至少创建了三个评估

• 使用 Haiku、Sonnet 和 Opus 进行了测试

• 使用真实使用场景进行了测试

• 合并了团队反馈（如果适用）

技能概述：

https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/overview

-structure

上下文窗口：

https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows

运行时环境：

https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/best-practices

-environment

代码执行工具文档：

https://platform.claude.com/docs/zh-CN/agents-and-tools/tool-use/code-execution-tool

技能创作最佳实践：

https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/best-practices

全文完

看到这里，如果觉得不错，随手点个赞、在看或者转发吧，也可以给个星标，你的支持就是我的动力。

王吉伟频道新书《一本书读懂AI Agent：技术、应用与商业》已出版，轻松读懂系统掌握AI Agent技术原理、行业应用、商业价值及创业机会，欢迎大家关注。

感谢大家长期关注与支持，小伙伴们随意留言，王吉伟频道会随机选取留言用户，《一本书读懂AI Agent：技术、应用与商业》包邮到家。

【文末福利1】：后台发消息研报2026，获取15篇2026年AI Agent研报。

【文末福利2】： 后台发消息Workflow，获取 Agentic Workflow 相关25篇论文。

【文末福利3】：后 台发消息agentic，获取Agentic AI相关资源 。

【文末福利4】：后台发消息RPA Agent，获取 相关论文和研报。

1、

2、

3、

4、

5、

6、

7、

8、

8、

10、

• 期待点赞、在看、评论、转发，您的支持就是我的动力。

• 鼓励积极评论，您的留言可以成为选题。

• 欢迎阅读其他文章，或会激发您的更多思考。

点击左下角“阅读原文”查看AIGC研究系列文章，扫码或者后台回复【加群】申请加入AIGC行业应用交流社群。如果你是正在关注AI Agent的创业者、投资人及企业，欢迎带着产品、项目及需求与王吉伟频道交流。

【王吉伟频道，关注AIGC与IoT，专注数字化转型、业务流程自动化与AI Agent。公号ID：jiwei1122，欢迎关注与交流。】