在 VS Code 中使用 Agent Skills

Agent Skills 是包含指令、脚本和资源的文件夹，GitHub Copilot 可以在相关时加载这些文件夹来执行专门的任务。Agent Skills 是一项开放标准，适用于多种 AI 智能体，包括 VS Code 中的 GitHub Copilot、GitHub Copilot CLI 以及 GitHub Copilot 云智能体。

与主要定义编码准则的自定义指令不同，技能支持专门的功能和工作流程，其中可以包含脚本、示例和其他资源。您创建的技能具有可移植性，可在任何兼容该技能的智能体中使用。

Agent Skills 的主要优势

• 专门化 Copilot：针对特定领域的任务定制功能，而无需重复上下文
• 减少重复：一次创建，在所有对话中自动使用
• 组合功能：结合多种技能来构建复杂的工作流程
• 高效加载：仅在需要时将相关内容加载到上下文中

Agent Skills 与自定义指令 (custom instructions) 的区别

虽然 Agent Skills 和自定义指令都有助于自定义 Copilot 的行为，但它们的服务目的不同

当您想执行以下操作时，请使用 Agent Skills：

• 创建可在不同 AI 工具中使用的可复用功能
• 在指令之外包含脚本、示例或其他资源
• 与更广泛的 AI 社区共享功能
• 定义专门的工作流程，如测试、调试或部署流程

当您想执行以下操作时，请使用自定义指令：

• 定义特定于项目的编码标准
• 设置语言或框架约定
• 指定代码审查或提交消息准则
• 使用 glob 模式根据文件类型应用规则

创建技能 (skill)

技能存储在包含 SKILL.md 文件的目录中，该文件定义了技能的行为。VS Code 支持两种类型的技能：

您可以使用 chat.agentSkillsLocations 在 VS Code 中打开 在 VS Code Insiders 中打开 设置为项目技能配置额外的文件位置。如果您想以不同的文件夹结构组织技能，或拥有多个技能目录，此功能非常有用。

创建技能的步骤：

1. 在“聊天”视图中，选择配置聊天 (Configure Chat)（齿轮图标）以打开“智能体自定义”编辑器，然后选择技能 (Skills) 选项卡。

2. 根据您想要存储技能的位置，从下拉菜单中选择新建技能 (工作区) 或新建技能 (用户)。

   

3. 选择位置并为该技能输入名称。

4. 填写 YAML frontmatter 并在此文件正文中添加指令，以完成 SKILL.md 文件。

   ---
   name: skill-name
   description: Description of what the skill does and when to use it
   ---
   
   # Skill Instructions
   
   Your detailed instructions, guidelines, and examples go here...
   

5. 可选：向技能目录中添加脚本、示例或其他资源。

   例如，用于测试 Web 应用的技能可能包括：

   • SKILL.md - 运行测试的说明
   • test-template.js - 测试文件模板
   • examples/ - 测试场景示例
   注意

   请确保在 SKILL.md 中引用任何附加文件，以便智能体能够识别它们。使用 Markdown 链接语法和相对路径，例如 [test template](./test-template.js)。

使用 AI 生成技能

您可以根据功能描述使用 AI 生成技能。在聊天中输入 /create-skill 并描述您想要的技能（例如：“一个用于运行和调试集成测试的技能”）。智能体会提出澄清性问题，并生成一个包含目录结构、说明和 frontmatter 的 SKILL.md 文件。

您也可以从正在进行的对话中提取可复用的技能。例如，在调试复杂问题并经过多轮对话后，询问“根据我们刚才调试的方法创建一个技能”，即可将该多步骤流程捕获为可复用的技能。

您也可以通过在“智能体自定义”编辑器中从下拉菜单选择生成技能 (Generate Skill) 来生成技能。

SKILL.md 文件格式

SKILL.md 是一个带有 YAML frontmatter 的 Markdown 文件，用于定义技能的元数据和行为。

头部（必需）

头部格式为 YAML frontmatter，包含以下字段

正文

技能正文包含 Copilot 在使用该技能时应遵循的指令、准则和示例。请编写清晰、具体的说明，描述：

• 该技能有助于完成什么任务
• 何时使用该技能
• 需遵循的逐步流程
• 预期输入和输出的示例
• 对任何已包含的脚本或资源的引用

您可以使用相对路径引用技能目录中的文件。例如，要引用技能目录中的脚本，请使用 [test script](./test-template.js)。

在分叉上下文中运行技能（实验性）

默认情况下，当 VS Code 加载技能时，技能的指令会被添加到父智能体的上下文窗口中。对于大型技能，或中间推理过程与对话其余部分无关的技能，您可以改为在分叉上下文 (forked context) 中运行。在分叉上下文中，技能在一个专用的子智能体中执行，仅将其最终结果返回给父智能体。这可以保持主对话上下文的整洁。

要在分叉上下文中运行技能，请将 SKILL.md frontmatter 中的 context 字段设置为 fork

---
name: review-pr
description: Review a pull request for code quality, style, and correctness. Use when asked to review a PR.
context: fork
---

# PR review

Follow these steps to review the pull request...

对于以下情况，请使用 context: fork：

• 读取大量文件或运行漫长的调查，其细节无需保留在主对话中
• 产生聚焦的结果（如摘要、报告或少量编辑），且父智能体可以直接基于此结果采取行动
• 不应影响父智能体最终输出之外的行为

技能示例

