Dec 22, 2025

Agent Skills 深度解析：AI Agent 能力擴展的開放標準

0. 前言：為什麼需要 Agent Skills？

隨著 AI Agent 的應用場景越來越廣泛，一個核心問題浮現：如何讓 Agent 具備特定領域的專業知識和能力？

傳統方法是：

把所有知識塞進 System Prompt（Context 爆炸）
為每個任務寫一個專門的 Agent（維護成本高）
硬編碼工具和流程（靈活性差）

Agent Skills 提供了一個優雅的解決方案：

Skills 是一個簡單、開放的格式，用於為 AI Agent 提供新的能力和專業知識。

這個標準最初由 Anthropic 開發，現已被多個主流平台採用：

Claude Code / Claude
OpenAI Codex
VS Code Copilot
Cursor / Amp / Letta
GitHub / goose

本文將從規範層級完整剖析 Agent Skills 的運作機制。

1. Agent Skills 核心概念

1.1 Skill 是什麼？

一個 Skill 本質上是：

一個包含指令、腳本和資源的目錄，
Agent 可以自動發現並在需要時載入使用。

可以把 Skill 想像成「Agent 的外掛程式」或「可熱載入的專業模組」。

1.2 Skill vs 傳統方法

特性	System Prompt	硬編碼工具	Agent Skills
Context 效率	一次載入全部	N/A	按需載入（Progressive Disclosure）
可維護性	差（一個大檔案）	中（程式碼）	好（模組化目錄）
可分享性	手動複製	需要部署	Git / Plugin
跨平台	需要轉換	完全不通用	統一標準
動態性	靜態	需重新部署	即時生效

1.3 Skill 的三種觸發方式

flowchart LR
  subgraph Triggers["Skill 觸發方式"]
    Explicit["顯式調用<br/>$skill-name 或 /skills"]
    Implicit["隱式調用<br/>Agent 自動匹配 description"]
    Reference["引用調用<br/>文檔中提及 Skill 名稱"]
  end

  Explicit --> Load["載入 SKILL.md"]
  Implicit --> Load
  Reference --> Load
  Load --> Execute["執行 Skill 指令"]

2. SKILL.md 規範詳解

2.1 檔案結構

每個 Skill 至少需要一個 SKILL.md 檔案，包含兩個部分：

---
# YAML Frontmatter（設定）
name: skill-name
description: Skill 描述
---

# Markdown Content（指令）

## Instructions
...

2.2 必要欄位

`name`（必填）

name: pdf-processing

驗證規則：

長度：1-64 字元
格式：小寫字母、數字、連字號（-）
不能以連字號開頭或結尾
不能有連續連字號
必須與父目錄名稱匹配
不能包含 XML 標籤或保留字

最佳實踐：

使用動名詞形式（verb + -ing）
例：generating-commit-messages、reviewing-code

`description`（必填）

description: Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

驗證規則：

長度：1-1024 字元
不能為空
不能包含 XML 標籤

關鍵要點：description 是 Agent 判斷是否使用該 Skill 的唯一依據。它必須包含：

做什麼：Skill 的核心功能
何時用：觸發場景和關鍵詞

# 好的 description（具體、包含觸發條件）
description: Generate clear commit messages from git diffs.
Use when writing commit messages, reviewing staged changes, or preparing PRs.

# 差的 description（太模糊）
description: Helps with git stuff

2.3 選填欄位

`allowed-tools`（實驗性）

限制 Skill 執行時可使用的工具：

allowed-tools: Read, Grep, Glob

用途：

創建唯讀 Skill
限制操作範圍
安全敏感場景

運作機制：當 Skill 被激活時，只有列出的工具可以無需額外權限確認。

`license`

license: Apache-2.0
# 或引用檔案
license: ./LICENSE

`compatibility`

compatibility: Requires Python 3.10+, pypdf and pdfplumber packages

說明環境需求，最多 500 字元。

`metadata`

metadata:
  author: zengineer
  version: "1.0.0"
  category: document-processing

自定義鍵值對，供客戶端使用。

2.4 完整範例

---
name: generating-commit-messages
description: >
  Generate clear, conventional commit messages from git diffs.
  Use when writing commit messages, reviewing staged changes,
  or preparing pull requests.
