概览 on Agent Skills

什么是 Skill？

Mon, 01 Jan 0001 00:00:00 +0000

什么是 Skill？#

Agent Skills 是一种轻量级的开放格式，用于通过专业知识和工作流扩展 AI 智能体（Agent）的能力。

从本质上讲，Skill 是一个包含 SKILL.md 文件的文件夹。该文件包含元数据（至少包括 name 和 description）以及告诉智能体如何执行特定任务的指令。Skill 还可以捆绑脚本、模板和参考资料。

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

技能如何运作#

Skill 使用 渐进式披露（Progressive Disclosure） 来高效地管理上下文：

发现（Discovery）：在启动时，智能体仅加载每个可用 Skill 的名称和描述，这足以让它知道该 Skill 何时可能相关。
激活（Activation）：当任务与 Skill 的描述匹配时，智能体会将完整的 SKILL.md 指令读取到上下文中。
执行（Execution）：智能体遵循指令，并根据需要加载引用的文件或执行关联的代码。

这种方法在保持智能体响应速度的同时，让它们能够根据需求访问更多上下文。

SKILL.md 文件#

每个 Skill 都始于一个包含 YAML Frontmatter 和 Markdown 指令的 SKILL.md 文件：

---
name: pdf-processing
description: 提取 PDF 文本、填写表单、合并文件。在处理 PDF 时使用。
---

# PDF 处理

## 何时使用此技能

当用户需要处理 PDF 文件时，使用此技能...

## 如何提取文本

1. 使用 pdfplumber 进行文本提取...

## 如何填写表单

...

SKILL.md 顶部必须包含以下 Frontmatter：

格式规范

Mon, 01 Jan 0001 00:00:00 +0000

格式规范#

Agent Skills 的完整格式规范。

目录结构#

一个 Skill 本质上是一个目录，其中至少包含一个 SKILL.md 文件：

skill-name/
├── SKILL.md # 必需：元数据 + 指令
├── scripts/ # 可选：可执行代码
├── references/ # 可选：文档资料
├── assets/ # 可选：模板、资源
└── ... # 任何额外的文件或目录

`SKILL.md` 格式#

SKILL.md 文件必须包含 YAML 前置参数（Frontmatter），随后是 Markdown 内容。

前置参数 (Frontmatter)#

字段	是否必需	约束条件
`name`	是	最长 64 个字符。仅限小写字母、数字和连字符。不能以连字符开头或结尾。
`description`	是	最长 1024 个字符。不能为空。描述 Skill 的功能及使用场景。
`license`	否	许可证名称或指向随附许可证文件的引用。
`compatibility`	否	最长 500 个字符。指示环境要求（目标产品、系统包、网络访问等）。
`metadata`	否	用于存储额外元数据的任意键值映射。
`allowed-tools`	否	预先批准该 Skill 可以使用的工具列表，以空格分隔。（实验性）

最小示例：

客户端展示

Mon, 01 Jan 0001 00:00:00 +0000

客户端展示#

支持 Agent Skills 格式的智能体产品。

Agentman #

Agentman 是一个智能医疗平台。它使用 AI 智能体自动执行收入周期工作流，同时不牺牲控制力。每项操作都是可测试、可追溯和可审计的。

设置指南

Amp #

Amp 是前沿的编程智能体，让您能够发挥领先模型的全部力量。

设置指南

Autohand Code CLI #

Autohand Code CLI 是一款运行在终端的自主 LLM 驱动编程智能体。它利用 ReAct (推理 + 行动) 模式来理解您的代码库、计划更改并在获得您的批准后执行。

Claude #

Claude 是 Anthropic 的 AI，专为问题解决者而构建。处理复杂的挑战、分析数据、编写代码并思考您最困难的工作。

设置指南

Claude Code #

Claude Code 是一款智能编程工具，可以读取您的代码库、编辑文件、运行命令并与您的开发工具集成。可在您的终端、IDE、桌面应用程序和浏览器中使用。

