讓 AI 代理學會「技能」：Agent Skills 開放標準如何重塑開發者的能力架構？

1. 前言：跳脫「重複下指令」的無限輪迴

對於身處生成式 AI 第一線的開發者來說，最消耗精力的往往不是撰寫程式碼，而是與 AI 溝通的「摩擦力」。你是否曾感到厭倦？每次開啟新的對話，都必須重新貼上團隊的編碼規範、重複交代 CI/CD 的修復流程，或是一再強調特定架構的設計原則。這種「重複下指令」的循環不僅浪費 Token，更反映出我們與 AI 協作的底層缺失：我們缺乏一種標準化的方式，來封裝並傳遞專業知識。

「Agent Skills」的出現正是為了打破這個僵局。它不只是另一種 Prompt 技巧，而是一項將「能力（Capability）」從「模型（Model）」中解耦（Decoupling）的開放標準。透過這套框架，我們可以賦予 AI 代理（AI Agents）一套專門化的「技能包」，讓 AI 從泛泛而談的聊天機器人，進化為掌握特定工作流的領域專家。

2. 突破點一：跨平台的開放標準——寫一次，處處可用

身為 AI 研發架構師，我認為 Agent Skills 最具戰略意義的特性在於其移植性（Portability）避免廠商鎖定（Vendor Lock-in）。這是一項基於 agentskills.io 的開放標準，目前已獲得 GitHub Copilot、Claude Code、Cursor、Gemini CLI 與 OpenAI Codex 等主流平台的支援。

這意味著你所封裝的專業邏輯，現在可以像程式碼一樣進行版本控制（Version Control），並與專案代碼並行存在。不論你的團隊決定從 Cursor 切換到 Claude Code，或是從 IDE 轉向 CLI 工具，這些經過驗證的運作知識（Operational Logic）都能無縫遷移。

「技能是一種可移植、受版本控制的包，用於教會 AI 代理如何執行特定領域的任務。」

這種「一次開發，多端運行」的模式，讓開發者能將最佳實踐封裝起來，在整個開發生命週期中保持 AI 表現的一致性。

3. 突破點二：漸進式揭露（Progressive Disclosure）——極致的 Token 效率

在大型專案中，盲目地將所有背景資料塞入上下文（Context Window）會導致嚴重的權杖（Token）浪費，甚至稀釋模型對核心任務的專注度。Agent Skills 採用的「漸進式揭露」機制，是針對 Token 效率與效能的最佳實踐。

系統不會在啟動時加載所有指令，而是根據任務需求，分三個層級進行上下文感應加載（Context-Aware Loading）：

1. 技能發現（Discovery）： 啟動時，系統僅解析 SKILL.md 中的 YAML 前言（Frontmatter），讀取名稱與描述。此階段極輕量，通常僅耗費 30-50 個 Token。
2. 指令加載（Instructions Loading）： 當使用者的請求觸發特定技能時，AI 才會讀取並加載 SKILL.md 的 Markdown 正文（Body），正式激活該項專門知識。
3. 資源訪問（Resource Access）： 只有在執行具體任務時，AI 才會根據指令進一步存取資料夾內的輔助腳本（Scripts）或參考文件（References）。

這種架構確保了 AI 代理能同時「待命」上百種技能，卻始終保持極低的運行成本。

4. 突破點三：技能 (Skills) vs. MCP vs. 自定義指令

為了精確佈署 AI 工具流，架構師必須釐清不同組件的定位。我通常使用以下比喻：

* MCP (Model Context Protocol) 是「硬體或驅動程式」： 它負責連接外部工具（如資料庫 API、檔案系統），提供 AI 與世界互動的「手」。
* Agent Skills 是「操作說明書」： 它教導 AI 「如何使用工具」來完成特定任務。它定義了邏輯判斷與工作流程（Workflow）。
* 自定義指令（Custom Instructions）是「專案全局準則」： 如 .claude.md 或 .cursorrules，定義全局通用的程式風格或命名規範。

特性	Agent Skills	MCP 伺服器	自定義指令
定位	任務特定工作流 (Logic)	外部工具與數據整合 (Tools)	全局行為修正 (Rules)
啟動方式	語意觸發或斜線指令	顯式工具調用 (Tool Calls)	始終開啟 (Always-on)
最佳場景	TDD、Git 工作流、複雜除錯	數據庫連結、外部服務 API	程式风格、命名規範

5. 突破點四：語意觸發（Semantic Triggering）——讓 AI 具備「聯想力」

