在 VS Code 中使用 Agent Skills

Agent Skills 是由指令、指令碼與資源組成的資料夾，GitHub Copilot 可以在相關時載入這些內容以執行特定任務。Agent Skills 是一項開放標準，適用於多種 AI 代理程式，包括 VS Code 中的 GitHub Copilot、GitHub Copilot CLI 以及 GitHub Copilot 雲端代理程式。

與主要定義程式碼撰寫準則的自訂指令不同，技能能實現專業化的功能與工作流程，其中可包含指令碼、範例與其他資源。您建立的技能具有可攜性，可在任何相容的代理程式中使用。

Agent Skills 的主要優點

• 專業化 Copilot：針對特定領域的任務量身打造功能，無需重複提供背景資訊
• 減少重複作業：一次建立，在所有對話中自動使用
• 組合功能：結合多項技能以建立複雜的工作流程
• 高效載入：僅在需要時將相關內容載入至上下文

Agent Skills 與自訂指令 (Custom Instructions) 的比較

雖然 Agent Skills 與自訂指令都有助於自訂 Copilot 的行為，但它們的用途不同

當您想要執行以下操作時，請使用 Agent Skills：

• 建立可在不同 AI 工具間運作的可重複使用功能
• 在指令之外加入指令碼、範例或其他資源
• 與更廣大的 AI 社群分享功能
• 定義專業化的工作流程，例如測試、除錯或部署程序

當您想要執行以下操作時，請使用自訂指令：

• 定義專案特定的程式碼標準
• 設定語言或框架規範
• 指定程式碼審查或提交訊息規範
• 使用 glob 模式根據檔案類型套用規則

建立一個技能 (Skill)

技能儲存在包含 SKILL.md 檔案的目錄中，該檔案定義了技能的行為。VS Code 支援兩種類型的技能

您可以透過 chat.agentSkillsLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來配置專案技能的其他檔案位置。如果您希望以不同的資料夾結構組織技能，或擁有多個技能目錄，此設定會非常有用。

若要建立技能

1. 在聊天檢視中，選取設定聊天 (Configure Chat)（齒輪圖示）以開啟「代理程式自訂編輯器」，然後選取技能 (Skills) 索引標籤。

2. 根據您想要儲存技能的位置，從下拉式選單中選擇新技能 (工作區) (New Skill (Workspace)) 或新技能 (使用者) (New Skill (User))。

   

3. 選擇位置並輸入技能名稱。

4. 填寫 YAML frontmatter 並在檔案本文中新增指令，以完成 SKILL.md 檔案。

   ---
   name: skill-name
   description: Description of what the skill does and when to use it
   ---
   
   # Skill Instructions
   
   Your detailed instructions, guidelines, and examples go here...
   

5. (選用) 將指令碼、範例或其他資源新增至技能目錄中。

   例如，用於測試 Web 應用程式的技能可能包含：

   • SKILL.md - 執行測試的指令
   • test-template.js - 範本測試檔案
   • examples/ - 測試情境範例
   注意

   請確保在 SKILL.md 中引用任何額外檔案，以便代理程式能偵測到它們。請使用 Markdown 連結語法搭配相對路徑，例如 [test template](./test-template.js)。

使用 AI 產生技能

您可以根據功能描述使用 AI 產生技能。在聊天中輸入 /create-skill 並描述您想要的技能（例如：「一個用於執行與除錯整合測試的技能」）。代理程式會詢問釐清問題，並產生包含目錄結構、指令與 frontmatter 的 SKILL.md 檔案。

您也可以從正在進行的對話中提取可重複使用的技能。例如，在除錯複雜問題的多輪對話後，詢問「create a skill from how we just debugged that」（根據我們剛才除錯的方式建立技能），即可將多步驟程序捕捉為可重複使用的技能。

您也可以從代理程式自訂編輯器中，透過下拉式選單選擇產生技能 (Generate Skill) 來產生技能。

SKILL.md 檔案格式

SKILL.md 是一個包含 YAML frontmatter 的 Markdown 檔案，用於定義技能的後設資料與行為。

標頭 (Header)（必要）

標頭格式為 YAML frontmatter，包含以下欄位：

本文 (Body)

技能本文包含 Copilot 使用此技能時應遵循的指令、準則與範例。請撰寫清晰、明確的指令，說明：

• 該技能有助於完成什麼任務
• 何時使用該技能
• 應遵循的逐步程序
• 預期輸入與輸出的範例
• 對任何隨附指令碼或資源的引用

您可以使用相對路徑引用技能目錄中的檔案。例如，若要引用技能目錄中的指令碼，請使用 [test script](./test-template.js)。

在分支上下文中執行技能（實驗性）

依預設，當 VS Code 載入技能時，技能的指令會新增至父代理程式的上下文視窗中。對於大型技能，或中間推論與對話其餘部分無關的技能，您可以改為在分支上下文 (forked context) 中執行。在分支上下文中，技能會在專用的子代理程式中執行，僅將最終結果傳回給父代理程式。這能保持主要對話上下文的乾淨。

若要在分支上下文中執行技能，請將 SKILL.md frontmatter 中的 context 欄位設定為 fork

---
name: review-pr
description: Review a pull request for code quality, style, and correctness. Use when asked to review a PR.
context: fork
---

# PR review

Follow these steps to review the pull request...

針對以下技能，建議使用 context: fork：

• 讀取大量檔案或執行冗長的調查，且細節無需留在主對話中
• 產生聚焦結果（例如摘要、報告或少量編輯），且父代理程式可直接針對該結果採取行動
• 不應影響父代理程式最終輸出之外的行為

技能範例

