第四节：Agent Skills——AI可执行的专业能力包
一、什么是 Agent Skills？
在前三节中，你已经学会了用 Instructions 定义全局规则、用 Agent 创建专业角色、用 Prompt 固化任务模板。但所有这些配置都有一个共同的限制：它们只能包含“文字指令”，无法携带脚本、模板或可执行资源。
Agent Skills 正是为了突破这一限制而生的。它允许你在指令文件夹中附带脚本、模板和任何辅助资源，让 AI 不仅能“知道怎么做”，还能“实际做到”。
💡 官方定义：Agent Skills 是指令、脚本和资源的文件夹，Copilot 可以在相关任务中加载它们，以提升其在专业任务中的性能。Agent Skills 规范是一个开放标准，被 GitHub Copilot、Claude Code、Cursor、Codex、Gemini CLI 等多种 AI 系统共同采用。
如果把前三节的配置体系比作“员工手册”（Instructions）、“特种兵编制”（Agent）和“操作指令卡”（Prompt），那么 Agent Skills 就是“携带工具箱的专家”——它不仅知道该怎么做，还带来了完成工作所需的全部工具。
二、Agent Skills 的核心特性
2.1 超越纯文本：可以携带资源
与其他配置文件的根本区别在于，Agent Skills 可以在指令文件夹中同捆包含脚本、示例代码、模板文件等资源，AI 在执行任务时可以直接使用它们。
| 配置类型 | 可携带脚本 | 可携带资源 | 触发方式 |
|---|---|---|---|
| Instructions | ❌ | ❌ | 常时自动 |
| Prompt | ❌ | ❌ | 手动 / 命令 |
| Agent | ❌ | ❌ | 手动选择 |
| Agent Skills | ✅ | ✅ | 自然语言自动触发 |
💡 理解区别：如果你只是想让 AI “知道如何测试”，用 Prompt 就够了。但如果你想让 AI 在测试时使用你写的测试模板、调用某个脚本、遵循参考样例，那就需要 Agent Skills。
2.2 自动发现与加载
当你输入自然语言提示时，Copilot 会根据技能目录中 SKILL.md 文件的 description 字段来判断是否应该加载某个技能。匹配成功后，它会将该技能的所有指令和资源注入到当前任务的上下文中。
2.3 跨平台兼容
由于 Agent Skills 遵循开放规范，同一个技能文件夹可以在 GitHub Copilot、Claude Code、Cursor、Gemini CLI、Codex 等多种 AI 工具中无缝使用。这意味着你一次编写，随处使用。
三、SKILL.md 文件结构与 Frontmatter 详解
Agent Skills 的核心是 SKILL.md 文件。它是一个带有 YAML Frontmatter 的 Markdown 文件，命名固定，大小写敏感。
3.1 存放位置（两种作用域）
Agent Skills 可以存放在两个层级，决定其作用范围。
| 类型 | 存放路径 | 作用范围 |
|---|---|---|
| 项目技能 | .github/skills/<skill-name>/ |
仅对当前仓库生效，随仓库共享 |
| 个人技能 | ~/.copilot/skills/<skill-name>/ |
跨项目生效，仅限当前用户 |
📝 推荐：项目技能使用
.github/skills/路径，这是 GitHub 官方推荐的做法。.claude/skills/和.agents/skills/也受支持，用于兼容旧配置。
3.2 目录结构
每个技能是一个独立目录，名称必须小写，单词之间使用连字符（-），建议不超过 64 个字符。
.github/skills/
└── test-automation/ # 技能名：小写，连字符分隔
├── SKILL.md # 必需：技能定义文件
├── scripts/ # 可选：辅助脚本
│ └── setup-test-env.sh
├── references/ # 可选：参考文档
│ └── api-spec.md
├── examples/ # 可选：实现示例
│ └── sample-test.spec.ts
└── assets/ # 可选：模板、图表等
└── test-template.spec.hbs
3.3 Frontmatter 字段详解
Frontmatter 使用 YAML 格式，位于 SKILL.md 文件开头，用三个短横线 --- 包裹。
name（必需）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 技能的唯一标识符 |
| 约束 | 必须小写，对空格使用连字符，通常与技能目录名称一致 |
示例：
name: "github-actions-debugging"
description（必需）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 描述技能的功能和适用场景，Copilot 根据此字段判断是否加载该技能 |
| 长度建议 | 20-300 字符，越精确越好 |
示例：
description: "Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows."
license（可选）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 说明适用于该技能的许可证信息 |
示例：
license: "MIT"
treeSHA（自动管理，可选）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 由 gh skill install 自动写入，用于版本追踪和变更检测 |
| 长度 | 40 字符（Git commit SHA） |
💡 提示：使用
gh skill命令安装技能时，工具会自动在 Frontmatter 中写入treeSHA、repository、ref等追踪元数据，实现版本锁定和来源可追溯。手动创建的技能可以省略此字段。
3.4 Markdown 内容体
Frontmatter 下方是 Markdown 格式的技能指令。Copilot 加载技能时，会完整读取此部分并遵循其中的指引。
一份优秀的技能指令应包括：
- 任务目标：明确说明技能要解决什么问题
- 执行步骤：按顺序列出的具体操作步骤
- 可用资源：技能目录中包含的脚本、模板等资源及其使用方式
- 约束边界：技能不应该做什么，或需要用户确认后才能执行的操作
四、完整实战示例：github-actions-debugging 技能
下面是一个完整的 Agent Skills 示例，用于调试 GitHub Actions 工作流失败问题。
---
name: "github-actions-debugging"
description: "Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows."
license: "MIT"
---
# GitHub Actions 工作流调试指南
当用户要求调试失败的 GitHub Actions 工作流时，请按照以下步骤执行。
## 执行步骤
1. **获取工作流运行记录**
使用 `list_workflow_runs` 工具查找指定 PR 的近期工作流运行记录及其状态。
2. **分析失败日志摘要**
使用 `summarize_job_log_failures` 工具获取失败作业的 AI 摘要日志，在理解问题原因的同时，避免用数千行完整日志填满上下文窗口。
3. **按需获取详细日志**
若仍需更多信息，使用 `get_job_logs` 或 `get_workflow_run_logs` 工具获取完整的失败日志。
4. **本地复现问题**
在自己的环境中尝试复现失败现象。
5. **修复问题**
修复失败的构建。如果能够成功复现失败，确保修复完成后再提交更改。
## 可用的 MCP 工具
本技能需要使用 GitHub MCP Server 提供的以下工具：
- `list_workflow_runs`：列出工作流运行
- `summarize_job_log_failures`：分析失败日志
- `get_job_logs` / `get_workflow_run_logs`：获取完整日志
## 约束
- 只有在用户明确要求调试 GitHub Actions 工作流时，才加载本技能
- 在执行任何写入操作前，确认修复方案的正确性
五、使用 gh skill 命令管理技能
GitHub CLI 提供了 gh skill 命令，用于发现、安装、管理和发布 Agent Skills。
5.1 安装与更新
# 更新 GitHub CLI 到 v2.90.0 或更高版本
gh --version
# 交互式浏览并安装技能
gh skill install github/awesome-copilot
# 直接安装特定技能
gh skill install github/awesome-copilot documentation-writer
# 安装指定版本（使用 tag）
gh skill install github/awesome-copilot documentation-writer@v1.2.0
# 安装指定 commit（最大程度可复现）
gh skill install github/awesome-copilot documentation-writer@abc123def
5.2 搜索技能
# 搜索与 MCP 相关的技能
gh skill search mcp-apps
5.3 版本锁定（安全追溯）
# 锁定到特定版本
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0
# 锁定到特定 commit（最大可复现性）
gh skill install github/awesome-copilot documentation-writer --pin abc123def
锁定后的技能在执行 gh skill update 时会被跳过，确保你不会意外升级到未经测试的版本。
六、Agent Skills vs. 其他配置——完整对比
至此，你已经了解了 Copilot 的全部核心定制化功能。下表从多个维度做了完整对比：
| 维度 | Instructions | Agent | Prompt | Agent Skills |
|---|---|---|---|---|
| 本质 | 员工手册 | 专业角色 | 任务流程卡 | 专家工具箱 |
| 触发方式 | 常时自动 | 手动选择 | 手动命令 | 自然语言自动 |
| 是否可携带脚本 | ❌ | ❌ | ❌ | ✅ |
| 是否可携带资源 | ❌ | ❌ | ❌ | ✅ |
| 跨平台兼容 | 有限 | 有限 | 有限 | ✅ 开放标准 |
| 典型用途 | 编码规范、架构原则 | 多步骤复杂任务 | 标准化重复任务 | 模板化、脚本化的专业任务 |
使用建议：
- Instructions：团队编码规范和架构原则
- Agent：需要专门权限和上下文的复杂任务
- Prompt：标准化、可交互的单次任务
- Agent Skills：需要同捆脚本、模板的专业化任务，且希望跨项目/跨平台复用
七、参考资料
- GitHub Docs: About agent skills
- GitHub Docs: Adding agent skills for GitHub Copilot
- GitHub Docs: Creating agent skills for GitHub Copilot CLI
- GitHub Docs: Copilot customization cheat sheet
- GitHub Blog: Manage agent skills with GitHub CLI
- GitHub Community Discussion: Customizing which Agent Skills Copilot uses
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
10
0- 0
已为社区贡献58条内容
所有评论(0)