在 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 与自定义指令

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

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

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

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

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

创建技能

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

• 项目技能，存储在您的存储库中：.github/skills/（推荐）或 .claude/skills/（遗留，向后兼容）
• 个人技能，存储在您的用户配置文件中：~/.copilot/skills/（推荐）或 ~/.claude/skills/（遗留，向后兼容）

要创建技能

1. 在您的工作区中创建 .github/skills 目录。

2. 为您的技能创建一个子目录。每个技能应有自己的目录（例如 .github/skills/webapp-testing）。

3. 在技能目录中创建一个 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...
   

4. 可以选择将脚本、示例或其他资源添加到技能目录中。

   例如，一个用于测试 Web 应用程序的技能可能包含

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

SKILL.md 文件格式

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

Header（必需）

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

正文

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

• 该技能有助于实现什么
• 何时使用该技能
• 要遵循的分步说明
• 预期的输入和输出示例
• 对任何包含的脚本或资源的引用

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

示例技能

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

---
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

Copilot 如何使用技能

技能使用渐进式披露来高效地仅在需要时加载内容。这种三级加载系统可确保您可以安装许多技能而不会占用上下文

级别 1：技能发现

通过读取 YAML frontmatter 中的name和description，Copilot 始终知道哪些技能可用。这些元数据很轻量，有助于 Copilot 决定哪些技能与您的请求相关。

级别 2：指令加载

当您的请求与技能的描述匹配时，Copilot 会将其SKILL.md文件主体加载到其上下文中。只有那时，详细的说明才可用。

级别 3：资源访问

Copilot 仅在需要时才能访问技能目录中的其他文件（脚本、示例、文档）。这些资源在 Copilot 引用它们之前不会加载，从而保持上下文的高效性。

这种架构意味着技能是根据您的提示自动激活的——您无需手动选择它们。您可以安装许多技能，Copilot 只会为每项任务加载相关的内容。

使用共享技能

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

要使用共享技能

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

Agent Skills 标准

Agent Skills 是一个开放标准，支持在不同 AI 代理之间可移植。您在 VS Code 中创建的技能可用于多个代理，包括

• VS Code 中的 GitHub Copilot：可在聊天和代理模式下使用
• GitHub Copilot CLI：在终端工作时可访问
• GitHub Copilot 编码代理：在自动化编码任务中使用

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

相关资源

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