VS Code Agent Skills 使用指南

發表於 分類於

VS Code Agent Skills 使用指南

GitHub Copilot 的 Agent Skills 功能讓你能夠建立可重複使用的工作流程，並在需要時自動載入對應的指令、腳本與資源。本文將介紹 Agent Skills 的核心概念、建立方式，以及與其他自訂功能的差異。

Agent Skills 是什麼？

Agent Skills 是由一個資料夾組成的技能包，內含 SKILL.md 指令檔、腳本與相關資源。當 GitHub Copilot 判斷某個技能與當前任務相關時，會自動載入對應的內容。

Agent Skills 的設計遵循開放標準（agentskills.io），因此建立好的技能不僅適用於 VS Code，也能在 GitHub Copilot CLI 與 GitHub Copilot Coding Agent 等環境中使用。

使用 Agent Skills 的主要優點：

  • 專業化：為特定領域的任務量身打造能力，不需每次重複說明背景
  • 減少重工：建立一次，自動套用於所有相關對話
  • 組合運用：多個技能可以組合搭配，建構複雜的工作流程
  • 高效載入：僅在相關時才將內容載入 context，避免浪費 token

Agent Skills vs. 自訂指令

Agent Skills 與 Custom Instructions（自訂指令）都能自訂 Copilot 的行為，但用途截然不同：

比較項目 Agent Skills Custom Instructions
用途 封裝專業能力與工作流程 定義編碼規範與準則
可攜性 跨 VS Code、Copilot CLI、Copilot Coding Agent 僅限 VS Code 與 GitHub.com
內容 指令、腳本、範例與資源 僅限指令
載入時機 依需求動態載入 永遠套用（或透過 glob 模式控制）
標準 開放標準（agentskills.io） VS Code 專屬

選用 Agent Skills 的情境：

  • 需要跨不同 AI 工具重複使用同一套能力
  • 需要附帶腳本、範例或其他資源
  • 定義測試、除錯或部署等專業工作流程

選用 Custom Instructions 的情境：

  • 定義專案的編碼規範
  • 設定語言或框架慣例
  • 套用基於檔案類型的規則

建立技能

儲存位置

技能分為兩種範疇：

類型 儲存路徑
專案技能（存放於 repository） .github/skills/、.claude/skills/、.agents/skills/
個人技能（存放於使用者設定） ~/.copilot/skills/、~/.claude/skills/、~/.agents/skills/

提示：可在設定中調整 chat.agentSkillsLocations，指定額外的技能搜尋位置，方便跨專案共用。

手動建立步驟

  1. 在 Chat 視圖中，選擇齒輪圖示開啟 Chat Customizations 編輯器，切換至 Skills 頁籤
  2. 從下拉選單選擇 New Skill (Workspace) 或 New Skill (User)

建立新技能的畫面，顯示 Chat Customizations 編輯器的 Skills 頁籤與下拉選單

  1. 選擇儲存位置並輸入技能名稱
  2. 填寫 SKILL.md 的 YAML frontmatter 與指令內文
  3. 依需求新增腳本、範例或其他資源

使用 AI 自動生成

在聊天輸入框中輸入 /create-skill，並描述你想建立的技能（例如「一個用來執行與除錯整合測試的技能」）。Copilot 會提問釐清需求，並自動生成包含目錄結構、指令與 frontmatter 的 SKILL.md 檔案。

你也可以從正在進行的對話中萃取技能——例如在一段多輪除錯對話結束後，輸入「從我們剛才的除錯過程建立技能」，讓 Copilot 將這段流程封裝成可重複使用的技能。

SKILL.md 檔案格式

SKILL.md 是一個包含 YAML frontmatter 的 Markdown 檔案，負責定義技能的元資料與行為。

YAML Frontmatter（必填）

