GitHub Copilot Agent 設定教學｜用 .github 資料夾打造你的 AI 開發助手 - Kyle's Code Blog

GitHub Copilot 已經不只是自動補完程式碼的工具了，現在的 Copilot 支援 Agent Mode，可以理解整個專案的結構、自動執行指令、甚至幫你開 Pull Request。不過要讓 Copilot Agent 真正好用，關鍵在於告訴它你的專案長什麼樣子、該怎麼做事。這些設定都放在儲存庫的 .github 資料夾底下，只要把對應的檔案放好，Copilot 就能依照你的規則來工作。本文會教學 .github 資料夾中各個子資料夾的用途與設定方式，讓你快速上手 Copilot Agent。

Table of Contents

.github 資料夾總覽

在開始之前，先看一下 .github 資料夾底下跟 Copilot Agent 有關的子資料夾與檔案，有個全貌之後再一個一個介紹。

資料夾 / 檔案	用途	檔案格式
`copilot-instructions.md`	全域指令，定義整個儲存庫的規則	Markdown
`instructions/`	針對特定目錄或檔案類型的細粒度指令	`.instructions.md`
`agents/`	自訂 Agent，定義專門的 AI 助手	`.agent.md`
`prompts/`	可重用的 Prompt 範本	`.prompt.md`
`skills/`	Agent Skills，提供專業領域知識	`SKILL.md`
`workflows/`	GitHub Actions，設定 Agent 執行環境	`.yml`
`hooks/`	Agent Hooks，在特定事件觸發自訂腳本	`.json`

copilot-instructions.md — 全域指令

這是最基本也最重要的設定檔，放在 .github/copilot-instructions.md，用來告訴 Copilot 整個專案的開發規則與偏好。只要儲存這個檔案，Copilot Chat 就會自動讀取。

可以在裡面寫：

專案使用的程式語言和框架
程式碼風格（命名規則、縮排方式等）
測試規範
禁止使用的套件或做法

# 專案指令

## 技術
- 後端：Node.js + Express
- 前端：React + TypeScript
- 資料庫：PostgreSQL

## 程式碼風格
- 使用 camelCase 命名變數和函式
- 所有函式都要加上 JSDoc 註解
- 禁止使用 any 型別

## 測試
- 每個新功能都要寫單元測試
- 使用 Jest 作為測試框架
- 測試檔案放在 __tests__/ 目錄下

需要注意的是，這個檔案裡不要要求 Copilot 去讀取外部資源（像是某個網址的文件），也不要寫出跟 Copilot 核心功能衝突的指令。

instructions/ — 細粒度指令

如果專案中不同目錄需要不同的規則（例如前端和後端的寫法不一樣），可以在各個目錄下放 .instructions.md 檔案，Copilot 會根據你正在編輯的檔案位置，自動載入對應的指令。

假設你的專案結構是這樣：

my-project/
├── .github/
│   └── copilot-instructions.md    # 全域指令
├── frontend/
│   └── .instructions.md           # 前端專用指令
├── backend/
│   └── .instructions.md           # 後端專用指令
└── docs/
    └── .instructions.md           # 文件撰寫指令

前端的 frontend/.instructions.md 可能長這樣：

# 前端開發指令

- 使用 React 函式元件，不使用 class 元件
- 使用 CSS Modules 處理樣式
- 元件命名使用 PascalCase
- 狀態管理使用 Zustand

後端的 backend/.instructions.md 可能長這樣：

# 後端開發指令

- 使用 Express.js 路由
- 所有 API 回傳 JSON 格式
- 錯誤處理使用統一的 middleware
- 資料庫操作使用 Prisma ORM

這樣做的好處是 Copilot 不會把前端的規則套用到後端，反之亦然。全域指令 copilot-instructions.md 適合放專案共通的規則，而 .instructions.md 則用來處理目錄層級的差異。

agents/ — 自訂 Agent

自訂 Agent 可以讓你建立專門負責某類任務的 AI 助手，例如專門做 Code Review 的 Agent、專門寫測試的 Agent 等。檔案放在 .github/agents/ 底下，格式是 {名稱}.agent.md。

