为 GitHub Copilot 创建代理技能

在 Copilot 处理特定任务时，您可以修改其行为和能力。

本文内容

注意

代理技能可在 Copilot 云代理、GitHub Copilot CLI 以及 Visual Studio Code 的代理模式中使用。

代理技能是包含指令、脚本和资源的文件夹，Copilot 在相关时可加载它们，以提升在专门任务中的表现。欲了解更多信息，请参阅 关于代理技能。

创建并添加技能

要创建代理技能，您需要编写一个 SKILL.md 文件，并可选择其他资源，如补充的 Markdown 文件或脚本，并在 SKILL.md 指令中引用它们。

要添加技能，需将 SKILL.md 文件及所有子资源保存到 Copilot 知道的技能搜索位置。可以是仓库内部，也可以是您的主目录。

  1. 在受支持的位置之一创建一个 skills 目录，用于存放您的技能以及未来可能创建的其他技能。

    对于 **项目技能**（针对单个仓库），请在仓库中创建并使用 .github/skills、.claude/skills 或 .agents/skills 目录。

    对于 **个人技能**（跨项目共享），请在您的主目录中创建并使用 ~/.copilot/skills、~/.claude/skills 或 ~/.agents/skills 目录。

  2. 为新技能创建子目录。每个技能应拥有独立的目录（例如 .github/skills/webapp-testing）。

    技能子目录名称应全部小写，并使用连字符表示空格。

  3. 在技能子目录中，创建一个包含技能指令的 SKILL.md 文件。

    重要提示

    技能文件必须命名为 SKILL.md。

    SKILL.md 文件是带有 YAML 前言的 Markdown 文件。最简形式包括

    • YAML 前置数据
      • name（必填）：技能的唯一标识符。必须小写，使用连字符表示空格。通常与技能目录的名称一致。
      • description（必填）：对技能作用以及 Copilot 何时使用它的描述。
      • license（可选）：适用于此技能的许可证说明。
    • Markdown 正文，包含 Copilot 应遵循的指令、示例和指南。

  4. 您也可以向技能目录中添加脚本、示例或其他资源。

    欲了解更多信息，请参阅 "启用技能运行脚本。"

示例 SKILL.md 文件

**项目技能** 的情况下，此文件位于仓库中的 .github/skills/github-actions-failure-debugging 目录下。

**个人技能** 的情况下，此文件位于 ~/.copilot/skills/github-actions-failure-debugging 目录中。

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

To debug failing GitHub Actions workflows in a pull request, follow this process, using tools provided from the GitHub MCP Server:

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, to understand what went wrong without filling your context windows with thousands of lines of logs
3. If you still need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full, detailed failure logs
4. Try to reproduce the failure yourself in your own environment.
5. Fix the failing build. If you were able to reproduce the failure yourself, make sure it is fixed before committing your changes.

启用技能运行脚本

当调用技能时，Copilot 会自动发现技能目录中的所有文件，并将它们与技能指令一起提供。这意味着您可以在技能目录中包含脚本或其他资源，并在 SKILL.md 指令中引用它们。

创建可运行脚本的技能

  1. 将脚本添加到技能目录中。例如，一个将 SVG 图像转换为 PNG 的技能可能具有以下结构。

    .github/skills/image-convert/
├── SKILL.md
└── convert-svg-to-png.sh

  2. 可选地预先批准技能所需的工具。在 SKILL.md 前言中，您可以使用 allowed-tools 字段列出 Copilot 可直接使用而无需每次确认的工具。若工具未在 allowed-tools 中列出，Copilot 会在使用前提示您授权。

    ---
name: image-convert
description: Converts SVG images to PNG format. Use when asked to convert SVG files.
allowed-tools: shell
---

    警告

    仅当您已审查该技能及其引用的脚本，并完全信任其来源时，才预先批准 shell 或 bash 工具。预先批准 shell 或 bash 会省略运行终端命令的确认步骤，可能导致攻击者控制的技能或提示注入在您的环境中执行任意命令。如有疑虑，请在 allowed-tools 中省略 shell 与 bash，以确保 Copilot 在运行终端命令前必须获得您的明确确认。

  3. 编写指令告诉 Copilot 如何使用脚本。在 SKILL.md 的 Markdown 正文中，说明何时以及如何运行该脚本。

    When asked to convert an SVG to PNG, run the `convert-svg-to-png.sh` script
from this skill's base directory, passing the input SVG file path as the
first argument.

Copilot 如何使用代理技能

在执行任务时，Copilot 会根据您的提示以及技能描述决定何时使用您的技能。

当 Copilot 选择使用某个技能时，SKILL.md 文件会注入到代理的上下文中，使代理能够访问您的指令。随后它即可遵循这些指令，并使用您在技能目录中包含的任何脚本或示例。

技能 vs 自定义指令

您可以同时使用技能和自定义指令来教会 Copilot 如何在您的仓库中工作以及如何完成特定任务。

我们建议将 自定义指令 用于几乎每个任务都相关的简单指令（例如仓库的编码规范信息），而将 技能 用于更详细的指令，Copilot 只在相关时才会访问。

欲了解更多关于仓库自定义指令的信息，请参阅 为 GitHub Copilot 添加仓库自定义指令。

© . This site is unofficial and not affiliated with GitHub, Inc.