设置指南

Command Code #

Command Code 是一款会不断学习您的代码品味的编程智能体。我们的元神经符号 AI 模型 taste-1 结合了持续强化学习，将 LLM 与您的代码品味相结合。

快速入门

Mon, 01 Jan 0001 00:00:00 +0000

快速入门#

创建你的第一个智能体技能（Agent Skill），并在 VS Code 中查看其运行效果。

在本教程中，你将创建一个技能，使智能体能够使用随机数生成器进行掷骰子。

前提条件#

安装了 GitHub Copilot 的 VS Code

本教程使用 VS Code，但智能体技能（Agent Skills）是一种开放格式。同样的技能可以在任何兼容的智能体中使用，包括 Claude Code 和 OpenAI Codex.

创建技能#

技能是一个包含 SKILL.md 文件的文件夹。VS Code 默认在 .agents/skills/ 路径下查找技能。在你的项目中创建 .agents/skills/roll-dice/SKILL.md 文件：

文件：.agents/skills/roll-dice/SKILL.md

---
name: roll-dice
description: 使用随机数生成器掷骰子。当被要求掷骰子（如 d6、d20 等）、掷出骰子或生成随机掷骰结果时使用。
---

要进行掷骰子，请使用以下命令生成一个从 1 到指定面数的随机数：

```bash
echo $((RANDOM % <sides> + 1))
```

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

将 `<sides>` 替换为骰子的面数（例如，标准骰子为 6，二十面骰为 20）。

就是这样 —— 一个文件，不到 20 行。以下是各部分的作用：

name — 技能的短标识符。必须与文件夹名称匹配。
description — 告诉智能体何时使用此技能。智能体据此决定是否激活该技能。
正文 (The body) — 技能激活时智能体遵循的指令。在这里，智能体被指示使用终端命令生成随机数，并将用户请求中的面数代入其中。

尝试一下#

在 VS Code 中打开你的项目。
打开 Copilot Chat 面板。
从聊天面板底部的模式下拉菜单中选择 Agent 模式。
输入 /skills 以确认 roll-dice 出现在列表中。如果没出现，请检查文件是否位于项目根目录下的 .agents/skills/roll-dice/SKILL.md。
提问：“掷一个 d20 骰子”

智能体应该会激活 roll-dice 技能。它可能会请求运行终端命令的权限 —— 请允许它。它将运行命令并返回一个 1 到 20 之间的随机数。

最佳实践

Mon, 01 Jan 0001 00:00:00 +0000

技能创建者的最佳实践#

如何编写范围明确、且针对任务校准良好的技能。

从真实的专业经验开始#

技能创建中一个常见的陷阱是：在不提供特定领域上下文的情况下，要求 LLM 生成技能 —— 仅仅依赖于 LLM 的通用训练知识。其结果往往是模糊、通用的流程（如“妥善处理错误”、“遵循身份验证的最佳实践”），而不是那些使技能具有真正价值的具体 API 模式、边缘情况和项目约定。

有效的技能往往根植于真实的专业经验。其关键在于将特定领域上下文馈送到创建过程中。

从实际任务中提取#

在与 Agent 的对话中完成一个真实任务，并在此过程中提供上下文、更正和偏好。然后，将这种可复用的模式提取成技能。请关注以下几点：

奏效的步骤 —— 指向成功的行动序列。
你做出的更正 —— 你引导 Agent 方法的地方（例如，“使用库 X 而不是 Y”、“检查边缘情况 Z”）。
输入/输出格式 —— 数据进入和输出时的样子。
你提供的上下文 —— Agent 之前不知道的特定于项目的实施、约定或约束。

从现有项目资产中合成#

当你拥有大量的现有知识时，你可以将其提供给 LLM 并要求它合成为一项技能。通过你团队真实的事故报告和运行手册（Runbooks）合成的数据管道技能，其表现将优于从通用的“数据工程最佳实践”文章中合成的技能，因为它捕获了你的 Schema、故障模式和恢复程序。关键在于特定于项目的材料，而非通用参考资料。