license: MIT
allowed-tools: Bash, Read
metadata:
  author: zengineer
  version: "1.0.0"
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged` to see changes
2. Analyze the changes and generate a commit message with:
   - Summary under 50 characters (imperative mood)
   - Blank line
   - Detailed description explaining what and why

## Format

<type>(<scope>): <subject>

<body>

<footer>

## Types

- feat: New feature
- fix: Bug fix
- docs: Documentation
- style: Formatting
- refactor: Code restructuring
- test: Adding tests
- chore: Maintenance

## Examples

feat(auth): add OAuth2 login support

Implement Google and GitHub OAuth2 providers.
Includes token refresh and session management.

Closes #123

3. 目錄結構

3.1 完整結構

my-skill/
├── SKILL.md              # 必要：主要指令和設定
├── scripts/              # 選填：可執行腳本
│   ├── process.py
│   └── helper.sh
├── references/           # 選填：額外文檔
│   ├── REFERENCE.md
│   └── FORMS.md
└── assets/               # 選填：靜態資源
    ├── template.txt
    └── config.json

3.2 各目錄用途

`scripts/`

存放 Agent 可執行的腳本：

# scripts/extract_pdf.py
import pdfplumber

def extract_text(pdf_path: str) -> str:
    with pdfplumber.open(pdf_path) as pdf:
        return "\n".join(page.extract_text() for page in pdf.pages)

if __name__ == "__main__":
    import sys
    print(extract_text(sys.argv[1]))

使用方式：在 SKILL.md 中引用

Run the extraction script:
```bash
python {baseDir}/scripts/extract_pdf.py input.pdf


`{baseDir}` 會被替換為 Skill 目錄的實際路徑。

#### `references/`

額外的說明文檔，按需載入：

