> ## Documentation Index
> Fetch the complete documentation index at: https://agent-skills.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

> 创建你的第一个 Agent 技能并在 VS Code 中查看其效果。

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

## 前提条件

* 安装了 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 的 [VS Code](https://code.visualstudio.com/)

<Note>
  本教程使用 VS Code，但 Agent 技能是一种开放格式。相同的技能可在任何兼容的 Agent 中工作，包括 Claude Code 和 OpenAI Codex。
</Note>

## 创建技能

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

````markdown .agents/skills/roll-dice/SKILL.md theme={null}
---
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`** — 技能的简短标识符。必须与文件夹名称匹配。
* **`description`** — 告诉 Agent 何时使用此技能。这是 Agent 决定是否激活它的方式。
* **主体** — 技能激活时 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` 技能。它可能会请求运行终端命令的权限 —— 允许它。它将运行命令并返回 1 到 20 之间的随机数。

<Note>
  工具使用的可靠性因模型而异 —— 有些模型会遵循技能指令并一致地运行命令，而另一些模型可能会尝试自行回答。如果 Agent 在没有运行终端命令的情况下响应，请尝试从模型下拉菜单中选择不同的模型。
</Note>

## 工作原理

以下是幕后发生的事情：

1. **发现** — 当聊天会话开始时，Agent 扫描了默认技能目录并找到了你的技能。它只读取了 `name` 和 `description`，足以知道技能何时可能相关。
2. **激活** — 当你询问掷骰子时，Agent 将你的问题与技能描述匹配，并将完整的 `SKILL.md` 主体加载到上下文中。
3. **执行** — Agent 遵循主体中的指令，根据你请求中的面数调整终端命令。

此过程使用 **渐进式披露** 让 Agent 访问许多技能，而无需预先加载所有指令。有关更多详细信息，请参阅 [技能如何工作](/what-are-skills#how-skills-work)。

## 后续步骤

此过程使用 **渐进式披露**，使 Agent 能够访问许多技能，而无需预先加载它们的所有指令。

* **[最佳实践](/skill-creation/best-practices)** — 如何编写范围明确且有效的技能。
* **[优化技能描述](/skill-creation/optimizing-descriptions)** — 测试并改进你的技能描述，以便它在正确的提示下激活。
* **[规范](/specification)** — `SKILL.md` 文件的完整格式参考。
* **[示例技能](https://github.com/anthropics/skills)** — 在 GitHub 上浏览真实世界的技能。