前言

• 本文章是使用 GitHub Copilot 的人都應該建立 "copilot-instructions.md"的續篇。
• 在本文章中，我們使用copilot-instructions.md來作為自訂指示（或上下文檔案），但在AGENTS.md中大部分操作並不會有很大變化。

使用 GitHub Copilot 的開發者們，你們是否已經建立了.github/copilot-instructions.md這個檔案？
而且，你們有建立 SKILL.md 這個檔案嗎？

在 2025 年 10 月，我發布了文章使用 GitHub Copilot 的人都應該建立 "copilot-instructions.md"，我是TooMe。
距離那時已經過了三個多月，GitHub Copilot 也進行了幾次更新。
其中最重要的更新是支援在 2025 年 12 月推出的 1.108 版本中的Agent Skills。

版本說明：https://code.visualstudio.com/updates/v1_108

在本文章中，我將介紹如何利用這個Agent Skills來更強力地使用 GitHub Copilot，超越之前文章中的方法。

之前的方法的弱點

在之前的文章中，我們對copilot-instructions.md提供了許多信息。因此，推論所使用的模型性能較低；如果在一次對話中太長，可能會忘記之前所說的內容，甚至忘記在copilot-instructions.md中所定義的內容。
此外，提供的上下文過多可能會造成噪音，導致推論時間延長或產生不相關的回應。

什麼是 Agent Skills

Agent Skills 是一組指令、腳本和資源的資料夾，Copilot 可以在相關情況下加載它們，以提升執行特殊任務的性能。Agent Skills 是各種代理所使用的開放標準。

有關 Agent Skills 的資訊 - GitHub 文件

從「技能」這個名稱來看，它聽起來像是使用某些工具的能力，或是定義工具本身，但實際上最常見的用法是將項目的領域知識等納入。
實際上，我們來介紹一下它的使用情況。
以下是一個SKILL.md的例子。

<details>
<summary>範例：測試策略的 SKILL.md（點擊展開）</summary>

---
name: testing
description: TooMe's Task App (Web)的測試策略。簡述使用 Vitest、React Testing Library、MSW 的單元及元件測試。供測試時參考。
---

# 測試策略

## 技術棧
- **單元測試**: Vitest
- **元件測試**: React Testing Library + user-event
- **API 模擬**: MSW (Mock Service Worker)
- **E2E 測試**: Playwright / Cypress
- **Hook 測試**: `@testing-library/react-hooks` (或 RTL 的 `renderHook`)

## 單元測試 (Utils / Hooks / Stores)
- 驗證純函數（utils）、自定義 hooks、Zustand 儲存的邏輯
- 包含非同步處理時，適當地使用 `waitFor` 或 `act`

