为 GitHub Copilot 添加代理技能

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

在本文中

注意

代理技能与Copilot云代理、GitHub Copilot 命令行界面 (CLI)和Visual Studio Code中的代理模式一起工作。

代理技能是包含说明、脚本和资源的文件夹，当需要时，这些文件夹可以被加载，以提升其在专用任务中的性能。 有关详细信息，请参阅“关于代理技能”。

创建和添加技能

若要创建代理技能，您需要编写一个SKILL.md文件，并且可选择编写其他资源，例如补充 Markdown 文件或脚本，这些资源是在SKILL.md说明中引用的。

  1. 如果尚未这样做，请在以下位置之一 skills 中创建目录。 你可以在其中找到你的技能，以及将来可能想要创建的任何其他技能。

    对于特定于单个存储库的项目技能，请在存储库中创建.github/skills、.claude/skills或.agents/skills目录。

    对于个人技能，这些技能可以在项目之间共享，请在您的本地主目录中创建~/.copilot/skills、~/.claude/skills或~/.agents/skills目录。

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

    技能子目录名称应为小写，对空格使用连字符。

  3. 在技能子目录中，创建包含 SKILL.md 技能说明的文件。

    重要

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

           `SKILL.md` 文件是带有 YAML frontmatter 的 Markdown 文件。 在最简单的形式中，它们包括：
    • YAML 前页
      • 名称 （必需）：技能的唯一标识符。 这必须是小写的，对空格使用连字符。 通常，这与技能目录的名称匹配。
      • 说明 （必需）：描述技能的作用，以及何时 Copilot 应使用它。
      • 许可证 （可选）：适用于此技能的许可证的说明。
    • 针对 Copilot 的 Markdown 正文，其中包含需要遵循的说明、示例和指南。

  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 会移除运行终端命令的确认步骤，并可能允许攻击者控制的技能或提示注入在你的环境中执行任意命令。 在有疑虑时，请省略 shell 和 bash 自 allowed-tools，这样 Copilot 必须在运行终端命令之前请求您明确的确认。

  3.        **编写说明，说明 Copilot 如何使用脚本。** 在 Markdown 正文 `SKILL.md`中，描述脚本的运行时间和方式。

    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.

添加其他人创建的技能

除了创建自己的技能外，还可以添加其他人创建的技能。

提示

您也可以在GitHub CLI中使用gh skill来搜索、安装、更新和发布代理技能。 有关详细信息，请参阅“为 GitHub Copilot 添加代理技能”。

  1. 下载技能目录（即包含 SKILL.md 文件和（可选）其他文件和子目录的目录）。

    例如，从 Awesome GitHub Copilot 存储库下载技能： https://awesome-copilot.github.com/skills/。

  2. 如果下载了文件 .zip ，请解压缩该文件。

  3. 将技能目录移动到所需位置：

    • 对于单个存储库特定的项目技能：可以在.github/skills、.claude/skills或者.agents/skills之中选择。

    • 对于个人技能，可在项目~/.copilot/skills``~/.claude/skills之间共享，或~/.agents/skills在本地主目录中共享。

使用 GitHub CLI 管理技能

注意

          `gh skill` 位于 公共预览版，可能会有变动。 若要使用它，请更新 GitHub CLI 到版本 2.90.0 或更高版本。

可以在GitHub CLI中使用gh skill命令来发现、安装、更新和发布来自GitHub存储库的代理技能。

          `gh skill` 子命令的完整列表，请运行 `gh skill --help` 或查看 GitHub CLI 使用指南的 [`gh skill`](https://cli.github.com/manual/gh_skill) 部分。

安装技能

可以搜索技能、预览技能，并从GitHub 仓库安装技能。

警告

技能未经验证 GitHub ，可能包含提示注入、隐藏指令或恶意脚本。 在使用 gh skill preview 安装技能之前，请始终检查其内容。

  1. 按主题搜索技能：

    gh skill search TOPIC

  2. 在安装之前预览技能以查看和评估其内容。 这会在终端中显示技能的 SKILL.md 和文件树，而无需安装任何内容。

    gh skill preview OWNER/REPOSITORY SKILL

  3. 安装技能。 可以执行 gh skill install，无需参数以实现完全交互的流程，或指定存储库以交互方式浏览其技能。

    gh skill install OWNER/REPOSITORY

    直接安装某项特定技能：

    gh skill install OWNER/REPOSITORY SKILL

    例如，若要从 github/awesome-copilot 存储库安装技能，请执行以下操作：

    Shell
    gh skill install github/awesome-copilot documentation-writer

    可以使用 @TAG 或 @SHA 安装特定版本：

    Shell
    gh skill install github/awesome-copilot documentation-writer@v1.2.0

    若要将技能锁定到特定版本（或提交 SHA），以便在更新期间跳过它，请使用 --pin：

    Shell
    gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

    注意

    语法 @VERSION 和 --pin 标志互斥。 使用一个或另一个，而不是两者。

    若要为特定代理主机安装技能，请使用 --agent 标志。 若要控制安装范围，请使用 --scope：

    Shell
    gh skill install github/awesome-copilot documentation-writer --agent claude-code --scope user

技能会自动安装到代理主机的正确目录中。 默认情况下，技能被安装在 Copilot 的项目范围内。

更新技能

使用 gh skill 安装技能时，来源元数据将写入技能的 SKILL.md 头部信息，包括源存储库、ref 和树 SHA。 该 gh skill update 命令使用此元数据来检查上游更改。

若要以交互方式检查更新，请执行以下操作：

gh skill update

更新特定技能：

gh skill update SKILL

在不提示的情况下更新所有已安装的技能：

gh skill update --all

更新期间会跳过锁定的技能。 若要更新已固定的技能，请用新的 --pin 值重新安装该技能。

发布能力

如果维护技能存储库，则可以使用 GitHub CLI 验证和发布技能。

若要根据 代理技能规范 验证技能并检查远程设置（如标记保护、机密扫描和代码扫描）而不发布，请使用 --dry-run：

gh skill publish --dry-run

若要自动修复技能文件中的元数据问题，请使用 --fix。 这不会发布你的技能。

gh skill publish --fix

要验证并发布您的技能：

gh skill publish

如何使用 Copilot 的代理技能

执行任务时，Copilot 将根据您的提示和技能描述决定何时使用您的技能。

当 Copilot 选择使用某项技能时，SKILL.md 文件将注入智能体的上下文中，使智能体能够访问你的指令。 然后，它可以按照这些说明执行操作，并使用你在技能目录中包含的任何脚本或示例。

技能与自定义指令的对比

你可以同时使用技能和自定义指令，教 Copilot 如何在你的存储库中工作以及如何执行特定任务。

我们建议将自定义指令用作几乎与每个任务相关的简单指令（例如有关存储库编码标准的信息），将技能用于 Copilot 仅在相关时才应访问的更详细指令。

若要了解有关存储库自定义说明的详细信息，请参阅 为GitHub Copilot添加存储库自定义说明。