为 GitHub Copilot CLI 创建代理技能

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

创建和添加技能

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

要添加技能，只需将 SKILL.md 文件及其所有子资源保存到 Copilot 能够搜索到的路径中。该路径可以是仓库内部，也可以是您的主目录。

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

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

对于 **个人技能**（跨项目共享），请在主目录中创建并使用 ~/.copilot/skills、~/.claude/skills 或 ~/.agents/skills 目录。
为您的新技能创建子目录。每个技能应该拥有自己的目录（例如 .github/skills/webapp-testing）。

技能子目录名称应全部小写，使用连字符（-）替代空格。
在技能子目录中，创建一个包含该技能指令的 SKILL.md 文件。

重要提示

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

SKILL.md 文件是带有 YAML frontmatter 的 Markdown 文件。最简形式包括以下内容：
- YAML 前置数据
  - name（必填）：技能的唯一标识符。必须全部小写，使用连字符表示空格。通常与技能目录名相同。
  - description（必填）：对技能功能以及 Copilot 何时应使用该技能的描述。
  - license（可选）：适用于该技能的许可证说明。
- Markdown 正文，包含 Copilot 应遵循的指令、示例和指南。
可选地，向技能目录中添加脚本、示例或其他资源。

有关更多信息，请参阅 “启用技能运行脚本”。

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.

---
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 指令中引用它们。

创建运行脚本的技能

将脚本添加到技能目录中。例如，将 SVG 转换为 PNG 的技能可能具有如下结构。
```
.github/skills/image-convert/
├── SKILL.md
└── convert-svg-to-png.sh
```
可选地预先批准技能所需的工具。在 SKILL.md 的 frontmatter 中，您可以使用 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 必须在运行终端命令前征得您的明确确认。

编写指令，告诉 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 选择使用某个技能时，SKILL.md 文件会被注入到代理的上下文中，从而让代理能够访问您的指令。随后它会遵循这些指令，并使用您在技能目录中包含的任何脚本或示例。

若想让 Copilot 使用特定技能，只需在提示中加入技能名称并在前面加上斜杠。例如，若您有名为 “frontend-design” 的技能，可以使用如下提示：

Use the /frontend-design skill to create a responsive navigation bar in React.

CLI 中的技能命令

列出当前可用的技能：使用命令 /skills list 或在提示中输入相应内容。
```
What skills do you have?
```
启用或禁用特定技能：使用命令 /skills，随后使用键盘的上下键以及空格键来切换技能的开关状态。
了解某个技能的更多信息（包括其所在位置）：使用命令 /skills info。
添加技能存放位置：若要添加备用的技能存放路径，请使用命令 /skills add。
重新加载技能：如果您在一次 CLI 会话中新增了技能，可以使用命令 /skills reload 来刷新，而无需重启 CLI。
移除技能：若要删除您直接添加的（非通过插件）的技能，请使用命令 /skills remove SKILL-DIRECTORY。若技能是通过插件提供的，则必须管理对应的插件本身。使用 info 子命令可查看该技能来源于哪个插件。

技能与自定义指令的对比

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

我们建议将 **自定义指令** 用于几乎所有任务都会用到的简单说明（例如仓库的编码规范），而将 **技能** 用于更为细致、只有在相关时才需要访问的指令。

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

想了解技能与其他自定义功能的区别，请参阅比较 GitHub Copilot CLI 的自定义功能。