```markdown
<!-- SKILL.md -->
For advanced patterns, see [REFERENCE.md](references/REFERENCE.md).

Agent 只有在需要時才會讀取這些檔案，節省 Context。

`assets/`

模板和靜態資源：

Use the template at `{baseDir}/assets/template.txt` as a starting point.

3.3 存放位置與優先級

Skills 可以存放在多個位置（優先級由高到低）：

範圍	位置	用途
專案	`./.codex/skills/` 或 `./.claude/skills/`	專案專用
倉庫根目錄	`$REPO_ROOT/.codex/skills/`	組織共用
使用者	`~/.codex/skills/` 或 `~/.claude/skills/`	個人跨專案
系統	`/etc/codex/skills/`	系統級共用
內建	打包在 CLI 中	預設功能

覆蓋規則：高優先級的 Skill 會覆蓋低優先級的同名 Skill。

4. Agent 如何載入 Skills

4.1 Discovery 機制

Agent 啟動時會執行 Skill Discovery：

flowchart TD
  Start["Agent 啟動"]
  Scan["掃描 Skill 目錄"]
  Parse["解析 SKILL.md Frontmatter"]
  Validate["驗證欄位"]
  Index["建立 Skill 索引<br/>(name + description)"]
  Inject["注入 System Prompt"]

  Start --> Scan --> Parse --> Validate
  Validate -->|有效| Index --> Inject
  Validate -->|無效| Error["記錄錯誤，跳過"]

4.2 Lazy Loading（延遲載入）

為了節省 Context，Agent 採用 Progressive Disclosure 策略：

啟動時：僅載入 name + description（~100 tokens/skill）
        ↓
激活時：載入完整 SKILL.md 內容（<5000 tokens 建議）
        ↓
需要時：按需載入 references/ 和 scripts/

這意味著即使有 100 個 Skills，啟動時的 Context 開銷也可控。

4.3 Skill 選擇機制

Agent 使用 純語言理解 來選擇 Skill，沒有：

Embedding 相似度搜尋
分類器或路由器
模式匹配規則

選擇流程：

flowchart LR
  User["使用者請求"]
  Reason["Agent 推理"]
  Match["比對 Skill descriptions"]
  Select["選擇最相關 Skill"]
  Load["載入完整內容"]

  User --> Reason --> Match --> Select --> Load

這就是為什麼 description 的撰寫如此關鍵。

5. Context 注入原理

5.1 雙層 Context 修改

當 Skill 被激活時，會修改兩個層面的 Context：

Conversation Context（對話上下文）

Skill 內容被注入為「使用者訊息」：

訊息 1（可見）：
<command-message>The "pdf-processing" skill is loading</command-message>
<command-name>pdf-processing</command-name>

訊息 2（隱藏，isMeta: true）：
[完整的 SKILL.md 內容，500-5000 詞]

這種雙訊息模式：

第一條訊息對使用者可見，作為 UI 回饋
第二條訊息隱藏，但發送給 Agent 處理

Execution Context（執行上下文）

如果 Skill 定義了 allowed-tools，執行上下文會被臨時修改：

# 偽代碼
def activate_skill(skill):
    # 保存原始工具權限
    original_permissions = get_current_permissions()

    # 設置 Skill 專屬權限
    set_permissions(skill.allowed_tools, pre_approved=True)

    # 執行 Skill
    yield execute_skill(skill)

    # 恢復原始權限
    set_permissions(original_permissions)

這創造了一個 臨時、範圍限定的工具存取權。

5.2 注入流程圖

sequenceDiagram
  participant User
  participant Agent
  participant SkillLoader
  participant LLM

  User->>Agent: "幫我處理這個 PDF"
  Agent->>Agent: 比對 Skill descriptions
  Agent->>SkillLoader: 載入 "pdf-processing" Skill
  SkillLoader->>SkillLoader: 讀取 SKILL.md
  SkillLoader->>Agent: 返回 Skill 內容

  Note over Agent: 注入 Conversation Context
  Agent->>Agent: 修改 Execution Context<br/>(pre-approve tools)

  Agent->>LLM: 發送完整訊息陣列<br/>(含 Skill 指令)
  LLM->>Agent: 執行結果

  Note over Agent: 恢復原始權限
  Agent->>User: 返回處理結果

5.3 與 Claude Agent SDK 的對比

Claude Agent SDK 使用不同的擴展機制：

特性	Agent Skills	Claude Agent SDK (MCP)
擴展方式	Prompt 注入	工具註冊
定義格式	Markdown + YAML	Python 裝飾器
執行方式	Agent 解釋指令	直接函數調用
Context 控制	Progressive Disclosure	按需載入
跨平台	是（開放標準）	否（Anthropic 專用）
適用場景	專業知識、工作流程	外部 API、計算任務

互補關係：

flowchart TD
  subgraph Skills["Agent Skills"]
    Knowledge["領域知識"]
    Workflow["工作流程"]
    BestPractice["最佳實踐"]
  end

  subgraph MCP["MCP Tools"]
    API["外部 API"]
    Compute["計算任務"]
    System["系統操作"]
  end

  Agent["AI Agent"]
  Skills --> Agent
  MCP --> Agent

Skills 提供「知道怎麼做」，MCP 提供「能夠做」。

6. 執行時行為詳解

6.1 Skill 激活條件

Skill 在以下情況被激活：

顯式指名

使用 $pdf-processing 處理這個檔案

描述匹配

幫我從這個 PDF 提取表格
# Agent 自動匹配含 "PDF", "extract", "table" 的 Skill

工具選擇
```
/skills  # 顯示可用 Skills 選單
```

6.2 Skill 作用範圍

重要：Skill 只在當前回合（turn）有效。

flowchart LR
  Turn1["回合 1<br/>激活 pdf-processing"]
  Turn2["回合 2<br/>需重新提及或匹配"]
  Turn3["回合 3<br/>..."]

  Turn1 --> Turn2 --> Turn3

  Note1["Skill 活躍"]
  Note2["Skill 已失效"]

  Turn1 -.- Note1
  Turn2 -.- Note2

如果需要持續使用 Skill，必須：

在每個回合提及 Skill 名稱
或確保請求匹配 Skill description

6.3 多 Skill 場景

當需要多個 Skills 時：

使用 $pdf-processing 和 $data-analysis 處理這份報告

Agent 會：

載入所有提及的 Skills
合併工具權限
按需執行各 Skill 的指令

7. 腳本執行詳解

7.1 腳本類型

Skills 支援多種腳本：

scripts/
├── process.py      # Python
├── helper.sh       # Bash
├── transform.js    # JavaScript
└── analyze.R       # R

7.2 執行方式

Agent 通過內建的 Bash 工具執行腳本：

<!-- SKILL.md -->
To extract text from PDF:

```bash
python {baseDir}/scripts/extract_pdf.py "$FILE_PATH"