良好的源材料包括：

内部文档、运行手册和风格指南。
API 规范、Schema 和配置文件。
代码评审建议和问题追踪器（捕获了反复出现的关注点和评审者的预期）。
版本控制历史，特别是补丁和修复（通过实际发生的更改揭示模式）。
真实的失败案例及其解决方案。

通过实际执行进行微调#

技能的初稿通常需要进一步细化。针对实际任务运行该技能，然后将结果（包括成功的和失败的）反馈回创建过程。思考：是什么触发了误报？遗漏了什么？哪些部分可以删减？

即使仅进行一次“执行-修订”循环，也能显著提高质量；对于复杂的领域，通常需要进行多次迭代。

阅读 Agent 的执行痕迹（Traces），而不仅仅是最终输出。如果 Agent 在生产力较低的步骤上浪费时间，常见原因包括：指令过于模糊（Agent 在找到可行方法前尝试了多种方法）、指令不适用于当前任务（但 Agent 仍然遵循了它们），或者在没有明确默认值的情况下提供了过多的选项。

关于结构化的迭代方法（包括测试案例、断言和评分），请参阅评估技能输出质量。

明智地消耗上下文#

一旦技能被激活，其完整的 SKILL.md 正文将与对话历史、系统上下文和其他活动技能一起加载到 Agent 的上下文窗口中。你技能中的每一个 Token 都在与该窗口中的其他内容竞争 Agent 的注意力。

优化描述

Mon, 01 Jan 0001 00:00:00 +0000

优化 Skill 描述#

如何改进 Skill 的描述，使其在相关提示词下能够可靠地触发。

Skill 只有在被激活时才能发挥作用。SKILL.md 的 Frontmatter 中的 description 字段是智能体决定是否为给定任务加载该 Skill 的主要机制。描述不足会导致 Skill 在该触发时未触发；描述过宽则会导致其在不该触发时触发。

本指南介绍了如何系统地测试和改进 Skill 的描述，以提高触发准确性。

Skill 触发的工作原理#

智能体使用渐进式披露来管理上下文。在启动时，它们仅加载每个可用 Skill 的 name 和 description —— 这足以让它们决定某个 Skill 何时可能相关。当用户的任务与描述匹配时，智能体就会将完整的 SKILL.md 读取到上下文中并遵循其中的指令。

这意味着描述承担了触发的全部重任。如果描述没能传达出 Skill 何时有用，智能体就不知道要调用它。

一个重要的细微差别是：智能体通常只在任务需要的知识或能力超出了它们单独处理的范围时才会咨询 Skill。一个简单的、单步骤的请求（如“读取此 PDF”）可能不会触发 PDF Skill，即使描述完美匹配，因为智能体可以使用基础工具处理它。只有涉及专业知识的任务 —— 不熟悉的 API、特定领域的流转或不常见的格式 —— 才是精心编写的描述能发挥作用的地方。

编写有效的描述#

在测试之前，了解一份好的描述是什么样的会很有帮助。几个原则：

使用祈使句。 将描述框定为给智能体的指令：“当…时使用此技能”，而不是“此技能可以…”。智能体在决定是否采取行动，所以告诉它何时采取行动。
专注于用户意图，而非具体实现。 描述用户试图实现的目标，而不是 Skill 的内部机制。智能体会根据用户要求的任务进行匹配。
宁可稍微“推销”一点。 明确列出 Skill 适用的场景，包括用户没有直接点名该领域的情况：“即使他们没有明确提到‘CSV’或‘分析’。”
保持简练。 几句话到一小段通常是合适的 —— 长度足以覆盖 Skill 的范围，又短到不会在智能体面对众多 Skill 时使其上下文膨胀。规范强制限制为 1024 个字符。