Agent Skills 的魔力在於其**隱性調用（Implicit Invocation）機制。當你在 YAML 前言中撰寫 description 時，你實際上是在為 AI 建立一個語意觸發（Semantic Trigger）**點。

AI 會根據你的自然語言請求與技能描述進行動態匹配。例如，當你輸入「協助我處理這個失敗的 PR 狀態」時，AI 會發現該請求與「GitHub Actions 偵錯技能」的描述高度關聯，進而主動請求激活該技能。這種設計讓 description 欄位不再只是註解，而是觸發 AI 專業行為的「神經元」。當然，如果你需要更精確的控制，也可以透過 /skill-name 或 $ 符號進行顯式調用（Explicit Invocation）。

「AI 代理會根據使用者的提示與技能描述，自主決定何時採用特定的專家技能。」

6. 實戰示範：技能包的解剖學

一個標準的 Agent Skill 是以資料夾形式存在的獨立單元。在實作時，你應根據作用域選擇存放路徑：

* 專案級技能： ./.github/skills/ 或 ./.claude/skills/（推薦用於團隊共享）。
* 個人級技能： ~/.copilot/skills/ 或 ~/.claude/skills/（推薦用於個人習慣）。

核心文件必須命名為 SKILL.md。以下是一個結合安全與自動化的「GitHub Actions 偵錯」技能範例：

---
name: github-actions-failure-debugging
description: 用於偵錯失敗的 GitHub Actions 工作流。當使用者要求處理 CI/CD 失敗或分析 PR 狀態時使用。
allowed-tools: list_workflow_runs, summarize_job_log_failures, get_job_logs
context: fork
---

# GitHub Actions 偵錯專家

當處理失敗的工作流時，請務必遵循以下專家流程：

1. **狀態盤點**：使用 `list_workflow_runs` 工具查看最近的運行狀態，確認受影響的 Job。
2. **日誌摘要**：使用 `summarize_job_log_failures` 獲取日誌摘要，**嚴禁**直接加載數千行原始日誌以節省上下文空間。
3. **隔離分析**：若需執行診斷腳本，請使用 [debug-helper.py](./scripts/debug-helper.py)。
4. **驗證修復**：修復後應嘗試在本地環境重現，確保解決方案有效後再提交。

## 參考資源
- 查閱 [common-errors.md](./references/common-errors.md) 了解已知問題。


在這個範例中，我使用了 allowed-tools 來限制 AI 僅能存取特定的 GitHub 工具，並透過 context: fork 確保偵錯過程在獨立的子代理環境（Sub-agent context）中運行，避免汙染主對話的歷史紀錄。

7. 結論：邁向模組化 AI 專家的未來

Agent Skills 標準的成熟，標誌著開發範式的轉移：我們正從「撰寫 Prompt」進化到「定義能力」。

在可預見的未來，高品質的 SKILL.md 將成為技術資產的一部分。團隊不再是傳承厚重的文檔，而是交付一套可以動態激活、版本化且跨平台的「技能庫」。這不僅提升了開發效率，更讓初級開發者能透過 AI 直接調用團隊內資深架構師的思維框架。

思考題： 如果你的團隊能將過去十年累積的架構決策與 Code Review 標準封裝成一個 Agent Skill，你們的團隊效能會產生什麼樣的量級變化？

Agent Skills：讓 AI 代理帶著「技能包」上工

1. 問題在哪？每次都要重來一遍

用 AI 寫程式碼的人大概都有這種經驗：開一個新對話，又要重新貼團隊的編碼規範、再交代一次 CI/CD 修復流程、再說明架構原則。反覆做這件事真的很煩，而且浪費 Token。

說到底，問題在於我們沒有一套標準格式來打包「AI 該知道的事」。Agent Skills 就是為了解決這個問題——把專業知識封裝成可重複使用的技能檔案，讓 AI 代理在需要時自己讀取，不用你每次手動餵。

2. 跨平台：寫一次就能到處用

我覺得 Agent Skills 最實在的地方，在於它是開放標準（基於 agentskills.io）。GitHub Copilot、Claude Code、Cursor、Gemini CLI、OpenAI Codex 都已經支援。

換句話說，你花時間整理好的技能檔可以跟著專案走，用 Git 做版本控制，團隊換工具也不用重寫。從 Cursor 搬到 Claude Code？技能檔直接帶過去。

3. 省 Token 的三層載入機制

把所有背景資料一股腦塞進上下文視窗，Token 吃很兇，AI 回答品質也會下降。Agent Skills 用了一個分層載入的做法：