### 7.3 腳本最佳實踐

```python
#!/usr/bin/env python3
"""PDF 文字提取腳本

Usage:
    python extract_pdf.py <input.pdf> [output.txt]

Requirements:
    pip install pdfplumber
"""

import sys
import pdfplumber

def main():
    if len(sys.argv) < 2:
        print("Error: Please provide a PDF file path", file=sys.stderr)
        print("Usage: python extract_pdf.py <input.pdf>", file=sys.stderr)
        sys.exit(1)

    pdf_path = sys.argv[1]

    try:
        with pdfplumber.open(pdf_path) as pdf:
            for i, page in enumerate(pdf.pages):
                print(f"--- Page {i+1} ---")
                print(page.extract_text())
    except FileNotFoundError:
        print(f"Error: File not found: {pdf_path}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

關鍵要點：

清楚的使用說明
完整的錯誤處理
有意義的錯誤訊息
正確的退出碼

8. 驗證與除錯

8.1 使用 skills-ref 驗證

# 安裝驗證工具
pip install skills-ref

# 驗證 Skill
skills-ref validate ./my-skill

# 輸出
✓ SKILL.md found
✓ Valid frontmatter
✓ name: "my-skill" (valid)
✓ description: 156 characters (valid)
✓ No validation errors

8.2 常見問題排查

Agent 不使用我的 Skill

檢查清單：

Description 是否具體？

# 不好
description: Helps with files

# 好
description: Extract text from PDF files. Use when working with PDFs.

YAML 語法正確？

---
name: my-skill
description: My description
---
# 注意開頭和結尾的 ---

檔案路徑存在？
```
ls ~/.claude/skills/my-skill/SKILL.md
```
啟用 debug 模式：
```
claude --debug
```

Skill 有錯誤

驗證依賴已安裝：
```
pip install pdfplumber
```

檢查檔案路徑語法：

# 正確
scripts/helper.py

# 錯誤（Windows 路徑）
scripts\helper.py

確保執行權限：
```
chmod +x scripts/*.py
```

9. 實戰範例

9.1 程式碼審查 Skill

---
name: reviewing-code
description: >
  Review code for best practices, potential bugs, and security issues.
  Use when reviewing code, checking PRs, or analyzing code quality.
allowed-tools: Read, Grep, Glob
metadata:
  version: "1.0.0"
---

# Code Review

## Checklist

1. **Code Quality**
   - Naming conventions
   - Code organization
   - DRY principle

2. **Error Handling**
   - Exception handling
   - Edge cases
   - Input validation

3. **Security**
   - SQL injection
   - XSS vulnerabilities
   - Secrets in code

4. **Performance**
   - Unnecessary loops
   - Memory leaks
   - N+1 queries

## Instructions

1. Use Glob to find relevant files
2. Use Read to examine code
3. Use Grep to search for patterns
4. Provide structured feedback

## Output Format

```markdown
## Code Review: [filename]

### Summary
[Brief overview]

### Issues Found

#### Critical
- [ ] Issue description

#### Warnings
- [ ] Issue description

#### Suggestions
- [ ] Improvement idea

### Positive Aspects
- Good practice observed


### 9.2 資料庫查詢 Skill

```yaml
---
name: querying-database
description: >
  Generate and execute SQL queries safely.
  Use when working with databases, analyzing data, or creating reports.
allowed-tools: Bash, Read
metadata:
  version: "1.0.0"
---

# Database Query Assistant

## Safety Rules

1. NEVER run DELETE, DROP, TRUNCATE without explicit confirmation
2. Always use LIMIT for SELECT queries
3. Prefer read-only operations

## Query Templates

### Basic Select
```sql
SELECT column1, column2
FROM table_name
WHERE condition
LIMIT 100;

Aggregation

SELECT column, COUNT(*), AVG(value)
FROM table_name
GROUP BY column
HAVING COUNT(*) > 1;

Instructions

Understand the data request
Identify relevant tables (check schema first)
Build query incrementally
Run with LIMIT first
Explain results clearly


### 9.3 多檔案 Skill 結構

documentation-generator/ ├── SKILL.md ├── references/ │ ├── style-guide.md │ └── templates.md ├── scripts/ │ └── generate_toc.py └── assets/ └── template.md


**SKILL.md**:

```yaml
---
name: generating-documentation
description: >
  Generate comprehensive documentation for code projects.
  Use when creating README, API docs, or technical documentation.
allowed-tools: Read, Grep, Glob, Write
---

# Documentation Generator

## Instructions

1. Analyze codebase structure
2. Identify key components
3. Generate documentation using templates

## References

- [Style Guide](references/style-guide.md)
- [Templates](references/templates.md)

## Generate TOC

```bash
python {baseDir}/scripts/generate_toc.py ./docs

Base Template

Use {baseDir}/assets/template.md as starting point.


---

## 10. 進階主題

### 10.1 Skill 組合模式

複雜任務可以組合多個 Skills：

```mermaid
flowchart LR
  User["處理這份報告"]

  subgraph Skills
    PDF["pdf-processing"]
    Data["data-analysis"]
    Report["report-generation"]
  end

  User --> PDF --> Data --> Report
  Report --> Output["最終報告"]

10.2 動態 Skill 載入

某些平台支援在執行時動態載入 Skills：

# 安裝 Skill
$skill-installer github:anthropics/skills/pdf-processing

# Skill 立即可用

10.3 Skill 與 Plugin 的關係

flowchart TD
  subgraph Plugin["Plugin Package"]
    PluginCode["Plugin 程式碼"]
    PluginSkills["Skills 目錄"]
  end

  PluginSkills --> Skill1["skill-a/"]
  PluginSkills --> Skill2["skill-b/"]

  Install["安裝 Plugin"]
  Available["Skills 自動可用"]

  Plugin --> Install --> Available

11. 與其他框架的整合

11.1 在 Claude Agent SDK 中使用 Skills 概念

雖然 Claude Agent SDK 不直接支援 Agent Skills 格式，但可以借鑒其設計：

from claude_agent_sdk import ClaudeAgentOptions

# 模擬 Skill 的 Progressive Disclosure
SKILL_DESCRIPTIONS = {
    "pdf-processing": "Extract text from PDFs...",
    "code-review": "Review code for best practices...",
}

SKILL_PROMPTS = {
    "pdf-processing": """
    # PDF Processing Instructions
    1. Use pdfplumber to extract text
    2. Handle multi-page documents
    ...
    """,
}

def build_system_prompt(active_skills: list[str]) -> str:
    base_prompt = "You are a helpful assistant."

    # 只載入需要的 Skill 內容
    skill_content = "\n".join(
        SKILL_PROMPTS[skill]
        for skill in active_skills
        if skill in SKILL_PROMPTS
    )

    return f"{base_prompt}\n\n{skill_content}"

11.2 LangChain 中的類似概念

# LangChain 的 Tool 可以類比為 Skills 中的 scripts/

from langchain.tools import tool

@tool
def pdf_extract(file_path: str) -> str:
    """Extract text from a PDF file."""
    import pdfplumber
    with pdfplumber.open(file_path) as pdf:
        return "\n".join(p.extract_text() for p in pdf.pages)

12. 設計哲學總結

12.1 核心原則

原則	實現方式
模組化	每個 Skill 獨立目錄
可發現	description 支援自動匹配
高效	Progressive Disclosure 節省 Context
可分享	Git + Plugin 生態系統
跨平台	開放標準，多平台支援

12.2 何時使用 Skills

適合場景：

專業領域知識（法律、醫療、金融）
重複性工作流程（Code Review、文件生成）
團隊共享的最佳實踐
需要結構化輸出的任務

不適合場景：

需要外部 API 調用（使用 MCP/Tools）
即時計算任務（使用程式碼執行）
需要狀態持久化（使用 Checkpointer）

13. 結語

Agent Skills 代表了 AI Agent 能力擴展的一個重要演進：

從硬編碼到模組化：Skills 讓 Agent 能力可以像 Plugin 一樣管理
從全量載入到按需載入：Progressive Disclosure 解決了 Context 爆炸問題
從封閉到開放：統一標準讓 Skills 可以跨平台復用

隨著越來越多平台採用這個標準，我們可以預見一個豐富的 Skills 生態系統的形成。