檔名只能使用英文字母、數字、.、-、_，不能用中文或空格。

每個 .agent.md 檔案分成兩個部分：YAML frontmatter 定義 Agent 的基本資訊，Markdown 內容定義 Agent 的行為指令。

---
name: code-reviewer
description: "專門負責 Code Review，檢查程式碼品質與安全性"
tools:
  - read
  - edit
  - search
---

# Code Review Agent

你是一個專業的 Code Reviewer，請依照以下規則檢查程式碼：

## 檢查項目
1. 是否有潛在的安全漏洞（SQL Injection、XSS 等）
2. 是否符合專案的命名規範
3. 是否有重複的邏輯可以抽成共用函式
4. 錯誤處理是否完善

## 回覆格式
- 用條列方式列出發現的問題
- 每個問題附上建議的修改方式
- 嚴重程度分為：🔴 高、🟡 中、🟢 低

tools 欄位可以指定 Agent 能使用的工具，如果想讓它使用所有工具，可以設為 ["*"] 或是直接不寫這個欄位。

再來看一個專門寫測試的 Agent：

---
name: test-writer
description: "自動產生單元測試，確保程式碼品質"
tools:
  - read
  - edit
  - terminal
---

# Test Writer Agent

你是一個專門寫單元測試的助手。

## 規則
- 使用 Jest 測試框架
- 每個測試案例都要有清楚的描述
- 要涵蓋正常路徑和錯誤路徑
- Mock 外部依賴（API、資料庫等）

## 流程
1. 先讀取要測試的原始碼
2. 分析函式的輸入輸出
3. 撰寫測試案例
4. 執行測試確認通過

在 Copilot Chat 中使用 @code-reviewer 或 @test-writer 就可以呼叫對應的 Agent。

prompts/ — 可重用 Prompt 檔案

Prompt 檔案讓你把常用的提示詞存成範本，團隊成員可以共享，避免每次都要重新打同樣的內容。檔案放在 .github/prompts/ 底下，格式是 {名稱}.prompt.md。

---
description: "將選取的程式碼重構為更乾淨的版本"
---

請重構以下程式碼，遵循以下原則：

1. 提取重複的邏輯為獨立函式
2. 改善變數命名，讓程式碼更容易閱讀
3. 移除不必要的註解和程式碼
4. 確保重構後功能不變

你也可以在 Prompt 檔案中指定要搭配哪個 Agent 和哪些工具：

---
description: "產生 API 端點的文件"
agent: "doc-writer"
tools:
  - read
  - search
---

請幫我產生以下 API 端點的文件，包含：

- 端點路徑和 HTTP 方法
- 請求參數說明
- 回應格式範例
- 錯誤碼說明

在 Copilot Chat 中輸入 / 就會看到可用的 Prompt 列表，選擇後就會自動帶入內容。

skills/ — Agent Skills 設定

Skills 比 instructions 更進階，它是一組包含指令、範例、資源的資料夾，Copilot 會在需要的時候自動載入對應的 Skill。如果說 instructions 是「通用規則」，Skills 就是「專業技能包」。

每個 Skill 是一個子資料夾，裡面至少要有一個 SKILL.md 檔案：

.github/skills/
├── api-design/
│   ├── SKILL.md              # Skill 定義
│   └── examples/             # 範例檔案
│       ├── good-api.ts
│       └── bad-api.ts
└── database-migration/
    ├── SKILL.md
    └── templates/
        └── migration.sql

SKILL.md 的格式：

---
name: api-design
description: "RESTful API 設計指南，當使用者建立新的 API 端點時自動載入"
---

# API 設計指南

## 路由命名規則
- 使用複數名詞：`/users`，不用 `/user`
- 使用 kebab-case：`/user-profiles`，不用 `/userProfiles`
- 最多三層巢狀：`/users/:id/posts`

## HTTP 方法對應
| 操作 | 方法 | 路由範例 | 回應碼 |
|------|------|----------|--------|
| 列表 | GET | /users | 200 |
| 單筆 | GET | /users/:id | 200 |
| 新增 | POST | /users | 201 |
| 更新 | PUT | /users/:id | 200 |
| 刪除 | DELETE | /users/:id | 204 |