设计触发评估查询#

要测试触发情况，你需要一组评估查询 —— 标记了“应该触发”或“不应该触发”该 Skill 的真实用户提示词。

评估输出质量

Mon, 01 Jan 0001 00:00:00 +0000

评估输出质量#

如何使用评测驱动（eval-driven）的迭代来测试你的技能是否能产出高质量的输出。

你编写了一个 Skill，在提示词上试了一下，看起来运行良好。但它是否能可靠地工作——在各种不同的提示词下、在边缘情况下，是否真的比没有 Skill 时表现更好？运行结构化的评估（Evals）可以回答这些问题，并为你提供系统性改进 Skill 的反馈闭环。

设计测试用例#

一个测试用例包含三个部分：

提示词 (Prompt)：真实的普通用户消息——即用户实际会输入的内容。
预期输出 (Expected output)：对成功结果的人类可读描述。
输入文件（可选）：Skill 运行时需要配合使用的文件。

将测试用例存储在 Skill 目录下的 evals/evals.json 中：

{
	"skill_name": "csv-analyzer",
	"evals": [
		{
			"id": 1,
			"prompt": "我有一份 data/sales_2025.csv 的月度销售数据。你能帮我找出收入排名前三的月份并制作一张柱状图吗？",
			"expected_output": "一张显示收入前三月份的柱状图，带有清晰的轴标签和数值说明。",
			"files": ["evals/files/sales_2025.csv"]
		},
		{
			"id": 2,
			"prompt": "我的下载文件夹里有一个叫 customers.csv 的文件，有些行缺少邮箱地址——你能清理一下并告诉我漏掉了多少个吗？",
			"expected_output": "清理后的 CSV 文件（已处理缺失邮箱），并附带缺失数量的统计。",
			"files": ["evals/files/customers.csv"]
		}
	]
}

编写高质量测试提示词的技巧：

从 2-3 个用例开始。在看到第一轮结果之前不要过度投入，以后可以再扩展。
提示词要多样化。使用不同的措辞、详细程度和语气。有些提示词可以比较随意（“嘿，帮我洗下这个 csv”），有些则要精确（“解析 data/input.csv，删除 B 列为空的行，并将结果写入 data/output.csv”）。
覆盖边缘情况。至少包含一个测试边界条件的提示词——比如格式错误的输入、不寻常的请求，或者 Skill 指令可能产生歧义的情况。
使用真实的上下文。真实用户会提到文件路径、列名和个人背景。像“处理这个数据”这样模糊的提示词对于测试没有任何帮助。

现在不用担心如何定义具体的通过/失败标准——只需关注提示词和预期输出。在看到第一轮运行结果后，你再添加详细的检查项（称为断言）。

运行评估 (Evals)#

核心模式是将每个测试用例运行两次：一次 使用 Skill，一次 不使用 Skill（或使用之前的版本）。这为你提供了一个对比的基准。

使用脚本

Mon, 01 Jan 0001 00:00:00 +0000

在技能中使用脚本#

如何在技能中运行命令并捆绑可执行脚本。

Skill 可以指示 Agent 运行 Shell 命令，并在 scripts/ 目录中包含可重用的脚本。本指南涵盖了一次性命令、带有自身依赖项的自包含脚本，以及如何为 Agent 设计脚本接口。

一次性命令#

当现有的软件包已经能满足你的需求时，你可以直接在 SKILL.md 指令中引用它，而无需 scripts/ 目录。许多生态系统都提供了在运行时自动解析依赖项的工具。

uvx: 随 uv 一起发布。在隔离环境中运行 Python 包，具有强大的缓存功能。
```
uvx ruff@0.8.0 check .
uvx black@24.10.0 .
```
pipx: 在隔离环境中运行 Python 包。可通过 OS 包管理器安装。
```
pipx run 'black==24.10.0' .
pipx run 'ruff==0.8.0' check .
```
npx: 运行 npm 包，按需下载。随 npm（及 Node.js）一起发布。
```
npx eslint@9 --fix .
npx create-vite@6 my-app
```
bunx: Bun 版本的 npx。
deno run: 直接从 URL 或标识符运行脚本。需要权限标志（如 --allow-read）。
go run: 直接编译并运行 Go 包。内置于 go 命令中。

