2026 Agent Skills 完全指南：建立、分享與保護 AI Agent 能力

什麼是 Agent Skills？

Agent Skill 是一個包含 SKILL.md 檔案的資料夾——外加可選的腳本、參考資料和範例——用來教 AI 編程代理如何執行特定任務。把它想成一份代理按需載入的自包含操作手冊。當你要求 Claude Code「按照我們的設計系統建立一個 React 元件」，一個 skill 就能提供代理該遵循的具體規範、模板和驗證步驟。

一個流傳很廣的比喻：skills 就是 AI agent 的 npm。 npm 套件給你的應用程式可複用的程式碼，skills 則給你的 AI agent 可複用的知識。套件匯出函式，skill 匯出流程、約束條件和領域專業。

為什麼 skills 重要？因為模型的原始智力不夠用。Claude Opus 4.6 能力極強，但它不知道你團隊的命名規範、你的部署流程、你的合規要求。Skills 填補了通用智力和專案級執行之間的鴻溝。沒有 skills，你每次提示都要重複同樣的 context；有了 skills，你編碼一次，代理每次都會套用。

這個格式由 Anthropic 發起，以開放標準釋出，已被 OpenAI（Codex CLI）、Microsoft（GitHub Copilot）及更廣泛的生態系採用。截至 2026 年 3 月，三大市場上已有超過 351,000 個 skills。從「有趣的想法」到「標準基礎設施」，只花了不到六個月。

SKILL.md 格式

每個 skill 都從一個檔案開始：SKILL.md。格式刻意保持簡單——YAML frontmatter 提供機器可讀的 metadata，接著是 Markdown 格式的代理指令。

以下是一個真實可用的 skill：

---
name: react-component
description: Create React components following our team conventions with TypeScript, Tailwind CSS, and proper test coverage.
---

## Instructions

When creating a new React component:

1. Use functional components with TypeScript interfaces for props
2. Place the component in `src/components/[ComponentName]/`
3. Create three files:
   - `index.tsx` — the component implementation
   - `index.test.tsx` — unit tests with Vitest
   - `index.stories.tsx` — Storybook story (if the component is visual)

## Conventions

- Props interface name: `[ComponentName]Props`
- Export as named export, never default export
- Use Tailwind CSS utility classes, no inline styles
- All interactive components must handle keyboard navigation

## Example

