GitHub Copilot 自定义扩展实战：Instructions、Prompt Files、Agents 和 Hooks 怎么用

前言

默认状态下的 GitHub Copilot 已经能完成很多开发辅助工作，比如补代码、解释函数、生成测试、分析报错。但只靠默认配置，很容易遇到一个问题：Copilot 不知道你的项目习惯。

同样是 Next.js 项目，有的团队要求所有数据读取走 Server Actions，有的团队要求保留 API Routes；同样是测试，有的项目用 Vitest，有的项目用 Jest；同样是错误处理，有的项目返回统一错误对象，有的项目直接抛异常。Copilot 如果不知道这些约定，就会给出一段看起来能用、但和项目风格不一致的代码。

GitHub 现在已经把 Copilot 的自定义能力整理成一套比较完整的体系。官方 customization cheat sheet 中列出的能力包括 custom instructions、prompt files、custom agents、subagents、agent skills 和 hooks。它们分别对应不同层级的定制：指令负责长期规则，提示词负责重复任务，代理负责专业角色，hooks 负责执行前后的安全与自动化控制。

我更推荐按这个顺序理解：先让 Copilot 知道项目规矩，再把常用任务做成可复用提示词，复杂任务交给专门代理，涉及安全和合规的执行动作再交给 Hooks 拦截。

一、自定义指令：先把项目规则放进仓库

自定义指令是最容易落地的一层。