```typescript
// stores/authStore.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { renderHook, act } from '@testing-library/react';
import { useAuthStore } from './authStore';

describe('useAuthStore', () => {
    beforeEach(() => {
        const { result } = renderHook(() => useAuthStore());
        act(() => result.current.logout());
    });

    it('should set user and authentication status', () => {
        const { result } = renderHook(() => useAuthStore());
        const mockUser = { uid: '123', email: '[email protected]' };

        act(() => {
            result.current.setUser(mockUser as any);
        });

        expect(result.current.user).toEqual(mockUser);
        expect(result.current.isAuthenticated).toBe(true);
    });
});

元件測試 (UI / 整合)

• 使用 user-event 模擬用戶交互（點擊、輸入）
• 測試的是用戶可見的行為（可及性屬性和文本），而不是實作細節

// features/task/components/TaskInput.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { TaskInput } from './TaskInput';
import { vi } from 'vitest';

describe('TaskInput', () => {
    it('calls onSubmit with input text when enter is pressed', async () => {
        const handleCreate = vi.fn();
        const user = userEvent.setup();

        render(<TaskInput onCreate={handleCreate} />);
        const input = screen.getByRole('textbox', { name: /輸入任務/i });

        // 模擬輸入和提交
        await user.type(input, '新任務{enter}');

        expect(handleCreate).toHaveBeenCalledWith('新任務');
        expect(input).toHaveValue(''); // 提交後清空確認
    });
});

API 模擬 (MSW)

• 在元件測試或整合測試中需要 API 回應時，使用 MSW
• 不會發生實際的網路請求

// tests/mocks/handlers.ts
import { http, HttpResponse } from 'msw';

export const handlers = [
    http.get('/api/tasks', () => {
        return HttpResponse.json([
            { id: '1', title: '買牛奶', completed: false },
            { id: '2', title: '遛狗', completed: true },
        ]);
    }),
];

E2E 測試

• 驗證關鍵的用戶旅程（登入 → 創建任務 → 完成）
• 使用 Playwright 或 Cypress 進行實際的瀏覽器環境操作確認

測試最佳實踐

• AAA 模式: 有意識地執行 Arrange (準備)、Act (執行) 和 Assert (驗證)
• 查詢優先順序: 依照 getByRole > getByLabelText > getByText > getByTestId 的順序獲取元素
• 非同步等待: 等待數據加載時，使用 await screen.findBy... 或 waitFor
  </details>

這是從之前文章中的copilot-instructions.md範例 1: 使用 React 的 Web 應用程式中「測試策略」部分擷取的一部份，加上了一些 AI 的補充內容。

md 檔案的開頭部分有一些特別的分隔區，並在那裡設置了name和description。
我將簡要說明這些參數。

GitHub Copilot 會讀取每個 SKILL.md，根據需要執行任務。這個需要的條件是透過description來定義的。

在剛才的例子中，我們定義description如下。

TooMe's Task App (Web)的測試策略。簡述使用 Vitest、React Testing Library、MSW 的單元及元件測試。供測試時參考。

因此，在執行與測試相關的任務時，會讀取這個 SKILL.md。這樣我們就能將與測試策略相關的上下文從大的copilot-instructions.md中分離出來。而且，這個分離的上下文只會在需要時被讀取。

SKILL.md 的製作和使用方式

1. 在 VSCode 的設置中啟用 chat.useAgentSkills

隨著未來 VSCode 的更新，這個項目可能會預設為 true，甚至該項目可能會消失。

2. 按照以下目錄結構定義各 SKILL.md

這樣 GitHub Copilot 能根據需要參考到所需的 SKILL.md。
當然，這裡的目錄結構只是範例，根據項目需要，你可以自由創建新的目錄，並在其中建立 SKILL.md。

.github
│── skills
│   ├── architecture
│   │   └── SKILL.md
│   ├── ui-design
│   │   └── SKILL.md
│   ├── state-management
│   │   └── SKILL.md
│   ├── backend-integration
│   │   └── SKILL.md
│   ├── coding-standards
│   │   └── SKILL.md
│   └── testing
│       └── SKILL.md
└── copilot-instructions.md

提示：其實即使不使用上述結構，只要設置好 VSCode 的 chat.agentSkillsLocations，也可以創建自己喜好的目錄結構。

這樣一來，copilot-instructions.md就會變得非常簡潔。

# 專案的 Copilot 指示 (TooMe's Task App - Web)

## 前提條件
- **請務必以中文作答。**
- 在修改代碼時，若變更的行數可能超過 200 行，請先詢問用戶「此指示的變更行數可能超過 200 行，是否執行？」。
- 如需進行任何重大變更，請先計劃要做的內容，然後提議給用戶「我打算以這樣的計劃進行。」。

## 參考技能指南 (Skills)

在執行特定任務時，請務必參考以下相應的文件並遵循指導。
- **架構目錄結構**
  - 檔案配置、模組結構、功能分離
  - 📄 `.github/skills/architecture/SKILL.md`
- **UI 實作與樣式設計**
  - Tailwind CSS、元件設計、可及性(a11y)
  - 📄 `.github/skills/ui-design/SKILL.md`
- **狀態管理與數據擷取**
  - Zustand (全局)、React Query (伺服器)、React Hook Form
  - 📄 `.github/skills/state-management/SKILL.md`
- **後端整合與認證**
  - Firebase 認證、Google Calendar API、通知功能
  - 📄 `.github/skills/backend-integration/SKILL.md`
- **編碼規範**
  - TypeScript/React 的最佳實踐、命名規則、反模式
  - 📄 `.github/skills/coding-standards/SKILL.md`
- **測試策略**
  - Vitest、React Testing Library、MSW、E2E
  - 📄 `.github/skills/testing/SKILL.md`

## 專案概述

**TooMe's Task App (Web)** 是一個將任務管理與時間管理整合的 Web 應用程式。

### 技術棧概述

| 類別 | 技術 |
| --- | --- |
| **前端** | React 18, TypeScript 5, Vite 5 |
| **樣式** | Tailwind CSS, Radix UI |
| **狀態** | Zustand, TanStack Query (React Query) |
| **後端** | Firebase (Auth, Firestore, Functions, Hosting) |
| **整合** | Google Calendar API, Web Push API |
| **測試** | Vitest, React Testing Library, MSW |

### 目錄結構概述

src/
├── app/ # 入口點
├── features/ # 按功能劃分的模組 (task, calendar, auth...)
├── shared/ # 共用模組 (ui, hooks, utils...)
├── lib/ # 外部設定 (firebase, google...)
└── styles/ # 全域樣式

提示：在執行這個任務時，不必特意強調要參考這個 SKILL.md。若想縮短上下文檔案，也可以省略。
對我來說，因為還是剛開始接觸skills，感到有點不安，所以這樣寫下來。

結語

在本篇文章中，我們介紹了如何利用 GitHub Copilot 最新的功能Agent Skills，以及如何透過SKILL.md來比以往更強力地使用 GitHub Copilot。

大家也可以將 Agent Skills 引入自己的專案，將「相對優秀的助理」培養成「可靠的代理」。

VSCode 和 GitHub Copilot 的更新速度真是驚人。。。
在我撰寫這篇文章的同時，v1.109 的版本說明已經發布，GitHub Copilot 的 UI 也有了重大變化。
如果有需求，我可能會寫成文章。

活動宣傳

最後，讓我稍微宣傳一下活動。
KDDI 敏捷開發中心（KAG）每天都在探討如何在業務和個人活動中運用生成 AI 和其他 AI 技術。
下週我們將舉辦「KAG AI Week」，平日午餐時間（12:00～）將連續 5 天，由 KAG 員工進行 AI 相關的 LT（Lightning Talk）分享！

工程師如何在現場使用 AI，最新的 AI 趨勢又是怎麼看。大家可以在輕鬆的環境中，一邊吃午餐一邊參加！

我也預計在第 1 天和第 5 天上台發言！

與「KAG AI Week」相關的活動頁面如下↓

參考文獻

在撰寫本篇文章時參考的官方文件。
閱讀這些內容也許能進一步提升理解。

• 2025 年 12 月版本 1.108
• 有關 Agent Skills 的資訊 - GitHub 文件
• 在 VS Code 中使用 Agent Skills
• Specification - Agent Skills

原文出處：https://qiita.com/TooMe/items/230a730ce0387c77e822