```tsx
interface ButtonProps {
  variant: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant, size = 'md', children, onClick }: ButtonProps) {
  return (
    <button
      className={cn(baseStyles, variantStyles[variant], sizeStyles[size])}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

Frontmatter 有兩個必要欄位。name 必須是小寫加連字號，最多 64 字元，必須和上層目錄名稱一致。description 是觸發器——代理讀取它來決定這個 skill 是否和當前任務相關。最多 1024 字元。

可選的 frontmatter 欄位包括 allowed-tools（限制 skill 啟用時代理可呼叫的工具）、metadata（author、version）和 license。description 欄位是整個 skill 中最關鍵的一行。如果描述無法清楚匹配你的 skill 處理的請求類型，代理永遠不會載入它。

漸進式揭露（progressive disclosure）是核心設計原則。Frontmatter 永遠載入（成本極低）。SKILL.md 的完整本文只在代理判定 skill 相關時才載入。大型 skill 可以在本文中參照外部檔案，代理按需讀取——將初始 context window 成本壓到最低。

生態系：351K 個 Skills 且持續成長

六個月前，skill 生態系幾乎不存在。如今三大市場共服務超過 351,000 個 skills。

SkillsMP 是數量霸主——社群營運的探索平台，爬取 GitHub 上的 SKILL.md 檔案並以 AI 語意搜尋建立索引。分類涵蓋 89K 工具類、70K 開發類、60K 商業類 skills。成長曲線驚人：2025 年 12 月幾千個、2026 年 1 月數萬個，到 3 月初垂直拉升至 351K。

Skills.sh 是 Vercel 的參戰之作。2026 年 1 月 20 日上線，六小時內達到 20,000 次安裝。Stripe 在上線數小時後就發布了自家的 skills。Skills.sh 的差異化在於策展品質、CLI 原生安裝體驗（npx skills install vercel-labs/react-best-practices），以及與 Snyk 合作的整合安全掃描。截至 2026 年 3 月，vercel-react-best-practices 等熱門 skill 已超過 10 萬次安裝。

ClawHub 是反面教材。OpenClaw 的市場成長快速，卻遭受 ClawHavoc 攻擊——341 個惡意 skills 散播 Atomic macOS Stealer（下方安全章節詳述）。信任傷害相當嚴重。

生態系的成長速度令人矚目。在 AI CLI 工具的全貌中，我們追蹤了 2026 年開發者工具演進之快。Skills 遵循同樣的壓縮時間軸：從概念到標準基礎設施，以月計而非以年計。

建立你的第一個 Skill

建一個 skill 只要五分鐘。以下是完整流程。

步驟一：建立目錄。

Skills 放在 ~/.claude/skills/ 供個人使用，或放在專案的 .claude/skills/ 目錄供團隊使用。

mkdir -p .claude/skills/code-review

步驟二：撰寫 SKILL.md 檔案。

---
name: code-review
description: Perform thorough code review with focus on security, performance, and maintainability. Flag issues by severity.
---

## Review Process

When asked to review code, follow this process:

1. **Security scan** — Check for injection vulnerabilities, exposed secrets, improper auth checks
2. **Performance** — Identify N+1 queries, unnecessary re-renders, missing indexes
3. **Maintainability** — Flag functions over 30 lines, nesting deeper than 3 levels, missing types
4. **Testing** — Verify test coverage for critical paths

## Output Format

For each issue found:

- **Severity**: Critical / Warning / Suggestion
- **Location**: File path and line range
- **Issue**: One-sentence description
- **Fix**: Concrete code change or direction

## Rules

- Never approve code with Critical issues
- If no issues found, explicitly state the code passes review
- Do not nitpick formatting — assume a formatter handles that

步驟三：測試。

開啟終端機，提出一個應該觸發此 skill 的問題：

claude "review the changes in my last commit"

代理應該根據描述匹配載入 code-review skill，然後按照你定義的審查流程執行。

步驟四：優化描述。

如果 skill 沒有如預期觸發，調整 description 欄位。具體說明哪些任務應該匹配。Anthropic 的 Skill Creator 工具（claude.com/plugins/skill-creator）可以自動化這件事——它執行一個 eval 迴圈，用測試觸發語句驗證你的描述，最多迭代 5 次，產出帶有可衡量觸發率的優化描述。

Skill Creator 有四個模式：Create、Eval、Improve、Benchmark。Improve 模式是精華所在——它把你的測試案例分成 60% 訓練集和 40% 留出測試集，每個查詢跑 3 次評估觸發率，根據失敗案例提出描述改進建議，然後反覆重新評估。

跨 Agent 使用 Skills：Claude Code、Codex CLI、Copilot

SKILL.md 格式是開放標準。三大主流 agent 都支援，各自對 skills 的存放位置和發現機制有些微差異。

Claude Code

Claude Code 從三個位置讀取 skills：

• 個人： ~/.claude/skills/ — 跨所有專案可用
• 專案： .claude/skills/ — 透過版本控制和團隊共享
• 市場： 透過 Anthropic 的外掛系統或手動安裝

Claude Code 在 session 啟動時將 skill 描述載入 context，當請求匹配描述時選擇性載入完整的 skill 本文。allowed-tools frontmatter 欄位在此發揮作用——你可以限制 skill 只能使用特定工具（例如只讀取檔案，絕不執行 shell 命令）。

Codex CLI

OpenAI 採用了 Agent Skills 標準，維護一個官方 Skills Catalog，位於 github.com/openai/skills——截至 2026 年 3 月有 13K+ GitHub stars 和 35 個策展 skills。Codex CLI 從以下位置讀取 skills：

• 專案： .agents/skills/ 或 .codex/skills/
• 目錄： 透過內建的 $skill-installer 命令安裝

OpenAI 的目錄同時作為散布機制和參考實作。安裝不需要設定檔、不需要套件管理器、不需要建置步驟——只要 $skill-installer 加上重啟。

GitHub Copilot

GitHub 在 2025 年 12 月宣布支援 Agent Skills。Copilot 從 .github/skills/ 讀取 skills，支援相同的 SKILL.md 格式。Skills 可在 Copilot coding agent、Copilot CLI 和 VS Code 的 agent mode 中運作。

Copilot 的發現機制遵循標準做法：從 frontmatter 讀取 name 和 description，匹配使用者請求，匹配成功時載入完整本文。.github/skills/ 目錄慣例讓 skills 自然地和 GitHub Actions、issue templates 等 GitHub 特定設定共存。

跨 Agent 相容性

一個寫得好的 skill 可以在三個 agent 之間無需修改地運作。SKILL.md 格式是最大公約數。唯一的差異是目錄慣例和可選的 agent 特定 frontmatter 欄位。如果你需要跨 agent 相容性，堅持核心規範：name、description 和 Markdown 本文。避免在 frontmatter 中使用 agent 特定的擴充欄位。

對於使用多個 AI CLI 工具的團隊——這在 2026 年越來越常見——把 skills 放在共享目錄並建立符號連結到各 agent 期望的路徑是實際的解決方案：

# 標準位置
mkdir -p .skills/code-review

# 為每個 agent 建立 symlink
ln -s ../../.skills .claude/skills
ln -s ../../.skills .agents/skills
ln -s ../../.skills .github/skills

Superpowers 與 Skills 框架

目前採用最廣的 skills 框架是 Jesse Vincent 的 Superpowers——超過 82K GitHub stars，截至 2026 年 3 月每週增加約 2K stars。Superpowers 不是單一 skill，而是一套以可組合 skills 表達的完整軟體開發方法論。

框架附帶 10+ 個核心 skills，涵蓋完整的開發生命週期：

• Brainstorming — 結構化的構思流程，強制代理在下手前探索多種方案
• Planning — 將任務拆分為帶依賴關係的子任務，估計複雜度，識別風險
• Test-Driven Development — 先寫失敗的測試，實作使其通過，重構。代理自動遵循紅-綠-重構循環
• Code Review — 多輪審查，涵蓋安全性、效能、正確性和風格
• Debugging — 系統化的假設驅動除錯，搭配 logging 和二分搜尋策略
• Documentation — 從程式碼生成文件，而非反過來

Superpowers 之所以有效，在於它的強制機制。這些 skills 不只是建議 TDD——它們在沒有測試的情況下拒絕撰寫實作程式碼。不只是建議規劃——它們在碰任何檔案之前就停下來產出計畫。這把通用 LLM 變成一個有紀律、有可重複方法論的開發者。

Superpowers 於 2026 年 1 月被收錄進官方 Anthropic Claude Code 外掛市場。開箱即用支援 Claude Code，稍作調整即可相容 Codex CLI 和 Copilot。

團隊在評估該自建 skills 還是採用框架時，答案通常是兩者兼具：採用 Superpowers 作為通用方法論，再為領域特定任務（你的 API 規範、部署流程、合規要求）建立自訂 skills。

安全性：13.4% 的 Skills 存在重大問題

生態系成長的速度超過了安全實踐。數字令人警醒。

Snyk ToxicSkills 研究

Snyk 的 ToxicSkills 研究於 2026 年 2 月 5 日發表，掃描了 3,984 個 skills，發現：

• 1,467 個 skills（36.8%） 至少有一個安全漏洞
• 534 個 skills（13.4%） 包含重大等級問題
• 76 個 skills 被確認為惡意載荷——竊取憑證、植入後門、資料外洩
• 91% 的惡意 skills 結合了 prompt injection 和傳統惡意軟體

攻擊面是 skills 運作方式的固有風險。SKILL.md 檔案包含 AI agent 遵循的指令。這些指令可以包括「執行這個 shell 命令」或「讀取這個檔案並將內容傳送到這個 URL」。代理將 skill 視為合法 context 來信任，直接執行指令。

ClawHavoc 攻擊事件

目前最嚴重的事件：研究人員在 ClawHub（OpenClaw 的市場）發現 341 個惡意 skills 散播 Atomic macOS Stealer（AMOS）。攻擊於 2026 年 1 月 27 日開始，1 月 31 日暴增，Koi Security 在 2 月 1 日將其命名為 ClawHavoc。

攻擊手法很巧妙。隱藏在 SKILL.md 中的惡意指令將 AI agent 當作可信任的中介人來利用。代理會向使用者顯示一個偽造的設定對話框，要求輸入系統密碼來「完成安裝」。這個 AMOS 變體會竊取瀏覽器憑證、鑰匙圈密碼、加密貨幣錢包資料、SSH 金鑰，以及常見使用者目錄中的檔案。

後續攻擊波使惡意 skills 總數超過 1,184 個，ClawHub 才實施強制掃描。

威脅模型

Skills 有三個攻擊向量：

1. Shell 執行 — Skills 可以指示代理執行任意 shell 命令。惡意 skill 可以下載並執行載荷。
2. 檔案系統存取 — Skills 可以指示代理讀取敏感檔案（.env、SSH keys、credentials）並外洩資料。
3. Prompt injection — Skills 可以嵌入覆蓋代理安全準則的指令，利用代理的可信任地位來社交工程使用者。

防禦措施

Snyk 和 Vercel 合作為 Skills.sh 建立了整合安全掃描。Snyk 的 Agent Scan 工具（labs.snyk.io）分析 SKILL.md 檔案以偵測已知惡意模式，對已確認惡意 skills 的召回率達 90-100%，對前 100 名合法 skills 的誤報率為 0%。

實際步驟：

1. 只從已驗證的來源安裝 skills。 有 Snyk 掃描的 Skills.sh 是最安全的市場。SkillsMP 適合探索，但安裝前請驗證。
2. 安裝前讀 SKILL.md。 它是一個 Markdown 檔案——花 2 分鐘讀完，就能看到 skill 指示代理做的所有事情。
3. 使用 allowed-tools 限制。 將 skills 鎖定在最小必要的工具集。程式碼審查 skill 不需要 shell 執行權限。
4. 代理要求輸入密碼時絕不配合。 沒有合法的 skill 需要你的系統密碼。
5. 定期稽核已安裝的 skills。 在你的專案上執行 snyk agent-scan .claude/skills/。

Skill 架構最佳實踐

建一個 skill 很容易。建立可隨團隊成長而維護的 skills 需要紀律。

保持 SKILL.md 在 500 行以內

SKILL.md 中的每一行在載入時都是 context window 的成本。保持主檔案聚焦在指令和約束條件。大量參考資料——API schema、大量範例、模板庫——移到 skill 參照的獨立檔案中。

---
name: api-design
description: Design REST API endpoints following our conventions.
---

## Instructions

Follow the API design guidelines in `./references/api-standards.md`.
Use the OpenAPI template in `./templates/endpoint.yaml` as a starting point.

## Key Rules

- All endpoints must use JSON:API format
- Authentication via Bearer token
- Rate limiting headers on every response
- Pagination via cursor, not offset

代理先讀取 20 行的 SKILL.md。只有在需要完整 API 標準或模板時才讀取參照的檔案。漸進式揭露的實際運作。

確定性任務用腳本

有些任務不該交給 LLM 詮釋。Linting、formatting、跑測試、部署——這些都有精確的命令。放進腳本，讓 skill 呼叫：

在 SKILL.md 中加入：

After Making Changes

Run the validation script: ./scripts/validate.sh

This script runs:

1. TypeScript type checking (tsc --noEmit)
2. ESLint with auto-fix (eslint --fix)
3. Unit tests (vitest run)
4. Build verification (next build)

代理呼叫腳本而非自行發揮每個步驟。能確定的確定，需要智慧的才動腦。

何時拆分成多個 Skills

當一個 skill 試圖服務兩種不同的觸發模式時就該拆。「程式碼審查」skill 和「PR 描述撰寫」skill 共享部分 context，但在不同的請求上觸發，產出不同的結果。如果你的 SKILL.md 中有些段落只適用於部分觸發條件，是時候拆分了。

經驗法則：一個 skill，一個動詞。審查程式碼。產生測試。撰寫文件。部署到 staging。每個各有自己的 skill。

團隊 Skill 共享

Skills 有三個層級，邊界很重要。

個人 skills 存放在 ~/.claude/skills/（其他 agent 有對應位置）。這些是你的私人工作流優化——你喜歡的 commit message 格式、你個人的程式碼審查清單、你的除錯方法。它們跟著你跨專案移動。

專案 skills 存放在版本庫內的 .claude/skills/。提交到版本控制、和團隊共享、像其他程式碼一樣追蹤版本。專案 skills 編碼團隊規範：API 設計標準、元件模板、部署流程。

市場 skills 從外部來源安裝。提供通用能力——Superpowers 作為方法論、語言特定的最佳實踐、框架特定的模式。

治理

對專案 skills 施加和程式碼同等的嚴謹度：

• 審查 skill 的變更。 SKILL.md 的修改影響團隊中的每位開發者。像審查 CI/CD pipeline 變更一樣審查它。
• 固定市場 skill 的版本。 記錄專案使用的外部 skills 版本。不要自動更新。
• 測試 skill 行為。 當 skill 變更時，驗證它在代表性任務上是否仍產出預期結果。

治理開銷很低，因為 skills 很小。一個典型的專案有 5-15 個自訂 skills，每個都是單一 Markdown 檔案。審查負擔可控。

Context Engineering：Skills vs CLAUDE.md vs AGENTS.md

Skills 和其他 context 機制共存。理解何時使用哪個可以避免重複並降低 context 成本。

CLAUDE.md 是你專案的憲法——永遠載入、永遠在 context 中。保持在 200-500 字的高訊號資訊。架構決策、關鍵規範、硬性約束。如果某件事適用於專案中的每個任務，它就屬於 CLAUDE.md。

AGENTS.md 和 CLAUDE.md 角色相同，但被 Codex CLI、Copilot 和其他工具識別。如果你的團隊使用多個 AI CLI 工具，以 AGENTS.md 作為規範來源。

Skills 是任務層級的能力。只在相關時載入，所以可以比 CLAUDE.md 更長更詳細，而不會在不相關的任務上浪費 context。程式碼審查 skill 只在你要求程式碼審查時載入。API 設計 skill 只在你設計 API 時載入。

MCP Servers 提供即時資料。Skills 告訴代理怎麼做。MCP servers 給代理存取權限——資料庫、GitHub 倉庫、監控儀表板。

反模式是把所有東西塞進 CLAUDE.md。如果你的 CLAUDE.md 超過 500 字，把任務特定的段落抽取成 skills。ETH Zurich 關於 context engineering 的研究（在我們的 AI CLI 工具指南中涵蓋）證實過度詳細的 context 檔案會降低代理效能。

建立與測試 Skills

Anthropic 的 Skill Creator 外掛（claude.com/plugins/skill-creator）是從構想到可用 skill 的最快路徑。它處理手動 skill 開發所需的建立-評估-改進循環。

工作流程：

1. Create — 描述 skill 該做什麼。Skill Creator 產生 SKILL.md 草稿。
2. Eval — 提供 5-10 個應該觸發此 skill 的測試查詢。工具衡量觸發率和回應品質。
3. Improve — 工具分析失敗案例、提出描述和指令修改建議、重新評估。自動迭代最多 5 次。
4. Benchmark — 對比優化後的 skill 和原版。工具產出 HTML 報告，展示觸發率、回應品質和逐次迭代的改進。

手動開發的 eval 迴圈也很直接：寫 skill、測試 5 個觸發語句、檢查代理是否載入 skill 並遵循指令、觸發率低就改進描述、行為不對就改進指令。

描述優化是最高槓桿的改進。「code review」這樣的描述觸發的請求比「Perform thorough code review with focus on security, performance, and maintainability. Flag issues by severity.」少得多。對任務、方法和輸出格式要具體。

有效測試 skills 意味著在一個窗格中編輯 SKILL.md，同時在旁邊的終端窗格中執行測試提示。看指令、跑提示、檢查輸出、迭代。這個編輯-測試循環正是多窗格終端環境的價值所在——你需要同時看到 skill 檔案和代理的回應。

上手清單

1. 理解格式。 閱讀 agentskills.io/specification 上的 SKILL.md 規範。大約 10 分鐘。
2. 安裝 Superpowers。 Clone github.com/obra/superpowers 並按照設定說明操作。立刻獲得一套經過實戰驗證的 skill 框架。
3. 建立一個個人 skill。 挑你最常重複的工作流——程式碼審查、元件建立、PR 描述——將它編碼為 ~/.claude/skills/ 中的 SKILL.md。
4. 建立一個專案 skill。 挑你團隊最重要的規範——API 設計、測試模式、部署流程——提交到版本庫的 .claude/skills/ 中。
5. 測試觸發可靠性。 用 5 種不同的措辭提出相同的請求。如果 skill 沒有穩定載入，改進描述。
6. 掃描安全性。 在安裝市場 skills 前執行 Snyk Agent Scan。讀 SKILL.md 檔案。如果它指示代理執行你不理解的 shell 命令，不要安裝。
7. 為 skill 開發設定終端機。 下載 Termdock — 在內建的檔案管理器中編輯 SKILL.md 檔案、在終端窗格中測試 skills、用 workspace 切換維護不同專案的 skill 設定。AST 分析可以解析 skill 檔案結構，session recovery 在重啟後保留你的 skill 開發 context。
8. 建立團隊治理。 將 SKILL.md 檔案加入程式碼審查要求。固定市場 skill 版本。記錄你的 skill 清單。
9. 每週迭代。 Skills 隨使用而改進。檢視哪些 skills 正確觸發、哪些產出好結果、哪些需要改進。把 skills 當程式碼看待——它們是隨專案演進的活文件。

Agent skills 生態系在六個月內從零成長到 351K。速度沒有放緩。現在投入 skill 素養的開發者——理解格式、建立團隊規範、保護供應鏈——會在 2026 年及以後持續累積這個優勢。