一文了解 Agent Skill的定义、编写、script、references

什么是Skills？

Agent Skills 是一种轻量级、开放的格式，用于扩展 AI Agent能力，结合专业知识和工作流程。

Skill的核心是一个包含 SKILL.md 文件的文件夹。该文件包含元数据（至少包含name和description）以及指示Agent如何执行特定任务的指令。Skill还可以绑定可执行代码、模板/资源和参考资料。

plain 复制代码

my-skill/
├── SKILL.md          # 必填：指令+元数据
├── scripts/          # 可选: 可执行代码
├── references/       # 可选: 参考资料
└── assets/           # 可选: 模板，资源

scripts 可执行代码

包含Agent可以运行的可执行代码，支持的语言取决于Agent的实现。常见的选择包括 Python、Bash 和 JavaScript。。脚本应当：
- Agent有的代码或明确记录依赖关系
- 包含有用的错误信息
- 优雅地处理边缘情况
references 参考文献

包含Agent在需要时可阅读的额外文件：
- REFERENCE.md - 详细技术参考
- FORMS.md - 表单模板或结构化数据格式
- 领域特定文件（finance.md、legal.md 等）
保持每个参考文献文件的聚焦。Agent按需加载这些文件，因此文件越小，上下文的使用越少。

在引用Skill中的其他文件时，使用Skill根的相对路径：
SKILL.md 复制代码
```
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py
```
保持文件引用与SKILL.md仅隔一级。避免深层嵌套的引用链。
assets 模板/资源

包含静态资源：
- 模板（文档模板、配置模板）
- 图片（图示、示例）
- 数据文件（查找表，模式）

Skills工作原理

Skills利用渐进式披露高效管理上下文：

发现：启动时，Agent只加载每个可用Skill的name和description，仅仅Skill的用途和激活的时机。
激活：当任务与Skills描述匹配时，Agent会将完整的 SKILL.md 指令读入上下文。
执行：Agent按照指令操作，可根据需要加载引用文件或执行绑定Script。

这种方式既能让Agents保持快速工作，又能按需获取更多上下文信息。

SKILL.md 文件

每个Skills都以包含 YAML 前言和 Markdown 指令的 SKILL.md 文件开头：

plain 复制代码

---
name: Logistics Customer Service
description: 当客户咨询支持的快递公司、发货时效、订单的物流信息、快递是否签收是使用Skill。
---

# 物流服务

## 何时使用
当用户需要查询物流、快递相关信息。

## 快递服务
- 支持快递公司：中通、圆通、申通
- 发货时效：下单后48小时内发货

## 工作流规则
1. 信息披露：仅根据已知事实（由用户或工具结果提供）进行回复。切勿编造依据的回复。
2. 强制工具调用：如果用户提到订单但上下文中没有物流数据 → 在回答之前**立即调用 `getOrderLogistics`**，参数订单号orderId。
3. 签收判断：分析工具结果中的 `status` 字段：
	- ✅签收：最新节点包含"signed"/"received"/"已签署"/"已接收"/"代收"等 → 确认签收成功。
	- 🚛运输中：状态显示 "transport"/"departure"/"arrival" → 如有可能，请提供预计到达时间。
	-  ⏳未发货：无快递单号或仅限"order created" →对照48小时承诺检查
4. 异常处理：
	- 工具调用后仍无数据 → 建议用户稍后重试或联系人工客服。
	- 不支持该快递公司 → 礼貌提示超出范围（仅支持中通/圆通/申通）。

## 回复风格
1. 专业且友好：使用敬语（如"您"），确认关键信息，总结清晰。

SKILL.md 顶部需要附上以下前言：

name ：简短标识
description ：何时使用此技能

Markdown 正文包含实际的说明，且对结构或内容没有具体限制。

Skills规范

SKILL.md 文件必须包含 YAML 前言，后面是 Markdown 内容。

YAML前言

字段	必填	约束
name	Yes	最多64个字符。仅限小写字母、数字和-。不得以-开头或结尾。
description	Yes	最多1024字符。非空的。描述Skill的作用以及何时使用。
license	No	许可证名称或捆绑许可文件的引用。
compatibility	No	最多500字符。表示环境需求（预期产品、系统包、网络访问等）。
metadata	No	任意键值映射以获取额外元数据。

Markdown 内容

前言后的 Markdown 主体包含技能指令。没有格式限制。写任何帮助LLM有效完成任务的内容。

专注于Agent没有的Skill ，Agent不会知道的部分：项目特定的惯例、领域特定的流程、不显而易见的边缘情况，以及可用的特定工具或 API。