GitHub Docs 里写得很清楚，仓库级 custom instructions 可以给 Copilot 提供项目上下文，帮助它理解项目如何构建、测试和验证。仓库级文件放在 .github/copilot-instructions.md，会作为 repository-wide instructions 应用到仓库上下文中的请求。路径级指令放在 .github/instructions/*.instructions.md，通过 applyTo 指定适用文件范围。

一个 Next.js 项目的 .github/copilot-instructions.md 可以这样写：

markdown 复制代码

# Project rules

- This project uses Next.js App Router.
- Prefer Server Components unless interactivity requires Client Components.
- Use Server Actions for form submissions.
- Use Zod to validate external input.
- Keep API response shape compatible with existing clients.
- Do not introduce a new state management library unless explicitly requested.
- After changing business logic, update or add tests in the related test folder.

这类指令不需要写得像制度文件。越接近真实开发约束，效果越好。

如果某些规则只适用于特定文件，可以拆到 path-specific instructions。

markdown 复制代码

---
applyTo: "**/*.ts,**/*.tsx"
---

- Use explicit return types for exported functions.
- Avoid `any`; use `unknown` with narrowing when input type is uncertain.
- Keep React components small and move business logic into separate functions.

GitHub CLI 相关文档里也提到，applyTo 可以使用 glob 语法，例如 **/*.ts,**/*.tsx，匹配后会和仓库级指令一起生效；文档也提醒，指令之间尽量不要冲突，因为 Copilot 面对冲突指令时选择结果可能不稳定。

这里有一个实践经验：不要写"写高质量代码""遵循最佳实践"这种宽泛句子。Copilot 很难从这类表达里得到明确约束。

更好的写法是：

markdown 复制代码

- Functions longer than about 40 lines should be split into named helper functions.
- Database access must go through `src/lib/db.ts`.
- Payment status changes must write an audit log entry.
- Do not modify migration files unless the prompt explicitly asks for schema changes.

这些规则有明确行为边界。Copilot 更容易执行，代码审查时也更容易判断它有没有遵守。

二、Prompt Files：把重复任务做成团队模板

自定义指令适合长期规则，Prompt files 更适合重复任务。

GitHub Docs 对 prompt files 的定义很直接：它们是可复用的提示词文件，保存为 Markdown，并放在工作区里，用来封装常见开发任务。Prompt files 目前仍处于 public preview，支持范围主要是 VS Code、Visual Studio 和 JetBrains IDEs。

在支持的 IDE 里，prompt file 通常放在：

text 复制代码

.github/prompts/

文件名以 .prompt.md 结尾。

例如可以创建一个 review-api.prompt.md：

markdown 复制代码

Review the selected API implementation.

Focus on:
- input validation
- authentication and authorization
- error response compatibility
- database transaction boundaries
- missing tests

Return:
- critical issues first
- then suggested improvements
- then test cases that should be added

这样团队成员不需要每次都重新写一大段审查要求。需要做 API 审查时，直接调用这个 prompt file，再附上相关文件即可。

GitHub Docs 也提到，prompt files 可以引用工作区里的其他文件，可以通过 Markdown 链接或 #file: 语法提供额外上下文，例如 API 规范、产品文档或相关源文件。

这点很适合团队协作。比如你可以把接口规范、错误码文档、数据库约束一起挂进去：

markdown 复制代码

Review the implementation against these references:

- #file:../../docs/api-error-format.md
- #file:../../docs/auth-rules.md
- #file:../../prisma/schema.prisma

Check whether the selected code follows these documents.

Prompt files 和 custom instructions 的关系也要分清楚。

Custom instructions 负责"所有任务都应该遵守什么规则"。

Prompt files 负责"某个任务应该怎么执行"。

比如项目要求所有外部输入都用 Zod 校验，这应该放进 custom instructions。API 安全审查要检查鉴权、事务、错误码和测试，这更适合做成 prompt file。

三、Custom Agents：给复杂任务配置专门角色

Custom agents 适合处理比普通提示词更复杂的任务。

GitHub Docs 说明，custom agents 是 Copilot agent 的专门版本，可以根据团队工作流、编码约定和使用场景进行定制。它们用 Markdown agent profile 定义，里面可以包含 description、prompt、tools，必要时也可以配置 MCP servers。

仓库级 agent 可以放在：

text 复制代码

.github/agents/

一个安全审查代理可以这样写：

markdown 复制代码

---
name: security-reviewer
description: Reviews code for authentication, authorization, secrets, injection risks, and unsafe dependency usage.
tools:
  - search
  - edit
  - shell
---

You are a security reviewer for this repository.

Focus on:
- exposed secrets or credentials
- missing authentication checks
- missing authorization checks
- SQL injection risks
- unsafe shell command execution
- dependency changes that may introduce security risk

Do not rewrite large parts of the code unless explicitly asked.
Return findings with risk level, affected files, and recommended fixes.

这个 agent 和普通 prompt file 的区别在于，它更像一个带工具权限和专业边界的任务执行者。

GitHub 的 custom agents 文档提到，agent profiles 可以定义在仓库级，也可以在组织或企业级通过 .github-private 仓库下的 /agents/ 目录提供。创建后，可以用于 Copilot cloud agent、IDE 中的 cloud agent，以及 GitHub Copilot CLI；部分 IDE 环境中的 custom agents 仍处于 public preview，具体属性在不同环境里可能会有差异。

这意味着团队在写 agent 时要避免只按一个环境理解。

如果主要用于 Copilot CLI，要关注 CLI 的 agent 创建和调用方式。GitHub Docs 说明，CLI 中的 custom agent 可以放在项目的 .github/agents/ 或用户目录 ~/.copilot/agents/，同名时用户目录中的 agent 优先。

如果主要用于 cloud agent，要关注 GitHub.com、Issue 分配、Pull Request 任务和 MCP server 配置。

比较适合创建 custom agent 的场景有：

text 复制代码

安全审查
数据库迁移审查
前端性能优化
README 和文档维护
测试补全
遗留项目迁移
GitHub Actions 工作流修复

不建议给每个小任务都创建 agent。Agent 太多以后，团队反而不知道该用哪个。更稳的做法是先从 3 到 5 个高频角色开始，等使用稳定后再扩展。

四、Hooks：控制 Copilot 真正执行了什么

前面几类能力主要影响 Copilot 怎么想、怎么写。Hooks 解决另一个问题：Copilot 执行工具前后，团队能不能插入自己的规则。

GitHub 文档说明，Hooks 是存放在 .github/hooks/*.json 中的 JSON 配置，可以在 agent 工作流的特定节点执行自定义 shell 命令。它们可用于 Copilot cloud agent 和 GitHub Copilot CLI。

Hooks 最常用的场景是安全拦截和审计。

比如团队不希望 Copilot CLI 执行高风险命令，可以配置 preToolUse。GitHub 的 hooks 教程也明确写到，Hooks 可以检查 prompt 和工具调用，记录审计信息，甚至阻止某些命令执行，适合平台团队和工程管理者在组织安全策略内使用 Copilot CLI。

一个最小配置可以这样写：

json 复制代码

{
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": ".github/hooks/scripts/block-dangerous-command.sh",
        "timeoutSec": 10
      }
    ]
  }
}

脚本里可以检查危险命令：

bash 复制代码

#!/bin/bash
set -euo pipefail

INPUT="$(cat)"
TOOL_ARGS="$(echo "$INPUT" | jq -r '.toolArgs')"

if echo "$TOOL_ARGS" | grep -qE "rm -rf /|mkfs|dd if=|curl .*\\| bash|wget .*\\| sh|DROP TABLE"; then
  echo '{"permissionDecision":"deny","permissionDecisionReason":"Blocked by repository security policy"}'
  exit 0
fi

GitHub 的 hooks configuration 参考文档列出了多个 hook 类型，包括 session start、user prompt submitted、pre tool use、post tool use、error occurred、agent stop 和 subagent stop。preToolUse 在工具执行前触发，因此最适合做权限判断和危险命令拦截。

这里有一个细节要注意。Hooks 的输出字段里有 permissionDecision 和 permissionDecisionReason。文档中对 permissionDecision 的取值包含 allow、deny、ask，但当前 hooks configuration 中说明真正会被处理的是 deny。所以在 Copilot CLI 和 cloud agent 的 Hooks 场景里，最稳的用法是用它做硬拦截和日志记录，不要把它当成完整审批系统。

Hooks 和 custom instructions 可以配合使用。

比如指令里写：

markdown 复制代码

- Do not modify deployment scripts unless explicitly requested.
- Do not run destructive shell commands.

Hooks 里再做实际拦截：

bash 复制代码

if echo "$TOOL_ARGS" | grep -qE "kubectl delete|terraform destroy|rm -rf"; then
  echo '{"permissionDecision":"deny","permissionDecisionReason":"Destructive operation blocked"}'
  exit 0
fi

指令负责提醒 Copilot，Hooks 负责防止执行越界。对于企业项目，这两层都需要。

五、Awesome Copilot：别从零开始写配置

如果你刚开始做 Copilot 自定义，不需要所有配置都自己写。

GitHub 维护的 github/awesome-copilot 仓库是一个社区贡献集合，里面包含 custom agents、instructions、skills、hooks、workflows 和 plugins。仓库说明里也提到，官网提供全文搜索和过滤，还包含 MCP servers、开发工具、Learning Hub 等内容。

它的价值不在于直接复制，而在于找参考结构。

比如你要写一个安全审查 agent，可以先看社区里安全类 agent 的描述方式、工具限制和输出格式。你要写 TypeScript instruction，可以看别人怎么把 lint、类型、目录结构写成具体规则。你要写 Hooks，可以先找危险命令拦截、审计日志、策略提示这类模板。

我建议按这个方式使用：

text 复制代码

先找相近模板
复制到自己的仓库
删掉不适用的规则
补上项目真实约定
提交 PR 让团队 review
使用一段时间后继续调整

不要直接把几十条通用规则塞进项目。指令过多会稀释重点，甚至互相冲突。Copilot 最需要的是"这个项目真正重要的规则"，不是一份泛泛的最佳实践清单。

六、推荐的一套落地顺序

真正落地时，不建议一开始就做 Agents 和 Hooks。

更稳的顺序是从低成本配置开始。

第一步，写 .github/copilot-instructions.md。

先放 10 到 20 条项目最重要的规则。内容包括技术栈、目录约定、测试命令、错误处理、数据库访问、安全边界。写完以后，让 Copilot 改一个小功能，看输出是否明显更贴近项目。

第二步，补 path-specific instructions。

比如 TypeScript、React、SQL、GitHub Actions、测试文件，都可以有不同规则。只要某类文件有明确约定，就可以拆出来。

第三步，把高频任务做成 prompt files。

比如代码审查、生成单测、更新 README、分析 GitHub Actions 失败、生成 PR 描述。团队成员每天都要重复写的提示词，最适合沉淀成 .prompt.md。

第四步，为复杂角色创建 custom agents。

比如安全审查、数据库迁移、前端性能、测试补全、文档维护。每个 agent 都要有清晰边界，最好限制工具权限和输出格式。

第五步，为高风险仓库配置 Hooks。

先做三类就够了：危险命令拦截、敏感目录保护、审计日志。等团队适应后，再增加更复杂的质量门禁。

这个顺序的好处是每一步都有明确收益，也不会一下子增加太多维护成本。

总结

GitHub Copilot 的自定义能力，核心目标很简单：让 Copilot 更理解你的项目，也让团队能控制它的执行边界。

Custom instructions 适合放项目规则。它告诉 Copilot 当前仓库的技术栈、目录结构、测试方式和编码约定。

Prompt files 适合封装重复任务。代码审查、生成测试、写 README、分析报错，都可以做成可复用提示词，让团队成员用同一套标准执行。

Custom agents 适合复杂专业任务。安全审查、数据库迁移、性能优化、文档维护这类任务，需要更明确的角色、工具和输出边界。

Hooks 适合控制执行动作。它可以记录 prompt 和工具调用，也可以在工具执行前拦住危险命令。对于企业和重要仓库，Hooks 比单纯写指令更可靠。

我的建议是先从 .github/copilot-instructions.md 开始。不要一上来追求完整体系，先让 Copilot 明白项目最关键的 10 条规则。等日常输出稳定后，再补 prompt files、custom agents 和 hooks。这样做出来的定制体系更轻，也更容易被团队长期维护。