Agent Skills

快速入门

创建你的第一个 Agent Skill,并在 VS Code 中体验它的运行效果。

本教程将带你创建一个 Skill,让 Agent 使用随机数生成器掷骰子。

前提条件

注意

本教程使用 VS Code,但 Agent Skills 是一种开放格式。同一个 Skill 也能在其他兼容的 Agent 中运行,包括 Claude Code 和 OpenAI Codex。

创建 Skill

Skill 是包含 SKILL.md 文件的文件夹。VS Code 默认在 .agents/skills/ 中查找 Skill。在项目中创建 .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,d20 骰子填 20。

这样就完成了:一个文件,不到 20 行。各部分的作用如下:

  • name——Skill 的简短标识,必须与文件夹名称一致。
  • description——告诉 Agent 何时使用这个 Skill,Agent 据此决定是否激活它。
  • 正文——Skill 激活后供 Agent 遵循的指令。这里的指令要求 Agent 用终端命令生成随机数,并按用户要求代入骰子的面数。

试运行

  1. 在 VS Code 中打开项目。
  2. 打开 Copilot Chat 面板。
  3. 在聊天面板底部的模式下拉菜单中选择 Agent 模式。
  4. 输入 /skills,确认列表中出现 roll-dice。如果没有,检查文件是否位于项目根目录下的 .agents/skills/roll-dice/SKILL.md。
  5. 输入:“掷一次 d20 骰子”。

Agent 应当激活 roll-dice Skill。它可能请求运行终端命令的权限,允许后便会执行命令,返回一个介于 1 和 20 之间的随机数。

注意

不同模型使用工具的可靠程度不同。有些模型能稳定地遵循 Skill 指令并运行命令,有些则可能尝试直接作答。如果 Agent 没有执行终端命令就给出了结果,可以在模型下拉菜单中换一个模型再试。

工作原理

这一过程的背后发生了以下步骤:

  1. 发现——聊天会话启动后,Agent 扫描默认的 Skill 目录,找到你创建的 Skill。它只读取 name 和 description,据此判断这个 Skill 可能适用于哪些任务。
  2. 激活——你提出掷骰子的请求后,Agent 将请求与 Skill 的描述匹配,再把完整的 SKILL.md 正文加载到上下文中。
  3. 执行——Agent 遵循正文中的指令,按你要求的骰子面数调整终端命令。

这个过程采用渐进式披露,让 Agent 无需一开始就加载全部指令,也能使用大量 Skill。

后续步骤

你已经创建了一个能够运行的 Agent Skill。接下来可以阅读:

  • 最佳实践——如何编写范围明确、有效的 Skill。
  • 优化 Skill 描述——测试并改进 Skill 描述,让它在合适的 Prompt 下激活。
  • 格式规范——SKILL.md 文件的完整格式参考。
  • Skill 示例——在 GitHub 上浏览实际使用的 Skill。