## 範例
參考 examples/ 資料夾中的範例檔案。

跟 instructions 的差異在於，instructions 幾乎每次都會載入，而 Skills 只有在 Copilot 判斷當前任務相關時才會載入，所以更適合放比較詳細、篇幅較長的專業知識。

另外，Skills 是一個開放標準，不只 GitHub Copilot 支援，其他 AI 工具也可以讀取，所以設定一次可以在多個工具間共用。

workflows/ — GitHub Actions 整合

Copilot Coding Agent 在執行任務時，是跑在 GitHub Actions 的環境裡的。如果你需要讓 Agent 能夠編譯專案、執行測試，就要透過 .github/workflows/copilot-setup-steps.yml 設定它的執行環境，像是安裝 Node.js、Python 等依賴。

# .github/workflows/copilot-setup-steps.yml
name: "Copilot Setup Steps"
on: workflow_dispatch

jobs:
  copilot-setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install

這個部分跟 GitHub Actions 的設定方式一樣，如果想深入了解 Workflow 的寫法，可以參考之前的文章：使用GitHub Actions自動部署服務到自己的伺服器。

其他推薦設定

hooks/ — Agent Hooks

Agent Hooks 讓你在 Copilot Agent 的特定時間點觸發自訂腳本，像是在 Agent 開始工作前檢查環境、在使用工具前做驗證等。檔案放在 .github/hooks/ 底下，格式是 JSON。

支援的事件有：

事件	觸發時機
`sessionStart`	Agent 開始工作
`sessionEnd`	Agent 結束工作
`preToolUse`	使用工具之前（可以批准或拒絕）
`postToolUse`	使用工具之後
`agentStop`	Agent 停止

{
  "hooks": [
    {
      "event": "sessionStart",
      "command": "npm install"
    },
    {
      "event": "preToolUse",
      "command": "./scripts/validate-tool-usage.sh",
      "args": ["--strict"]
    }
  ]
}

其中 preToolUse 比較特別，它可以透過腳本的退出碼來決定是否允許 Agent 使用該工具。退出碼 0 表示允許，非 0 表示拒絕。

MCP Server 設定

如果你想讓 Copilot Agent 使用外部工具（像是查詢資料庫、呼叫第三方 API），可以透過 Model Context Protocol（MCP）Server 來擴充。設定方式有兩種：

在 Agent 檔案中設定：

---
name: db-agent
description: "可以查詢資料庫的 Agent"
tools:
  - "*"
mcp-server:
  - name: database
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
---

你可以使用資料庫工具來查詢和分析資料。

在儲存庫設定中設定：

在 GitHub 網頁上，到 Settings → Copilot and Coding agent → MCP servers configuration，可以用 JSON 格式設定 MCP Server。

需要注意的是，Copilot Coding Agent 目前只支援 MCP Server 提供的 tools，不支援 resources 和 prompts。

完整資料夾結構範例

最後整理一個完整的 .github 資料夾結構給各位參考：

.github/
├── copilot-instructions.md          # 全域指令
│
├── instructions/                    # 細粒度指令（也可以放在各子目錄）
│
├── agents/                          # 自訂 Agent
│   ├── code-reviewer.agent.md
│   ├── test-writer.agent.md
│   └── doc-writer.agent.md
│
├── prompts/                         # 可重用 Prompt
│   ├── refactor.prompt.md
│   ├── generate-docs.prompt.md
│   └── fix-bug.prompt.md
│
├── skills/                          # Agent Skills
│   ├── api-design/
│   │   ├── SKILL.md
│   │   └── examples/
│   └── testing/
│       ├── SKILL.md
│       └── templates/
│
├── hooks/                           # Agent Hooks
│   └── hooks.json
│
└── workflows/                       # GitHub Actions
    ├── copilot-setup-steps.yml      # Copilot Agent 環境設定
    └── ci.yml                       # 其他 CI/CD 工作流程

建議先從 copilot-instructions.md 開始設定，讓 Copilot 了解專案的基本規則，之後再根據需求逐步加入 agents、prompts、skills 等進階設定。不需要一次把所有資料夾都建好，用到什麼再加什麼就好。

Post Views: 3