过于全面的Skill反而可能弊大于利------Agent难以提取相关内容，可能走上因指令不适用而走上无效的道路。简明、分步骤的指导并附有可行的示例，往往比详尽的文档更有效。

规范建议 SKILL.md 保持在 500 行和 5000 个Token以内------仅保留Agent每次运行所需的核心指令。当某个Skill确实需要更多内容时，可以把详细的参考资料移到references/或类似目录中的独立文件中。

关键是告诉Agent何时加载每个文件。"如果 API 返回非 200 状态码，请阅读 references/api-errors.md"比通用的"详情请参见参考文献/"更有用。这使得Agent能够按需加载上下文，而非事先加载，这正是渐进披露的设计初面。

输出格式模板

当你需要Agent以特定格式输出时，提供模板。这比用散文描述格式更可靠，因为Agent能很好地与具体结构进行模式匹配。短模板可以在线保存 SKILL.md;对于较长的模板，或者只在特定情况下需要的模板，可以把它们存储在assets/ 并从 SKILL.md 引用，这样它们只在需要时加载。

markup 复制代码

## 返回结构

使用此模板，根据具体分析需求调整各部分内容：

```markdown
# [分析标题]

## 执行摘要
[关键发现的一段落概述]

## 主要发现
- 发现1及支持数据
- 发现2及支持数据

## 建议
1. 具体的可操作建议
2. 具体的可操作建议 ```

多步骤工作流程检查表

明确的检查清单帮助Agent跟踪进度，避免跳过步骤，尤其是在步骤存在依赖或验证时。

Markup 复制代码

## 表单处理流程

进度：
- [ ] 第一步：分析表单（运行 `scripts/analyze_form.py`）
- [ ] 第二步：创建字段映射（编辑 `fields.json`）
- [ ] 第三步：验证映射（运行 `scripts/validate_fields.py`）
- [ ] 第四步：填写表单（运行 `scripts/fill_form.py`）
- [ ] 第五步：验证输出（运行 `scripts/verify_output.py`）

循环验证

指示Agent在继续前验证自己的工作。

模式是：完成工作，运行验证程序（脚本、参考检查表或自我检查），修正任何问题，然后重复直到验证通过。

markup 复制代码

## 编辑工作流程

1. 进行编辑
2. 运行验证：`python scripts/validate.py output/`
3. 如果验证失败：
   - 查看错误信息
   - 修复问题
   - 再次运行验证
4. 仅在验证通过后继续

计划-验证-执行

对于批处理或破坏性操作，让Agent以结构化格式创建中间计划，验证真实性来源，然后执行。

markup 复制代码

## PDF 表单填写指南

1. 提取表单字段：`python scripts/analyze_form.py input.pdf` → `form_fields.json`
   （列出每个字段名称、类型及是否必填）
2. 创建 `field_values.json` 文件，将每个字段名映射到其预设值
3. 验证：`python scripts/validate_fields.py form_fields.json field_values.json`
   （检查表单中是否存在所有字段名、类型是否兼容、必填字段是否缺失）
4. 若验证失败，修改 `field_values.json` 后重新验证
5. 填写表单：`python scripts/fill_form.py input.pdf field_values.json output.pdf`

关键要素是第三步：一个验证脚本，将计划（field_values.json）与真实来源（form_fields.json）进行核对。诸如"未找到字段'signature_date'------可用字段：customer_name、order_total、signature_date_signed"这样的错误，能让Agent获得足够的信息进行自我纠正。

在Skill使用脚本

Skill可以指导Agent运行 shell 命令，并将可重用script捆绑在scripts/ 目录中。