以下示例演示了您可以创建的不同类型的技能。

---
name: webapp-testing
description: Guide for testing web applications using Playwright. Use this when asked to create or run browser-based tests.
---

# Web Application Testing with Playwright

This skill helps you create and run browser-based tests for web applications using Playwright.

## When to use this skill

Use this skill when you need to:
- Create new Playwright tests for web applications
- Debug failing browser tests
- Set up test infrastructure for a new project

## Creating tests

1. Review the [test template](./test-template.js) for the standard test structure
2. Identify the user flow to test
3. Create a new test file in the `tests/` directory
4. Use Playwright's locators to find elements (prefer role-based selectors)
5. Add assertions to verify expected behavior

## Running tests

To run tests locally:
```bash
npx playwright test
```

To debug tests:
```bash
npx playwright test --debug
```

## Best practices

- Use data-testid attributes for dynamic content
- Keep tests independent and atomic
- Use Page Object Model for complex pages
- Take screenshots on failure

---
name: github-actions-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
---

# GitHub Actions Debugging

This skill helps you debug failing GitHub Actions workflows in pull requests.

## Process

1. Use the `list_workflow_runs` tool to look up recent workflow runs for the pull request and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of the logs for failed jobs
3. If you need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full failure logs
4. Try to reproduce the failure locally in your environment
5. Fix the failing build and verify the fix before committing changes

## Common issues

- **Missing environment variables**: Check that all required secrets are configured
- **Version mismatches**: Verify action versions and dependencies are compatible
- **Permission issues**: Ensure the workflow has the necessary permissions
- **Timeout issues**: Consider splitting long-running jobs or increasing timeout values

将技能用作斜杠命令

技能作为聊天中的斜杠命令提供，与提示文件 (prompt files) 并列。在聊天输入框中输入 / 即可查看可用技能和提示列表，选择技能即可调用它。

您可以在斜杠命令后添加额外上下文。例如 /webapp-testing for the login page 或 /github-actions-debugging PR #42。

默认情况下，所有技能都会出现在 / 菜单中。使用 user-invocable 和 disable-model-invocation frontmatter 属性来控制每个技能的访问方式：

Copilot 如何使用技能

技能会逐步加载内容以保持您的上下文高效。以下是 Copilot 如何使用 webapp-testing 技能的示例：

1. 发现：Copilot 从 YAML frontmatter 中读取技能的 name 和 description。当您询问“帮助我测试登录页面”时，Copilot 根据描述将其匹配到 webapp-testing 技能。

2. 加载指令：Copilot 将 SKILL.md 正文加载到上下文中，使其能够访问详细的测试流程和准则。您也可以通过在聊天中输入 /webapp-testing 直接触发此步骤。

3. 资源访问：当 Copilot 执行指令时，它仅在引用技能目录中的附加文件（例如 test-template.js 或示例场景）时才会访问它们。如果文件中未引用该资源，则不会被加载。

这种三级加载系统意味着您可以安装许多技能而不会耗尽上下文。Copilot 仅加载与每项任务相关的内容。

选择加入分叉上下文的技能遵循相同的发现步骤，但它们的指令及其读取的任何文件都会加载到单独的子智能体中。仅将技能的最终结果返回给父智能体。

使用共享技能

您可以使用他人创建的技能来增强 Copilot 的功能。github/awesome-copilot 仓库包含一个不断增长的社区技能、自定义智能体、指令和提示合集。anthropics/skills 仓库包含额外的参考技能。

您还可以发现并安装捆绑在智能体插件中的技能。来自已安装插件的技能会与您本地定义的技能一起出现在配置技能 (Configure Skills) 菜单中。

使用共享技能的步骤：

1. 浏览仓库中可用的技能
2. 将技能目录复制到您的 .github/skills/ 文件夹中
3. 根据您的需要审查并自定义 SKILL.md 文件
4. 可选：根据需要修改或添加资源

从扩展中贡献技能

扩展程序可以使用其 package.json 中的 chatSkills 贡献点来贡献技能。路径必须指向一个包含 SKILL.md 文件的目录，并遵循 Agent Skills 规范。

必需的文件夹结构

技能目录必须遵循此结构

extension-root/
└── skills/
    └── my-skill/           # Directory name must match the `name` field in SKILL.md
        └── SKILL.md         # Required

在 package.json 中注册技能

在扩展的 package.json 中添加 chatSkills 贡献点。path 属性必须指向相应的 SKILL.md 文件

{
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/my-skill/SKILL.md"
      }
    ]
  }
}

SKILL.md 文件遵循与项目和个人技能相同的格式。例如：

---
name: my-skill
description: Description of what the skill does and when to use it.
---

# My Skill

Detailed instructions for the skill...

Agent Skills 标准

Agent Skills 是一项开放标准，可在不同的 AI 智能体之间实现可移植性。您在 VS Code 中创建的技能适用于多种智能体，包括：

• VS Code 中的 GitHub Copilot：在聊天和智能体模式下可用
• GitHub Copilot CLI：在终端工作时可访问
• GitHub Copilot 云智能体：在自动编码任务期间使用

通过 agentskills.io 了解有关 Agent Skills 标准的更多信息。

相关资源

• 自定义 AI 响应概述
• 创建自定义指令
• 创建可重用的提示文件
• 创建自定义代理
• Agent Skills 规范
• 参考技能仓库
• 发现和管理代理插件