> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 代理技能开发详细指南
- URL: https://www.hubwiz.com/blog/a-detailed-guide-to-building-agent-skills/
- Published: 2026-02-02T13:52:14.000Z
- Updated: 2026-02-02T13:52:14.000Z
- Description: 通过精心制作的技能将您的编码代理 OpenCode、Claude Code、Codex 和更多从通用 AI 转变为领域专家，将您的专业知识打包成可发现、自主的能力。 为什么技能很重要
- Author: admin
- Tags: AGENT, AGENT SKILLS, #Import 2026-10-14 14:41

您是否曾希望能够教您的编码代理团队的特定工作流程？或者给它关于公司工具和流程的即时专业知识？这正是 **Claude Code Skills** 所做的。

现在，不仅是 [Claude Code](https://code.claude.com/docs/en/skills?ref=hubwiz.com)，还有 [Codex](https://developers.openai.com/codex/skills?ref=hubwiz.com)、[Github Copilot](https://github.blog/changelog/2025-12-18-github-copilot-now-supports-agent-skills/?ref=hubwiz.com) 和 [OpenCode](https://opencode.ai/docs/skills/?ref=hubwiz.com) 都宣布支持 [Agentic Skills](https://agentskills.io/home?ref=hubwiz.com)。甚至还有一个 [Agent 技能市场](https://skillzwave.ai/?ref=hubwiz.com)，通过通用安装器支持 Gemini、Aidr、Qwen Code、Kimi K2 Code、Cursor（14+ 个，还在增加）以及更多具有 Agent 技能支持的工具。在本指南中，我将交替使用 Claude 和编码代理这个词，就像有人可能会说"帮我复印这份文件"而不是"帮我复制这份文件"。（在我的工作流程中，我倾向于使用 Claude Code、OpenCode 和 Gemini CLI。）

将技能视为优秀新员工的入职文档。它们包含 Claude 需要像资深团队成员一样工作的程序性知识和组织上下文。区别是什么？技能是模块化的、可发现的，并且仅在需要时加载，保持 Claude 的上下文窗口专注于重要内容。

本指南向您展示如何编写 Claude 可以成功发现和使用的技能。您将从核心原则学习到高级模式，所有这些都来自 Anthropic 的官方最佳实践。

到本指南结束时，您将知道如何：

- **编写简洁、有效的技能**，尊重上下文窗口
- **使用经过验证的命名和组织模式构建技能**
- **应用渐进式披露**来管理复杂性，而不让 Claude 感到不知所措
- **设计工作流程**，为质量关键任务包含反馈循环
- **使用评估驱动的开发进行测试和迭代**
- **打包可执行代码**，解决问题而不是创建问题

准备好让 Claude 成为团队的秘密武器了吗？让我们从技能的实际工作原理开始。

## 1、了解技能如何工作

在编写您的第一个技能之前，您需要了解 Claude 的三级加载系统。这个架构是技能力量的秘密。它保持您的上下文窗口精简，同时让 Claude 能够访问大量专业知识。

### 1.1 渐进式披露架构

技能不会一次性将所有内容都倒入 Claude 的上下文中。相反，它们使用巧妙的三阶段加载系统。这个巧妙的加载系统允许 Claude Code 使用 Agent 搜索。

![](https://www.hubwiz.com/blog/content/images/2026/02/image-22.png)

显示渐进式披露三个层的图表：元数据、技能指令和参考文件

### 1.2 Agent 技能加载的两个阶段

渐进式披露架构在两个不同的阶段中运行：

**阶段 1：发现（始终激活）**

启动时，Claude 仅从所有可用技能中加载元数据。这包括 YAML 前置内容中的 `name` 和 `description`。这个轻量级索引（每个技能约 50-100 个 token）允许 Claude 快速扫描和识别相关技能，而不会消耗大量上下文。

**阶段 2：深度加载（按需）**

当用户请求与技能的描述匹配时，Claude 加载完整的 `SKILL.md` 内容和任何其他引用的文件。这是渐进发生的——Claude 仅在需要时读取文件，保持上下文窗口专注于相关信息。

这种两阶段方法使技能可扩展。您可以拥有几十个可用技能，而不会使上下文窗口膨胀，因为只有相关的技能在需要时才会完全加载。

**阶段 1：启动** — 只有元数据（名称和描述）加载到系统提示中。这意味着您可以拥有几十个可用技能，而不会消耗上下文 token。

![](https://www.hubwiz.com/blog/content/images/2026/02/image-23.png)

**阶段 2–3**：按需加载 — 当用户请求匹配时，更深层级会渐进式加载。只有第 1 级（元数据）始终被加载。其他所有内容？在 Claude 需要之前为零 token。

![](https://www.hubwiz.com/blog/content/images/2026/02/image-24.png)

这意味着您可以将大量专业知识捆绑到一个技能中，包括 API 参考、详细示例和整个脚本，而不会使 Claude 的上下文膨胀。当 Claude 探索您的技能结构时，系统会按需加载文件。

\*\*关键见解：\*\*您可以包含的上下文量实际上是无限的。只有当 Claude 实际读取文件时，文件才会消耗 token。

## 2、三种类型的技能：个人、项目和插件

您放置技能的位置决定了它的范围和共享模型：

![](https://www.hubwiz.com/blog/content/images/2026/02/image-25.png)

**个人技能**（`~/.claude/skills/`、`~/.codex/skills`、`~/.config/opencode/skill`）是您的私人工具包。它们非常适合您独有的工作流程或您正在测试的实验性技能。

**项目技能**（`.claude/skills/`、`.codex/skills`、`.opencode/skill`、`.github/copilot/skills`）被检入 git 并与您的团队共享。这些捕获每个人都受益的组织知识。

**插件技能**随 MCP 插件一起提供，提供在您启用插件时激活的特定工具专业知识。

Claude Code 和 OpenAI Codex 还支持在项目目录上方的目录中拥有项目级技能。Codex 还提供了几个更多的地方来安装技能以供企业级使用。

无论类型如何，所有技能都遵循相同的核心结构：一个带有可选支持材料的 `SKILL.md` 文件。加载架构保持不变。

以下内容基于 [Anthropic 的创建技能最佳实践指南](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices?ref=hubwiz.com)，我强烈建议您查看。

我非常喜欢 Anthropic 的最佳实践指南，以至于我创建了一个技能来评估和改进我的技能。

只是为了向您展示我最初的评分：

![](https://www.hubwiz.com/blog/content/images/2026/02/image-26.png)

然后在使用指南并修复我的技能之后：

![](https://www.hubwiz.com/blog/content/images/2026/02/image-27.png)

让我们来看看指南中的一些关键思想。

## 3、核心原则

### 3.1 简洁为王

这里有一个令人不安的真相：您的技能正在为编码代理上下文窗口中的空间而战。您添加的每个 token 都与系统提示、对话历史、其他技能的元数据、项目特定指令和用户的实际请求竞争。

**黄金法则：** 假设您的编码代理已经非常聪明。只添加您的编码代理没有的上下文。

在写一段话之前，问问自己：我的编码代理真的需要这个解释吗？我可以假设编码代理已经知道这个了吗？这一段话是否证明了其 50-100 个 token 成本的合理性？

> 比较这些示例：

好的说明（50 个 token）：

```
## 提取 PDF 文本
使用 pdfplumber 进行文本提取：

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

```

简洁的版本直奔主题。它假设 Claude 知道 PDF 是什么，理解库，并且可以弄清楚如何安装。相信 Claude 的智能。与这个版本相比：

坏的说明（150 个 token）：

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

```

简洁的版本直奔主题。它假设您的编码代理（Claude Code、OpenCode、GitHub Copilot 等）知道 PDF 是什么，理解库，并且可以弄清楚如何安装。**相信您的编码代理的智能。**

### 3.2 设置适当的自由度

并非所有任务都需要相同级别的规定。关键问题是：这个操作有多脆弱？

将您的指令具体性与任务的容错性相匹配：

- **低自由度** — 对于必须遵循确切序列的脆弱、容易出错的操作。使用特定脚本，很少/没有参数，确切的命令。示例：数据库迁移。
- **中等自由度** — 对于具有首选模式但可以接受一些变化的任务。使用伪代码或带有可配置参数的模板。示例：报告生成。
- **高自由度** — 对于存在多种有效方法的任务。使用基于文本的指令和启发式方法来指导方法。示例：代码审查。

就像过桥一样想：两侧都有悬崖的狭窄桥梁需要特定的护栏（低自由度）。没有危险的宽阔开阔田野允许多条成功路径（高自由度）。穿过树林的标记路径：存在首选路径，但绕道不会造成问题；这提供模板但允许自定义（中等自由度）。

数据库迁移？用确切的脚本锁定它。代码审查？给您的编码代理思考空间。报告生成？提供模板但让您的编码代理适应数据。

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

与 Opus 或 Gemini 3 Pro 完美配合的技能可能会让 Haiku 或 Gemini Flash Light 感到困惑。不同的模型具有不同的推理能力。跨模型测试以找到最佳点。您的技能应该足够简洁以适合 Opus 用户，但对于 Haiku 用户来说足够详细。如果您针对更高的思维模型，如 Opus 或 Gemini 3 Pro，只需说明即可。如果您计划与 Haiku 一起使用技能，您应该用 Haiku 测试它。

## 4、技能结构

### 4.1 YAML 前置内容：发现机制

每个 SKILL.md 文件都以包含两个必需字段的 YAML 前置内容开头：name 和 description。这个元数据总是被加载（渐进式披露系统中的第 1 级）。这是您的编码代理发现哪些技能与用户请求相关的方式。

```
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

```

字段要求：

- name：最多 64 个字符，仅小写字母/数字/连字符，没有保留词（如 "anthropic" 或 "claude"）
- description：最多 1024 个字符，非空，描述技能做什么以及何时使用

### 4.2 命名约定：使用动名词形式

使用动名词形式（动词 + -ing）以保持清晰和一致：processing-pdfs、analyzing-spreadsheets、managing-databases、testing-code、generating-reports。您会看到很多旧技能，包括 Anthropic 的原始技能都不使用这种形式，但现在在 Anthropic [发布了最佳实践指南](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices?ref=hubwiz.com) 之后，它们开始采用它。如果您认真对待技能开发，您应该阅读此指南。我们也在本文中介绍了一些最佳实践。

避免像 "helper" 或 "utils" 这样的模糊名称，像 "documents" 或 "files" 这样的通用名称，以及像 "pdf" 这样的歧义名称。

使用**动名词形式**（动词 + -ing）以保持清晰和一致：

**推荐：**

- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `generating-reports`

### 4.3 编写启用发现的描述

描述是您技能的电梯演讲。您的编码代理阅读它以决定此技能是否与用户的请求匹配。

神奇公式：描述技能做什么以及何时使用它。始终使用第三人称编写，因为描述直接注入到系统提示中。

![](https://www.hubwiz.com/blog/content/images/2026/02/image-28.png)

好的示例："从 PDF 文件中提取文本和表格，填充表单，合并文档。在使用 PDF 文件或当用户提及 PDF、表单或文档提取时使用。"

糟糕的示例："帮助处理文档"；这太模糊了，没有何时使用它的上下文。

**很好的示例：**

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

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

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

```

**糟糕的示例：**

```
description: Helps with documents  # 太模糊 - 什么样的帮助？
description: Processes data        # 没有何时使用的上下文
description: Does stuff with files # 完全没有帮助

```

### 4.4 目录结构：一层深

技能通过智能组织进行扩展。最好的技能不会将所有内容都倾倒到单个文件中。它们创建**导航结构**，让您的编码代理在需要时准确找到需要的内容。

将您的技能视为参考库。主 `SKILL.md` 文件是接待台。它提供方向并指向正确的部分。支持文件是详细信息所在的专门阅读室。

关键原则：**保持一层深**。Claude 应该永远不需要从 `SKILL.md` 跟随超过一个链接才能到达实际内容。这防止了导航开销并确保快速、可靠地访问信息。

保持您的技能文件结构扁平和可导航：

![](https://www.hubwiz.com/blog/content/images/2026/02/image-29.png)

**黄金法则**：保持引用从 `SKILL.md` 起**一层深**。

为什么？编码代理通过跟随链接导航技能。深度嵌套（`SKILL.md` 到 `advanced.md` 到 `details.md` 到实际信息）会产生导航开销，并可能导致您的编码代理部分读取文件或完全错过内容。

**好的结构：**

```
my-skill/
├── SKILL.md          # 主入口点
├── reference/
│   ├── api.md        # 详细的 API 文档（从 SKILL.md 链接）
│   └── examples.md   # 使用示例（从 SKILL.md 链接）
└── scripts/
    ├── analyze.py    # 实用脚本
    └── validate.py   # 验证脚本

```

**糟糕的结构：**

您说得对！"糟糕的结构"示例应该更好地说明深度嵌套引用的反模式。这是一个改进版本，展示了有问题的链：

```
my-skill/
├── SKILL.md                    # 链接到 advanced.md
└── reference/
    └── advanced.md             # 链接到 details.md
        └── deep/
            └── details.md      # 链接到 actual-content.md
                └── nested/
                    └── actual-content.md  # 终于，信息！

```

这清楚地显示了多跳导航问题：[SKILL.md](http://skill.md/?ref=hubwiz.com) → [advanced.md](http://advanced.md/?ref=hubwiz.com) → [details.md](http://details.md/?ref=hubwiz.com) → [actual-content.md](http://actual-content.md/?ref=hubwiz.com)，这正是指南警告的模式。

## 5、渐进式披露模式

渐进式披露是仅在需要时揭示信息的艺术。您的 `SKILL.md` 充当地图，根据任务需要指向 Claude 详细材料。

### 5.1 模式 1：高级指南与参考

最常见的模式：在 `SKILL.md` 中提供快速入门，然后为高级场景链接到详细参考。

```
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files.
---

# PDF 处理

## 快速入门

使用 pdfplumber 提取文本：
```
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) 获取常见模式

```

**为什么这有效：**您的编码代理立即加载 `SKILL.md`（200-500 个 token）。如果用户只需要基本的文本提取，快速入门就足够了。如果他们需要表单填充，编码代理会按需读取 `FORMS.md`。

**结果**：您通过不为简单的文本提取任务加载表单填充文档，可能节省了数千个 token。

### 5.2 模式 2：领域特定组织

对于涵盖多个领域的技能，按主题组织文件以避免加载不相关的上下文：

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

```

[**SKILL.md**](http://skill.md/?ref=hubwiz.com) **导航部分：**

```
## 领域指南

**财务指标**：[finance.md](reference/finance.md) -
收入、计费、订阅
**销售数据**：[sales.md](reference/sales.md) -
机会、管道、预测
**产品分析**：[product.md](reference/product.md) -
使用、功能、采用
**营销活动**：[marketing.md](reference/marketing.md) -
归因、ROI

```

当用户询问"显示本季度的销售管道"时，编码代理只加载 `sales.md`。财务、产品和营销文档保持未加载状态，为实际分析节省 token。

### 5.3 模式 3：长文件的目录

如果参考文件超过 100 行，添加目录以帮助 Claude 导航：

```
# API 参考

## 目录
- [身份验证和设置](#authentication-and-setup)
- [核心方法](#core-methods) - 创建、读取、更新、删除
- [高级功能](#advanced-features) - 批量操作、webhook
- [错误处理](#error-handling) - 模式和恢复
- [代码示例](#code-examples)

## 身份验证和设置
...

## 核心方法
...

```

**为什么这有帮助：**您的编码代理可以扫描目录并直接跳转到相关部分，而不是线性地读取整个文件。这是 Agent 搜索的基础，它允许您的编码代理使用 GLOB 和 GREP 等工具快速导航文件，而不是读取其全部内容；从而节省宝贵的上下文窗口资源。

### 5.4 反模式：深度嵌套引用

避免创建多级导航链：

**糟糕的：**

```
# SKILL.md
查看 [advanced.md](advanced.md) 了解更多...

# advanced.md
查看 [details.md](details.md) 了解具体细节...
# details.md
终于，实际信息！

```

**问题**：Claude 在跟随链时可能会部分读取文件，消耗 token 而没有到达实际内容。更糟糕的是，深度嵌套可能导致 Claude 完全错过重要信息。

**好的：**

```
# SKILL.md
- **基本用法**：[下面的快速示例]
- **高级功能**：查看 [advanced.md](advanced.md)
- **API 参考**：查看 [reference.md](reference.md)
- **故障排除**：查看 [troubleshooting.md](troubleshooting.md)

```

所有重要文件距离 `SKILL.md` 一跳。

## 6、工作流程和反馈循环

> 工作流程：将复杂任务分解为步骤

复杂操作需要结构。使用清晰、顺序的工作流程和检查清单来指导 Claude 完成多步骤过程：

```
## PDF 表单填充工作流程

复制此检查清单并在完成项目时勾选：

```markdown
任务进度：
[ ]  步骤 1：分析表单（运行 analyze_form.py）
[ ]  步骤 2：创建字段映射（编辑 fields.json）
[ ]  步骤 3：验证映射（运行 validate_fields.py）
[ ]  步骤 4：填充表单（运行 fill_form.py）
[ ]  步骤 5：验证输出（运行 verify_output.py）
```

**步骤 1：分析表单**

运行分析脚本：
```bash
python scripts/analyze_form.py input.pdf
```

这会提取所有表单字段及其位置，输出到 `fields.json`。

**步骤 2：创建字段映射**

编辑 `fields.json` 为每个字段添加值。示例：

```json
{ "customer_name": "John Doe", "order_total": "1234.56" }
```

**步骤 3：验证映射**

在填充之前，验证映射是否正确：

**步骤 3：验证映射**

在填充之前，验证映射是否正确：
```bash
python scripts/validate_fields.py fields.json
```

在继续之前修复任何报告的错误。

...

```

**为什么检查清单有效：** 它们在用户和 Claude 之间创建共享状态。用户可以看到进度，Claude 可以跟踪完成情况，如果被打断，两者都可以恢复。

## 7、反馈循环：验证-修复-重复模式

对于质量关键操作，**没有验证绝不继续**。验证-修复-重复模式显著提高输出质量：

![](https://www.hubwiz.com/blog/content/images/2026/02/image-30.png)

此图说明了反馈循环工作流程，这是质量关键操作的关键模式。工作流程显示了如何迭代地验证工作，而不是等到最后：

![](https://www.hubwiz.com/blog/content/images/2026/02/image-31.png)

反馈循环更成功

**流程：**

1. **开始任务** → 开始操作
- **步骤 1：执行操作** → 执行初始工作（例如，编辑 XML，生成代码，修改数据）
- **步骤 2：验证** → 立即检查输出是否正确
- **决策点** → 验证是否成功？
- **如果否（❌）** → 进入步骤 3：修复问题，然后返回验证
- **如果是（✅）** → 进入整体工作流程的下一步

**关键原则：** 验证 → 检查 → 修复 → 验证之间的循环持续直到验证通过。这防止使用损坏或不正确的工作继续。

**为什么此模式有效：**

- **立即捕获错误**，当上下文新鲜时修复更容易
- **防止级联故障**，确保每个步骤在继续之前都是正确的
- **显著减少调试时间**，与"最后修复所有内容"的方法相比
- **建立信心**，最终输出将是正确的

图表使用颜色编码来区分操作步骤（蓝色）、验证步骤（橙色）、决策点（金色）和修复步骤（粉色），使工作流程一目了然。

**示例实现：**

```
## 文档编辑流程

1. 对 `word/document.xml` 进行编辑
2. **立即验证**：
```bash
python scripts/validate.py unpacked_dir/
```
3. **如果验证失败**：
- 仔细查看错误消息
- 修复 XML 中的问题
- 再次运行验证
- **在验证通过之前不要继续**
4. 重建文档：
```bash
python scripts/pack.py unpacked_dir/ output.docx
```
```

**为什么这有效：** 在进行更改后立即捕获错误比在最后调试损坏文件要容易得多。验证提供即时反馈，将脆弱的过程转变为可靠的过程。

**真实世界影响：** 与"先编辑所有内容然后检查"的方法相比，使用反馈循环的团队报告的损坏输出减少了 70-90%。

## 8、常见模式

### 8.1 模板模式：提供输出结构

当输出格式很重要时，提供显示预期结构的模板。

**对于严格要求（低自由度）：**

```
## 文档修改流程

### 步骤 1：确定修改类型

问问自己：我是在创建新内容还是编辑现有内容？

**创建新内容？** 遵循创建工作流程
**编辑现有内容？** 遵循编辑工作流程

---

### 创建工作流程

从头开始构建文档时：

1. 使用 `docx-js` 库
2. 以编程方式构建文档
3. 以正确的顺序添加内容（样式优先，然后是内容）

示例：

```python
from docx import Document 
doc = Document() 
doc.add_heading('Report Title', 0) 
doc.add_paragraph('First paragraph') 
doc.save('report.docx')
```

---

### 编辑工作流程

修改现有文档时：

1. 将现有文档解压到目录
2. 直接修改 XML 文件
3. **每次更改后验证**使用 `validate.py`
4. 仅在验证通过时重新打包

```bash
python scripts/unpack.py document.docx unpacked/
# 对 unpacked/word/document.xml 进行编辑
python scripts/validate.py unpacked/ 
python scripts/pack.py unpacked/ modified.docx
```
```

"ALWAYS" 一词表示这是强制性的，而非可选的

对于灵活的指导（高自由度）：

```
## 报告结构

这是一个合理的默认格式，但根据您的发现进行调整：

```markdown
# [分析标题]

## 概述
[上下文和范围]

## 分析
[根据发现调整部分]

## 结论
[关键要点]
```

根据数据自然调整部分。

```

"根据...调整"这一短语表示灵活性。

### 8.2 示例模式：输入/输出对

对于质量很重要的任务，显示正确输出的具体示例：

```
## 提交消息格式

**示例 1：新功能**

输入：添加了具有 JWT 令牌的用户身份验证
输出：
```
feat(auth): 实现基于 JWT 的身份验证
添加具有令牌生成和验证中间件的登录端点。 包括令牌刷新逻辑和安全存储。

**示例 2：错误修复**

输入：修复了日期显示不正确的错误
输出：
```
fix(reports): 更正时区转换中的日期格式
```
在报告生成中一致地使用 UTC 时间戳。 以前使用本地时间，这会导致不同时区的用户出现差异。
```

为什么示例有效：它们向 Claude 展示了预期的质量水平和风格，而不需要规定性规则。Claude 从示例中学习模式。

### 8.3 条件工作流程模式：决策点

在存在多个路径时指导 Claude 穿过决策树：

```
## 文档修改流程

### 步骤 1：确定修改类型

问问自己：我是在创建新内容还是编辑现有内容？

**创建新内容？** 遵循创建工作流程
**编辑现有内容？** 遵循编辑工作流程

---

### 创建工作流程

从头开始构建文档时：

1. 使用 `docx-js` 库
2. 以编程方式构建文档
3. 以正确的顺序添加内容（样式优先，然后是内容）

示例：
```python
from docx import Document 
doc = Document() 
doc.add_heading('Report Title', 0) doc.add_paragraph('First paragraph') doc.save('report.docx')
```

---

### 编辑工作流程

修改现有文档时：

1. 将现有文档解压到目录
2. 直接修改 XML 文件
3. **每次更改后验证**使用 `validate.py`
4. 仅在验证通过时重新打包
```python
python scripts/unpack.py document.docx unpacked/
# 对 unpacked/word/document.xml 进行编辑
python scripts/validate.py unpacked/ 
python scripts/pack.py unpacked/ modified.docx
```
```

清晰的决策点（"我是创建还是编辑？"）帮助 Claude 选择正确的路径。

## 9、评估和迭代

### 8.1 从评估开始，而不是文档

这里有一个可以为您节省数小时的秘密：**在编写大量文档之前构建评估。**

为什么？因为评估揭示了 Claude 挣扎的地方，指导您只编写重要的文档。

![](https://www.hubwiz.com/blog/content/images/2026/02/image-32.png)

**评估驱动的工作流程：**

1. **识别差距**：在没有技能的情况下让 Claude 处理真实任务。注意它在哪里挣扎、犯错或请求指导。
- **创建评估**：构建 3-5 个捕获这些失败模式的测试场景。每个场景应该测试特定能力。
- **编写最小技能**：创建一个简洁的 `SKILL.md`，针对记录的失败。抵制过度解释的冲动。
- **测试和迭代**：运行您的评估。如果失败，完善技能。如果通过，您就完成了。

评估结构示例：

```
{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF and save to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file",
    "Extracts text from all pages (not just the first page)",
    "Saves to output.txt in readable UTF-8 format",
    "Handles multi-column layouts correctly"
  ]
}

```

**为什么这有效：** 评估为您提供客观的通过/失败标准。不再猜测您的技能是否"足够好"。要么通过测试，要么不通过。

## 10、用 Claude 迭代开发技能

想知道创建技能的最快方法吗？**用Claude 构建它。**

以下是过程：

1. **手动完成任务**：用 Claude 完成一项任务，提供所有必要的上下文和指导。
2. **观察您反复解释的内容**：记录您在类似任务中多次提供的信息。
3. **要求 Claude 创建技能**："创建一个捕获我们刚刚用于 \[任务\] 的模式的技能。专注于 \[特定方面\]。"
4. **审查简洁性**：Claude 的第一稿通常会过度解释。无情地删减，相信 Claude 的基础知识。
5. **在新实例上测试**：打开一个新的 Claude 对话（以清除上下文）并在类似任务上测试技能。
6. **根据观察进行迭代**：观察 Claude 在哪里挣扎或犯错，然后完善技能以解决这些特定问题。

**真实示例：** 一位开发人员在构建 BigQuery 技能时与 Claude 一起完成了 5 个财务查询，然后说："创建一个捕获我们财务指标查询方法的技能。"Claude 生成了初始技能，开发人员将其修剪到原始长度的 40%，在新查询上进行了测试，并且在不到一小时内拥有了生产就绪的技能。

## 11、观察 Claude 如何实用您的技能

一旦您有了技能，观察 Claude 如何使用它。您会发现改进机会：

**意外的探索路径**：如果 Claude 以令人惊讶的顺序读取文件，您的导航结构可能不直观。添加更清晰的标志。

**错过的连接**：如果 Claude 没有发现相关的参考文件，链接可能不够明显。使连接更加明确。

**过度依赖某些部分**：如果 Claude 总是读取某个特定部分，该内容可能属于主 `SKILL.md` 以便更快访问。

**被忽略的内容**：如果 Claude 从不读取参考文件，它要么是不必要的，要么信号很弱。要么删除它，要么改进其描述。

**模式识别**：使用 5-10 次后，您将看到 Claude 如何导航的模式。围绕这些模式优化您的结构。

## 12、高级：具有可执行代码的技能

### 12.1 在脚本中显式处理错误

脚本应该**解决问题**，而不是把它们推给 Claude 处理。

**好的错误处理：**

```
def process_file(path):
    """处理文件，如果不存在则使用默认值创建它。"""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"文件 {path} 未找到，使用默认内容创建")
        with open(path, 'w') as f:
            f.write('# 默认配置\n')
        return '# 默认配置\n'
    except PermissionError:
        print(f"权限被拒绝用于 {path}。检查文件权限。")
        sys.exit(1)

```

**糟糕的错误处理：**

```
def process_file(path):
    # 只是失败并让 Claude 搞清楚
    return open(path).read()  # 用无用的错误崩溃

```

**为什么显式处理很重要：**当脚本因清晰、可操作的错误消息而失败时，Claude 通常可以自动解决问题。通用错误迫使 Claude 猜测。

### 12.2 提供实用脚本以节省 token

预制的脚本比让 Claude 按需生成代码有几个优势：

- **更可靠**：提前测试和调试
- **节省 token**：上下文窗口中没有代码
- **节省时间**：不需要生成
- **确保一致性**：每次都相同的方法

```

## 实用脚本

**analyze_form.py**：从 PDF 中提取所有表单字段
```bash
python scripts/analyze_form.py input.pdf > fields.json
```
输出：具有字段名称、类型和位置的 JSON 文件

**validate_boxes.py**：检查重叠的边界框
```bash
python scripts/validate_boxes.py fields.json
```
返回："OK" 或列出修复建议的冲突

```

**真实世界影响：** 一个构建文档处理技能的团队在用实用脚本替换生成的代码片段后，token 使用量减少了 40%。

### 12.3 创建可验证的中间输出

对于复杂的多步骤任务，使用**计划-验证-执行**模式：

1. **分析**以创建计划文件
2. **验证**计划以获得具体反馈
3. **执行**计划以执行操作
4. **验证**输出以确认成功

**示例工作流程：**

```
## 带验证的表单填充

1. 分析表单结构：
```bash
python scripts/analyze_form.py input.pdf > plan.json
```

2. **在继续之前验证计划**：
```bash
python scripts/validate_plan.py plan.json
```

修复任何报告的错误。常见问题：
- 缺少必填字段
- 重叠的边界框
- 无效的字段类型

3. 仅在验证通过时执行：
```bash
python scripts/fill_form.py plan.json input.pdf output.pdf
```

```

使验证具有具体的、可操作的错误消息：

```

糟糕的："验证失败"
好的："未找到字段 'signature_date'。可用字段：customer_name、order_total、delivery_address"

```

### 12.4 依赖项：列出和验证

始终明确指定所需的包：

```

## 要求

此技能需要以下包：
```bash
pip install pypdf pdfplumber pillow
```

**验证安装**：
```bash
python -c "import pdfplumber; print('pdfplumber:', pdfplumber.version)"
```

如果您看到版本输出，您就准备好了。

```

**为什么验证很重要：**安装可能会静默失败，特别是在虚拟环境中。快速验证步骤会在导致任务中途出现神秘错误之前捕获问题。

### 12.5 MCP 工具引用：使用完全限定名称

引用 MCP 工具时，始终使用完全限定格式：Plugin:tool\_name

```markdown
使用 `BigQuery:bigquery_schema` 工具检索表架构。
使用 `GitHub:create_issue` 工具创建问题。
使用 `Notion:create_page` 工具创建新页面。

```

**为什么这很重要：**像 "create\_issue" 这样的通用名称可能指的是多个工具。限定名称消除了歧义。

## 13、内容指南

### 13.1 避免时间敏感信息

技能应该是**永恒的**。避免引用特定日期或变得过时的"当前"状态。

**糟糕的：**

```
如果您在 2025 年 8 月之前这样做，请使用旧 API。 
在 2025 年 8 月之后，请使用新 API。
```

**好的：**

```python
## 当前方法

使用 v2 API 端点：
```python
response = requests.post("https://api.example.com/v2/messages")
```

## 旧模式
旧 v1 API（2025 年 8 月已弃用）

v1 API 使用不同的端点结构：
```python
response = requests.post("https://api.example.com/v1/messages")
```
```

**为什么这有效：**新用户立即看到当前方法。维护遗留代码的用户可以展开详细信息部分。不需要基于时间的逻辑。

### 13.2 在整个过程中使用一致的术语

为每个概念选择一个术语并坚持使用：

- **一致：**始终"API 端点" | **不一致（令人困惑）：**混合"API 端点"、"URL"、"路由"、"路径"
- **一致：**始终"字段" | **不一致（令人困惑）：**混合"字段"、"框"、"元素"、"控件"
- **一致：**始终"提取" | **不一致（令人困惑）：**混合"提取"、"拉"、"获取"、"检索"
- **一致：**始终"验证" | **不一致（令人困惑）：**混合"验证"、"检查"、"确认"、"测试"

为什么一致性很重要：每个新术语都迫使 Claude（和用户）确定它是同义词还是不同的概念。一致的术语减少了认知负荷。

### 13.3 避免提供太多选项

不要用选择压倒一切。**推荐一种方法**，然后仅在真正需要时提及替代方案。

**糟糕的：**

```
您可以使用 pypdf，或 pdfplumber，或 PyMuPDF，或 pdf2image，或 tabula-py... 每个都有优缺点。选择您喜欢的任何一个。
```

**好的：**

```python
使用 pdfplumber 进行文本提取。它可靠地处理大多数 PDF：

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

**对于扫描的 PDF（图像，不是文本），使用 pdf2image 和 pytesseract 进行 OCR：**
```python
from pdf2image import convert_from_path
from pytesseract import image_to_string
```
```

为什么单一推荐有效：它消除了决策瘫痪。Claude 可以专注于执行而不是评估权衡。如果推荐方法失败，Claude 可以探索替代方案。但大多数任务主要推荐都能成功。

## 14、有效技能的检查清单

在部署技能之前使用此检查清单：

核心质量：

- \[ \] 描述具体且包含触发关键词
- \[ \] 描述包括技能做什么以及何时使用它
- \[ \] [SKILL.md](http://skill.md/?ref=hubwiz.com) 主体在 500 行以下
- \[ \] 其他详细信息在单独的参考文件中（不挤入 [SKILL.md](http://skill.md/?ref=hubwiz.com)）
- \[ \] 没有时间敏感信息（没有"2025 年之前"的逻辑）
- \[ \] 在所有文件中术语一致
- \[ \] 文件引用是一层深的（没有嵌套链）
- \[ \] 适当地使用渐进式披露模式

代码和脚本：

- \[ \] 脚本显式处理错误并带有清晰消息
- \[ \] 没有"巫术常数"（所有硬编码值都有解释原因的注释）
- \[ \] 列出所需的包并带有安装命令
- \[ \] 所有文件路径使用正斜杠（跨平台兼容性）
- \[ \] 关键操作的验证/验证步骤
- \[ \] 脚本解决问题而不是把它们推给 Claude

测试：

- \[ \] 至少创建了三个评估，涵盖主要用例
- \[ \] 使用 Haiku、Sonnet 和 Opus 模型进行了测试
- \[ \] 在真实场景上测试（不仅仅是玩具示例）
- \[ \] 观察了 Claude 如何导航技能
- \[ \] 融入了团队反馈（对于项目技能）

## 15、快速参考：创建您的第一个技能

让我们创建一个生成提交消息的简单技能。

### 15.1 步骤 1：创建技能目录

```
# 个人技能（随处可用，对您私有）
mkdir -p ~/.claude/skills/generating-commit-messages

# 项目技能（仅此项目，通过 git 共享）
mkdir -p .claude/skills/generating-commit-messages
```

对于 Codex：

```
# 个人技能（随处可用，对您私有）
mkdir -p ~/.codex/skills/generating-commit-messages

# 项目技能（仅此项目，通过 git 共享）
mkdir -p .codex/skills/generating-commit-messages
```

对于 OpenCode：

```
# 个人技能（随处可用，对您私有）
mkdir -p ~/.config/opencode/skill/generating-commit-messages

# 项目技能（仅此项目，通过 git 共享）
mkdir -p .opencode/skill/generating-commit-messages
```

### 15.2 步骤 2：创建最小 [SKILL.md](http://skill.md/?ref=hubwiz.com)

```
---
name: generating-commit-messages description: Generates clear commit messages by analyzing git diffs. Use when writing commit messages or reviewing staged changes.
---

# 生成提交消息

## 指令

1. 运行 `git diff --staged` 查看更改
2. 分析更改并建议提交消息，包括：
  - 摘要：50 个字符以下，现在时
  - 描述：更改了什么以及为什么
  - 受影响的组件：列出修改区域

## 格式
```
<type>(<scope>): <summary>
```

类型：feat、fix、docs、refactor、test、chore

## 最佳实践
- 使用现在时（"添加功能"而不是"添加了功能"）
- 解释什么和为什么，而不是如何
- 在相关时引用问题编号
```

### 15.3 步骤 3：测试它

打开一个新的编码代理对话并尝试："帮我为我的暂存更改编写提交消息。"

### 15.4 步骤 4：迭代

观察您的编码代理如何使用技能。根据有效的和无效的进行改进。

## 16、结束语

编写有效的 Agent 代码技能是关于平衡：

**在简洁性和清晰性之间取得平衡**：每个 token 都在竞争空间，但 Claude 需要足够的上下文来成功。

**在规定和自由度之间取得平衡**：将指令具体性与任务脆弱性相匹配。

**在结构和灵活性之间取得平衡**：组织以便于导航，但不要过度设计。

**在测试和发布之间取得平衡**：根据实际使用进行迭代，但不要让完美成为良好的敌人。

最好的技能感觉像**来自专家的知识转移**。它们捕获了程序智慧和将 Claude 从通用 AI 转变为您的领域中的领域专家的组织上下文。

**从小开始：**

1. 首先构建评估（揭示 Claude 在哪里挣扎）
- 编写最少的文档（相信 Claude 的智能）
- 跨模型测试（Haiku、Sonnet、Opus）
- 根据观察进行迭代（观察 Claude 如何导航）

每次迭代都使您的技能更敏锐。您覆盖的每个用例都使 Claude 更有能力。您不仅在编写文档。您在编码专业知识。

**您会先教您的编码代理什么？**

---

**原文链接**：[Mastering Agentic Skills: The Complete Guide to Building Effective Agent Skills](https://pub.spillwave.com/mastering-agentic-skills-the-complete-guide-to-building-effective-agent-skills-d3fe57a058f1?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处