针对 Skill 中一次性命令的建议：

添加技能支持

Mon, 01 Jan 0001 00:00:00 +0000

如何为你的智能体添加技能支持#

为 AI 智能体或开发工具添加 Agent Skills 支持的指南。

本指南将深入探讨如何为 AI 智能体或开发工具添加 Agent Skills（智能体技能）支持。它涵盖了技能的完整生命周期：发现技能、告知模型相关技能、将内容加载到上下文中，以及确保这些内容在长时间会话中持续有效。

无论你的智能体架构如何，核心集成逻辑都是一致的。具体的实现细节会根据以下两个因素而有所不同：

技能存储在哪里？ 本地运行的智能体可以扫描用户文件系统的技能目录。而云端托管或沙箱化的智能体则需要替代的发现机制——例如 API、远程注册中心或捆绑的静态资产。
模型如何访问技能内容？ 如果模型具备文件读取能力，它可以直接读取 SKILL.md 文件。否则，你需要提供专用的工具，或者通过编程方式将技能内容注入提示词。

本指南在这些差异产生影响的地方进行了说明。你不需要支持所有场景——只需遵循适合你智能体需求的路径即可。

前提条件：熟悉 Agent Skills 规范，该规范定义了 SKILL.md 的文件格式、Frontmatter 字段和目录约定。

核心原则：渐进式披露#

每一个兼容技能的智能体都遵循相同的“三层加载”策略：

层级	加载内容	何时加载	Token 消耗
1. 目录	技能名称 + 描述	会话开始时	每个技能约 50-100 tokens
2. 指令	`SKILL.md` 的完整正文	技能被激活时	推荐 < 5000 tokens
3. 资源	脚本、引用、资产	当指令中显式引用它们时	视具体资源而定

模型从一开始就能看到目录，因此它知道有哪些可用技能。当模型判断某个技能相关时，它会加载完整的指令。如果这些指令中引用了辅助文件，模型会根据需要单独加载它们。

这种策略能保持基础上下文精简，同时让模型可以按需获取专业知识。即使一个智能体安装了 20 个技能，它也不需要预先承担 20 套完整指令的 Token 成本——只需为给定对话中实际用到的技能付费。

步骤 1：发现技能#

在会话启动时，寻找所有可用技能并加载其元数据。

扫描位置#

扫描哪些目录取决于智能体的环境。大多数本地运行的智能体至少会扫描两个范围：

概览 on Agent Skills

什么是 Skill？

什么是 Skill？#

技能如何运作#

SKILL.md 文件#

格式规范

格式规范#

目录结构#

SKILL.md 格式#

前置参数 (Frontmatter)#

客户端展示

客户端展示#

Agentman#

Amp#

Autohand Code CLI#

Claude#

Claude Code#

Command Code#

快速入门

快速入门#

前提条件#

创建技能#

尝试一下#

最佳实践

技能创建者的最佳实践#

从真实的专业经验开始#

从实际任务中提取#

从现有项目资产中合成#

通过实际执行进行微调#

明智地消耗上下文#

优化描述

优化 Skill 描述#

Skill 触发的工作原理#

编写有效的描述#

设计触发评估查询#

评估输出质量

评估输出质量#

设计测试用例#

运行评估 (Evals)#

使用脚本

在技能中使用脚本#

一次性命令#

添加技能支持

如何为你的智能体添加技能支持#

核心原则：渐进式披露#

步骤 1：发现技能#

扫描位置#

`SKILL.md` 格式#

Agentman #

Amp #

Autohand Code CLI #

Claude #

Claude Code #

Command Code #