1. 發現階段：系統啟動時只讀 SKILL.md 的 YAML 標頭（名稱和描述），大概 30-50 個 Token。
2. 指令載入：使用者的請求跟某個技能對上了，才把完整的 Markdown 內容讀進來。
3. 資源存取：執行任務時才去抓資料夾裡的腳本或參考文件。

所以 AI 可以同時「知道」上百種技能存在，但不會為此多花 Token。這個設計蠻實際的。

4. Skills、MCP、自定義指令——三者差在哪？

我自己的理解方式：

* MCP (Model Context Protocol) 是「手」：負責連接外部工具，像資料庫 API 或檔案系統。
* Agent Skills 是「操作手冊」：告訴 AI 用那些工具的時候該怎麼做，定義工作流程。
* 自定義指令是「專案規範」：像 .claude.md 或 .cursorrules，寫全域通用的程式風格和命名慣例。

| 特性 | Agent Skills | MCP 伺服器 | 自定義指令 |
|------|-------------|-----------|-----------|
| 定位 | 任務工作流 | 外部工具與資料整合 | 全域行為規範 |
| 啟動方式 | 語意觸發或斜線指令 | 顯式工具呼叫 | 始終啟用 |
| 適合場景 | TDD、Git 工作流、除錯 | 資料庫連結、外部 API | 程式風格、命名慣例 |

5. 語意觸發：AI 自己判斷要用哪個技能

你在 SKILL.md 的 YAML 標頭寫的 description，其實就是告訴 AI「什麼時候該啟用我」的關鍵字。

舉個例子，你輸入「幫我看看這個失敗的 PR」，AI 會拿這句話去比對所有技能的描述，發現跟「GitHub Actions 偵錯技能」最吻合，就主動把那個技能載入。description 欄位寫得好不好，直接影響觸發的準確度。

如果你不想靠自動配對，也可以用 /skill-name 或 $ 符號手動指定。

6. 一個技能長什麼樣？

技能就是一個資料夾，裡面放一個 SKILL.md 檔案。存放位置依作用範圍而定：

* 團隊共用：./.github/skills/ 或 ./.claude/skills/
* 個人使用：~/.copilot/skills/ 或 ~/.claude/skills/

下面是一個「GitHub Actions 偵錯」技能的範例：

---
name: github-actions-failure-debugging
description: 用於偵錯失敗的 GitHub Actions 工作流。當使用者要求處理 CI/CD 失敗或分析 PR 狀態時使用。
allowed-tools: list_workflow_runs, summarize_job_log_failures, get_job_logs
context: fork
---

# GitHub Actions 偵錯專家

當處理失敗的工作流時，請務必遵循以下流程：

1. **狀態盤點**：使用 `list_workflow_runs` 查看最近的運行狀態，確認受影響的 Job。
2. **日誌摘要**：使用 `summarize_job_log_failures` 取得摘要，**不要**直接載入數千行原始日誌。
3. **隔離分析**：若需執行診斷腳本，使用 [debug-helper.py](./scripts/debug-helper.py)。
4. **驗證修復**：修完後在本地重現確認，再提交。

## 參考資源
- 查閱 [common-errors.md](./references/common-errors.md) 了解已知問題。


這裡有兩個值得注意的設定：allowed-tools 限制 AI 只能用特定的 GitHub 工具，context: fork 讓偵錯跑在獨立的子代理環境，不會把主對話的紀錄搞亂。

7. 所以然後呢？

老實說，Agent Skills 解決的問題不算新鮮——「怎麼讓 AI 記住你要它做什麼」這個需求一直都在。但它給了一個具體的格式和生態系。

比較有意思的是，團隊的知識傳遞方式可能會改變。以前是寫文件、開會講、Code Review 時順便教。以後可能是把架構決策和審查標準寫成 SKILL.md，新人的 AI 助手直接讀取就能套用。省不省時間還很難說，但至少方向對了。

Agent Skills：讓 AI 代理帶著「技能包」上工

1. 問題在哪？每次都要重來一遍

用 AI 寫程式碼的人大概都有這種經驗：開一個新對話，又要重新貼團隊的編碼規範，再交代一次 CI/CD 修復流程，再說明架構原則。反覆做這件事真的很煩，而且浪費 Token。

說到底，問題在於我們沒有一套標準格式來打包「AI 該知道的事」。Agent Skills 就是為了解決這個問題，把專業知識封裝成可重複使用的技能檔案，讓 AI 代理在需要時自己讀取，不用你每次手動餵。

2. 跨平台：寫一次就能到處用