一次性指令(One-off commands）

当已存在的package已经满足你需要的功能时，你可以直接在 SKILL.md 指令中引用它，无需scripts/目录。许多生态系统提供在运行时自动解析依赖的工具。

例如 pipx 在隔离环境中运行 Python 包。通过操作系统包管理器（apt install pipx，brew install pipx）获取。

bash 复制代码

pipx run 'black==24.10.0' .
pipx run 'ruff==0.8.0' check .

引用 SKILL.md 中的脚本

使用Skill目录根的相对路径来引用捆绑文件。Agent会自动解析这些路径------不需要绝对路径。

在 SKILL.md 中列出可用的script，让Agent知道它们的存在：

SKILL.md 复制代码

## 可用脚本

- **`scripts/validate.sh`** --- 验证配置文件
- **`scripts/process.py`** --- 处理输入数据

然后指示Agent运行：

SKILL.md 复制代码

## 工作流

1. 运行验证脚本:
  bash scripts/validate.sh "$INPUT_FILE"

2. 处理结果:
  python3 scripts/process.py --input results.json

---help 使用文档

--help输出是Agent学习script接口的主要方式。请包含简要描述、可用标志和使用示例：

bash 复制代码

Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
  --format FORMAT    Output format: json, csv, table (default: json)
  --output FILE      Write output to FILE instead of stdout
  --verbose          Print progress to stderr

Examples:
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

保持简洁------输出结果会与Agent正在处理的所有其他内容一起进入Agent的上下文窗口。

写出有用的错误信息

当Agent收到错误信息时，该信息会直接影响其下一次尝试。一条晦涩难懂的"错误：输入无效"会浪费一次行动机会。相反，应该说明哪里出了问题，预期结果是什么，以及接下来应该尝试什么：

bash 复制代码

Error: --format must be one of: json, csv, table.
       Received: "xml"

优化 description

Skill只有在被激活时才有用。你 SKILL.md 前件中的description字段是Agent决定是否加载Skill的主要机制。description不够明确意味着Skill不会在应触发时触发;过于宽泛的description意味着它在不该触发时触发。

Skill触发机制

Agent使用渐进披露来管理背景。启动时，他们只加载每个可用Skill的name和description ------仅仅足够判断Skill何时可能相关。当用户的任务与描述相符时，Agent会将完整的 SKILL.md 解读到上下文中并遵循其指令。

这意味着description承担了触发的全部责任。如果description没有说明该Skill何时有用，Agent就不会知道该去使用它。

编写有效的`description`

好的description原则：

使用祈使句 。将description框架为对Agent的指令："当...使用此Skill时"而不是"此Skill..."Agent正在决定是否行动，所以告诉它何时行动。
关注用户意图，而非实现。描述使用者想要达到的目标，而不是Skill的内部机制。Agent会匹配用户要求的。
宁可强势一点。明确列出该Skill适用的场景，包括用户未直接提及领域的情况："即使他们没有明确提及'CSV'或'分析'。"
保持简洁。几句话配上一段短段落通常是合适的------足够长以涵盖技能的范围，又足够短，不会让Agent在多个Skill间的背景变得臃肿。规范强制执行 1024 字符的硬性限制。

评估技能输出质量

你写了一个技能，在提示下尝试了一下，似乎有效。但它是否能可靠地奏效------在各种提示下，在极端情况下，总比完全没有Skill好？进行结构化评估（evals）可以回答这些问题，并为你提供一个系统性提升Skill的反馈循环。

测试用例设计

测试用例分为三个部分：

Prompt：一个真实的User Message------那种有人真的会打出来的话。
预期成果 ：用通俗易懂的方式描述成功是什么样子。
输入文件 （可选）：Skill需要操作的文件。

在你的Skill目录中，将测试用例存放在evals/evals.json 中：

evals/evals.json 复制代码

{
  "skill_name": "Logistics-Customer-Service",
  "evals": [
    {
      "id": 1,
      "prompt": "123713订单的快递到那里了？",
      "expected_output": "快递已经到达街区，快递员正在派送中"
    },
    {
      "id": 2,
      "prompt": "啥时候可以发货？",
      "expected_output": "下单后48小时内发货"
    }
  ]
}

工作区结构

把评估结果和技能目录一起整理在工作区目录里。每次通过完整评估循环都会获得自己的iteration-N/ 目录。在该目录中，每个测试用例都会获得一个包含 with_skill/ 和 without_skill/ 子目录的评估目录：

plain 复制代码

Logistics-Customer-Service/
├── SKILL.md
└── evals/
    └── evals.json
Logistics-Customer-Service-workspace/
└── iteration-1/
    ├── eval-definite-query/
    │   ├── with_skill/
    │   │   ├── outputs/       # 运行生成的文件
    │   │   ├── timing.json    # Tokens and duration
    │   │   └── grading.json   # 断言结果
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    ├── eval-not-definite-query/
    │   ├── with_skill/
    │   │   ├── outputs/
    │   │   ├── timing.json
    │   │   └── grading.json
    │   └── without_skill/
    │       ├── outputs/
    │       ├── timing.json
    │       └── grading.json
    └── benchmark.json         # 汇总统计

你手写的主要文件是 evals/evals.json。其他 JSON 文件（grading.json、timing.json、benchmark.json）是在评估过程中生成的------由代理、脚本或你自己生成。

一文了解 Agent Skill的定义、编写、script、references

什么是Skills？

Skills工作原理

SKILL.md 文件

Skills规范

YAML前言

Markdown 内容

输出格式模板

多步骤工作流程检查表

循环验证

计划-验证-执行

在Skill使用脚本

一次性指令(One-off commands）

引用 SKILL.md 中的脚本

---help 使用文档

写出有用的错误信息

优化 description

Skill触发机制

编写有效的description

评估技能输出质量

测试用例设计

工作区结构

编写有效的`description`