1
2
3
4
5
6
7
---
name: skill-name              # 必填：小寫英數字與連字號，需與資料夾名稱相同，最多 64 字元
description: '說明技能的功能與使用時機，越具體越好，最多 1024 字元'
argument-hint: '[可選] 以 slash command 呼叫時顯示的提示文字'
user-invocable: true          # 可選，預設 true：false 則不顯示於 / 選單
disable-model-invocation: false # 可選，預設 false：true 則僅允許手動呼叫
---

各欄位說明：

欄位 必填 說明
name 是 技能唯一識別名稱，需與上層資料夾名稱完全相同
description 是 描述功能與使用時機，是 Copilot 判斷是否載入的依據
argument-hint 否 以 slash command 呼叫時顯示的輸入提示
user-invocable 否 是否顯示於 / 選單，預設 true
disable-model-invocation 否 禁止 Copilot 自動載入，僅允許手動呼叫，預設 false

指令內文（Body）

內文填寫 Copilot 使用此技能時應遵循的指令、準則與範例，建議包含：

  • 技能能完成的事項
  • 使用時機說明
  • 逐步操作流程
  • 預期輸入與輸出的範例
  • 隨附腳本或資源的參考路徑

可以用相對路徑引用技能資料夾內的檔案，例如：

1
執行測試請參考 [測試腳本](./scripts/test.js)

完整範例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
name: webapp-testing
description: '測試 Web 應用程式的技能。Use for: verifying frontend, debugging UI, capturing screenshots.'
---

# Web 應用程式測試

## 使用時機
- 驗證前端功能
- 除錯 UI 行為

## 操作步驟
1. 啟動 Web 伺服器
2. 執行 [測試腳本](./scripts/test.js)
3. 查閱 `./screenshots/` 中的截圖結果

以 Slash Command 呼叫技能

技能建立後會自動出現在 chat 的 / 指令選單中。輸入 / 即可瀏覽所有可用的技能與 prompt，選取後即可呼叫。

呼叫時也能附加額外的情境說明，例如：

1
2
/webapp-testing 驗證登入頁面的功能
/github-actions-debugging PR #42

Slash Command 行為控制：

設定組合 顯示於 / 選單 自動載入 適用情境
預設（兩者皆略去） 是 是 一般用途技能
user-invocable: false 否 是 背景知識型技能（由 Copilot 自動判斷載入）
disable-model-invocation: true 是 否 僅在手動呼叫時執行的技能
兩者皆設定 否 否 暫時停用的技能

Copilot 如何使用技能

技能採用漸進式載入機制，確保 context 使用效率：

  1. 探索（Discovery）：Copilot 讀取 YAML frontmatter 中的 name 與 description。當你提出相關問題時，Copilot 會根據描述比對最合適的技能。
  2. 載入指令（Instructions Loading）：Copilot 將 SKILL.md 的內文載入 context，取得詳細的操作流程與準則。你也可以直接輸入 /技能名稱 手動觸發此步驟。
  3. 存取資源（Resource Access）：當 Copilot 在執行指令時需要引用額外檔案（如腳本或範例），才會按需載入技能資料夾中的對應資源。

這個三層式載入機制的優點在於：即使安裝了大量技能，也不會佔用不必要的 context，Copilot 只會載入當前任務真正需要的內容。

Copilot CLI 實際Demo

使用社群分享的技能

你可以從以下社群資源取得現成的技能：

使用步驟：

  1. 瀏覽上述 repository 中的可用技能
  2. 將技能資料夾複製到你的 .github/skills/ 目錄
  3. 檢閱並視需要自訂 SKILL.md 內容
  4. 依需求修改或新增資源

安全提示：使用前務必仔細審查共享技能的內容，確認符合你的需求與安全標準。

重點整理

  • Agent Skills 讓你能夠封裝可重複使用的工作流程，並搭配腳本與資源一同管理
  • SKILL.md 中的 name 需與資料夾名稱完全相同
  • description 是 Copilot 自動判斷是否載入的關鍵，請寫得具體且包含觸發關鍵字
  • 技能採用漸進式載入，不用擔心安裝太多技能會影響效能
  • Agent Skills 遵循開放標準，可跨多個 AI 工具使用

相關資源