我覺得 Agent Skills 最實在的地方，在於它是開放標準（基於 agentskills.io）。GitHub Copilot、Claude Code、Cursor、Gemini CLI 與 OpenAI Codex 都已經支援。

換句話說，你花時間整理好的技能檔可以跟著專案走，以 Git 做版本控制，團隊換工具也不必重寫。從 Cursor 搬到 Claude Code？技能檔直接帶過去。

3. 省 Token 的三層載入機制

把所有背景資料一股腦塞進上下文視窗，Token 消耗很快，AI 回答品質也會下降。Agent Skills 用了一個分層載入的做法：

1. 發現階段：系統啟動時只讀 SKILL.md 的 YAML 標頭（名稱和描述），大概 30-50 個 Token。
2. 指令載入：使用者的請求跟某個技能對上了，才把完整的 Markdown 內容讀進來。
3. 資源存取：執行任務時才去抓資料夾裡的腳本或參考文件。

AI 因此可以同時「知道」上百種技能存在，卻不必為此多花 Token。這個設計蠻務實的。

4. Skills、MCP、自定義指令，三者差在哪？

我自己的理解方式：

* MCP (Model Context Protocol) 是「手」：負責連接外部工具，像資料庫 API 或檔案系統。
* Agent Skills 是「操作手冊」：告訴 AI 用那些工具的時候該怎麼做，定義工作流程。
* 自定義指令是「專案規範」：像 .claude.md 或 .cursorrules，寫全域通用的程式風格和命名慣例。

| 特性 | Agent Skills | MCP 伺服器 | 自定義指令 |
|------|-------------|-----------|-----------|
| 定位 | 任務工作流 | 外部工具與資料整合 | 全域行為規範 |
| 啟動方式 | 語意觸發或斜線指令 | 顯式工具呼叫 | 始終啟用 |
| 適合場景 | TDD、Git 工作流、除錯 | 資料庫連結、外部 API | 程式風格、命名慣例 |

5. 語意觸發：AI 自己判斷要用哪個技能

你在 SKILL.md 的 YAML 標頭寫的 description，其實就是告訴 AI「什麼時候該啟用我」的關鍵字。

舉個例子，你輸入「幫我看看這個失敗的 PR」，AI 會拿這句話去比對所有技能的描述，發現跟「GitHub Actions 偵錯技能」最吻合，就主動把那個技能載入。description 寫得好不好，直接影響觸發的準確度。

如果你不想靠自動配對，也可以用 /skill-name 或 $ 符號手動指定。

6. 一個技能長什麼樣？

一個技能就是一個資料夾，裡面放一支 SKILL.md 檔案。存放位置依作用範圍而定：

* 團隊共用：./.github/skills/ 或 ./.claude/skills/
* 個人使用：~/.copilot/skills/ 或 ~/.claude/skills/

下面是一個「GitHub Actions 偵錯」技能的範例：

---
name: github-actions-failure-debugging
description: 用於偵錯失敗的 GitHub Actions 工作流。當使用者要求處理 CI/CD 失敗或分析 PR 狀態時使用。
allowed-tools: list_workflow_runs, summarize_job_log_failures, get_job_logs
context: fork
---

# GitHub Actions 偵錯專家

當處理失敗的工作流時，請務必遵循以下流程：

1. **狀態盤點**：使用 `list_workflow_runs` 查看最近的運行狀態，確認受影響的 Job。
2. **日誌摘要**：使用 `summarize_job_log_failures` 取得摘要，**不要**直接載入數千行原始日誌。
3. **隔離分析**：若需執行診斷腳本，使用 [debug-helper.py](./scripts/debug-helper.py)。
4. **驗證修復**：修完後在本地重現確認，再提交。

## 參考資源
- 查閱 [common-errors.md](./references/common-errors.md) 了解已知問題。


這裡有兩個值得注意的設定：allowed-tools 限制 AI 只能用特定的 GitHub 工具，context: fork 讓偵錯跑在獨立的子代理環境，不會把主對話的紀錄搞亂。

7. 所以然後呢？

老實說，Agent Skills 解決的問題不算新鮮，「怎麼讓 AI 記住你要它做什麼」這個需求一直都在。但它提供了一個具體的格式與生態系。

比較有意思的是，團隊的知識傳遞方式可能會改變。以前是寫文件，開會講，Code Review 時順便教。以後可能是把架構決策和審查標準寫成 SKILL.md，新人的 AI 助手直接讀取就能套用。能不能省時間還很難說，但至少方向是對的。