技能创建 on Agent Skills

快速入门

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 中一次性命令的建议：