第四节：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.hbs3.3 Frontmatter 字段详解Frontmatter 使用 YAML 格式位于SKILL.md文件开头用三个短横线---包裹。name必需属性说明类型string用途技能的唯一标识符约束必须小写对空格使用连字符通常与技能目录名称一致示例name:github-actions-debuggingdescription必需属性说明类型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:MITtreeSHA自动管理可选属性说明类型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 skillinstallgithub/awesome-copilot# 直接安装特定技能gh skillinstallgithub/awesome-copilot documentation-writer# 安装指定版本使用 taggh skillinstallgithub/awesome-copilot documentation-writerv1.2.0# 安装指定 commit最大程度可复现gh skillinstallgithub/awesome-copilot documentation-writerabc123def5.2 搜索技能# 搜索与 MCP 相关的技能gh skill search mcp-apps5.3 版本锁定安全追溯# 锁定到特定版本gh skillinstallgithub/awesome-copilot documentation-writer--pinv1.2.0# 锁定到特定 commit最大可复现性gh skillinstallgithub/awesome-copilot documentation-writer--pinabc123def锁定后的技能在执行gh skill update时会被跳过确保你不会意外升级到未经测试的版本。六、Agent Skills vs. 其他配置——完整对比至此你已经了解了 Copilot 的全部核心定制化功能。下表从多个维度做了完整对比维度InstructionsAgentPromptAgent Skills本质员工手册专业角色任务流程卡专家工具箱触发方式常时自动手动选择手动命令自然语言自动是否可携带脚本❌❌❌✅是否可携带资源❌❌❌✅跨平台兼容有限有限有限✅ 开放标准典型用途编码规范、架构原则多步骤复杂任务标准化重复任务模板化、脚本化的专业任务使用建议Instructions团队编码规范和架构原则Agent需要专门权限和上下文的复杂任务Prompt标准化、可交互的单次任务Agent Skills需要同捆脚本、模板的专业化任务且希望跨项目/跨平台复用七、参考资料GitHub Docs: About agent skillsGitHub Docs: Adding agent skills for GitHub CopilotGitHub Docs: Creating agent skills for GitHub Copilot CLIGitHub Docs: Copilot customization cheat sheetGitHub Blog: Manage agent skills with GitHub CLIGitHub Community Discussion: Customizing which Agent Skills Copilot uses