以下範例展示了您可以建立的不同技能類型。

---
name: webapp-testing
description: Guide for testing web applications using Playwright. Use this when asked to create or run browser-based tests.
---

# Web Application Testing with Playwright

This skill helps you create and run browser-based tests for web applications using Playwright.

## When to use this skill

Use this skill when you need to:
- Create new Playwright tests for web applications
- Debug failing browser tests
- Set up test infrastructure for a new project

## Creating tests

1. Review the [test template](./test-template.js) for the standard test structure
2. Identify the user flow to test
3. Create a new test file in the `tests/` directory
4. Use Playwright's locators to find elements (prefer role-based selectors)
5. Add assertions to verify expected behavior

## Running tests

To run tests locally:
```bash
npx playwright test
```

To debug tests:
```bash
npx playwright test --debug
```

## Best practices

- Use data-testid attributes for dynamic content
- Keep tests independent and atomic
- Use Page Object Model for complex pages
- Take screenshots on failure

---
name: github-actions-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
---

# GitHub Actions Debugging

This skill helps you debug failing GitHub Actions workflows in pull requests.

## Process

1. Use the `list_workflow_runs` tool to look up recent workflow runs for the pull request and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of the logs for failed jobs
3. If you need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full failure logs
4. Try to reproduce the failure locally in your environment
5. Fix the failing build and verify the fix before committing changes

## Common issues

- **Missing environment variables**: Check that all required secrets are configured
- **Version mismatches**: Verify action versions and dependencies are compatible
- **Permission issues**: Ensure the workflow has the necessary permissions
- **Timeout issues**: Consider splitting long-running jobs or increasing timeout values

將技能作為斜線指令 (Slash commands) 使用

技能可作為聊天中的斜線指令使用，與提示詞檔案 (prompt files) 並列。在聊天輸入框中輸入 / 即可查看可用技能與提示詞列表，並選取技能以進行呼叫。

您可以在斜線指令後新增額外上下文。例如，/webapp-testing for the login page 或 /github-actions-debugging PR #42。

依預設，所有技能都會顯示在 / 選單中。請使用 user-invocable 與 disable-model-invocation frontmatter 屬性來控制每個技能的存取方式：

Copilot 如何使用技能

技能會逐步載入內容，以維持上下文的高效。以下是 Copilot 如何使用 webapp-testing 技能的範例：

1. 探索：Copilot 從 YAML frontmatter 讀取技能的 name 與 description。當您詢問「help me test the login page」（幫我測試登入頁面）時，Copilot 會根據描述將其與 webapp-testing 技能進行配對。

2. 載入指令：Copilot 將 SKILL.md 本文載入至其上下文中，使其能夠存取詳細的測試程序與指導方針。您也可以透過在聊天中輸入 /webapp-testing 直接觸發此步驟。

3. 存取資源：當 Copilot 執行指令時，僅在引用到技能目錄中的額外檔案（例如 test-template.js 或範例情境）時才會存取它們。如果檔案未在指令中被引用，則不會被載入。

這種三級載入系統意味著您可以安裝許多技能，而不會耗盡上下文資源。Copilot 僅載入每個任務所需的內容。

選擇加入分支上下文的技能會遵循相同的探索步驟，但其指令與讀取的任何檔案都會載入至獨立的子代理程式中。僅有技能的最終結果會傳回給父代理程式。

使用共享技能

您可以使用他人建立的技能來增強 Copilot 的功能。github/awesome-copilot 儲存庫包含一個不斷成長的社群技能、自訂代理程式、指令與提示詞集合。anthropics/skills 儲存庫則包含額外的參考技能。

您也可以探索並安裝打包在代理程式外掛程式中的技能。來自已安裝外掛程式的技能會與您在地端定義的技能一起顯示在設定技能 (Configure Skills) 選單中。

若要使用共享技能

1. 瀏覽儲存庫中可用的技能
2. 將技能目錄複製到您的 .github/skills/ 資料夾
3. 檢閱並根據您的需求自訂 SKILL.md 檔案
4. 視需要修改或新增資源

從擴充功能貢獻技能

擴充功能可以使用其 package.json 中的 chatSkills 貢獻點來貢獻技能。路徑必須指向包含 SKILL.md 檔案的目錄，並遵循 Agent Skills 規範。

必要的資料夾結構

技能目錄必須遵循此結構

extension-root/
└── skills/
    └── my-skill/           # Directory name must match the `name` field in SKILL.md
        └── SKILL.md         # Required

在 package.json 中註冊技能

在您的擴充功能的 package.json 中新增 chatSkills 貢獻點。path 屬性必須指向對應的 SKILL.md 檔案

{
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/my-skill/SKILL.md"
      }
    ]
  }
}

SKILL.md 檔案遵循與專案與個人技能相同的格式。例如：

---
name: my-skill
description: Description of what the skill does and when to use it.
---

# My Skill

Detailed instructions for the skill...

Agent Skills 標準

Agent Skills 是一項開放標準，能實現不同 AI 代理程式間的可攜性。您在 VS Code 中建立的技能可在多種代理程式中運作，包括：

• VS Code 中的 GitHub Copilot：可在聊天與代理程式模式中使用
• GitHub Copilot CLI：在終端機作業時可存取
• GitHub Copilot 雲端代理程式：在自動化程式碼撰寫任務期間使用

深入了解 Agent Skills 標準，請參閱 agentskills.io。

相關資源

• 自訂 AI 回應概覽
• 建立自訂指示
• 建立可重複使用的提示詞檔案
• 建立自訂代理
• Agent Skills 規範
• 參考技能儲存庫
• 探索並管理代理程式外掛程式