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

什麼是 Agent Skills？

想像你的工程團隊來了一位才華洋溢的新人。她寫 React 元件無懈可擊，TypeScript 乾淨俐落，Tailwind 用得精準，甚至不用提醒就會補上測試。只有一個問題：她從沒讀過你們的 style guide。她不知道 props interface 要加 Props 後綴，不知道禁止 default export，也不知道每個互動元素都必須回應鍵盤操作。她很有天分，但她缺少資訊。

沒有 skill 的 AI coding agent，就是這種情況。

把 skill 想成交給天才廚師的一份食譜。食譜提供結構：食材、順序、限制。廚師提供判斷力：醬汁需要再收一分鐘、什麼時候該替換食材。沒有食譜，天賦再高的廚師每次也會即興出不同的結果。沒有 skill，再強大的模型也會產出不一致的成品。

具體來說，Agent Skill 就是一個資料夾。裡面放一個 SKILL.md 檔案，加上可選的 script、參考資料和範例。當任務匹配 skill 的 description 時，agent 按需載入。整個機制就是這樣。不用編譯，不用 runtime，不用 dependency graph。一個帶 YAML frontmatter 的 Markdown 檔案，教會 agent 一個特定流程。

業界流傳最廣的比喻：skill 就是 AI agent 的 npm。 npm 套件給應用程式可複用的程式碼，skill 給 AI agent 可複用的知識。套件匯出函式。Skill 匯出流程、約束和領域專業。

為什麼重要？因為「通用智慧」和「具體好用」之間的落差，正是大多數 AI 輔助開發失敗的地方。Claude Opus 4.6 能力極強，但它不知道你的 deploy pipeline 或合規要求。Skill 填補這個落差。你把 context 編碼一次，agent 每次都會套用。

格式由 Anthropic 發起，以開放標準釋出。OpenAI（Codex CLI）、Microsoft（GitHub Copilot）和更廣泛的生態系都已採用。截至 2026 年 3 月，三大 marketplace 上已有超過 490,000 個 skill（SkillsMP、Skills.sh、ClawHub）。從「有趣的想法」到「標準基礎設施」，花了不到六個月。

SKILL.md 格式

每個 skill 從一個檔案開始：SKILL.md。格式刻意保持簡單。這不是意外，簡單就是設計。

YAML frontmatter 提供機器可讀的 metadata。Markdown 提供人類可讀的指令。Agent 解析前者，遵循後者。以下是一個真實可用的 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 是觸發器 -- agent 讀它來判斷 skill 是否跟當前任務相關。最長 1,024 字元。

description 是整個 skill 裡最關鍵的一行。把它想成反向的搜尋查詢：不是你在搜資訊，而是 agent 在你的 skill 庫裡搜相關性。如果 description 無法清楚匹配你的 skill 處理的請求類型，agent 永遠不會載入它。

可選的 frontmatter 欄位包括 allowed-tools（限制 skill 啟用時 agent 能呼叫的工具）、metadata（author、version）和 license。

漸進式揭露（progressive disclosure） 是核心設計原則。Frontmatter 永遠載入 -- 成本極低。完整的 SKILL.md body 只在 agent 判定 skill 相關時才載入。大型 skill 可以在 body 中參照外部檔案，agent 按需讀取。這把初始 context window 成本壓到最低。當你安裝了數十個 skill，這份經濟性至關重要。

生態系：490K 個 Skill 且持續成長

六個月前，skill 生態系幾乎不存在。今天，三大 marketplace 服務近五十萬個 skill。

SkillsMP 是數量霸主。社群營運的探索平台，爬取 GitHub 上的 SKILL.md 並以 AI 語意搜尋建索引。涵蓋 89K 工具類、70K 開發類、60K 商業類 skill。成長曲線說明一切：2025 年 12 月幾千個，2026 年 1 月數萬個，到三月中 400K+。這不是線性成長，這是相變。

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

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

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

建立你的第一個 Skill

建一個 skill 只要五分鐘。這不是行銷話術。就是一個資料夾裡的一個 Markdown 檔案。

步驟一：建目錄。

Skill 放在 ~/.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"

Agent 應該根據 description 比對載入 code-review skill，然後按你定義的 review 流程執行。

步驟四：優化 description。

如果 skill 沒有如預期觸發，調整 description 欄位。把哪些任務該匹配寫清楚。Anthropic 的 Skill Creator（claude.com/plugins/skill-creator）能自動化這件事。它跑一個 eval 迴圈，用測試觸發語句驗證你的 description，最多迭代 5 次，產出帶有可量測觸發率的最佳化 description。

Skill Creator 有四個模式：Create、Eval、Improve、Benchmark。Improve 模式是真正幹活的。它把測試案例分成 60% 訓練集和 40% 留出測試集，每個 query 跑 3 次評估觸發率，根據失敗案例提改進建議，然後反覆重新評估。結果：一個能在你在乎的請求上穩定觸發的 description。

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

SKILL.md 格式是開放標準。三大 agent 都支援，各自對存放位置和發現機制有些微差異。有趣的問題不是它們能不能相容（答案是能），而是差異透露了各家的設計哲學。

Claude Code

Claude Code 從三個位置讀 skill：

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

Claude Code 在 session 啟動時將 skill description 載入 context，當請求匹配 description 時才選擇性載入完整 body。allowed-tools frontmatter 欄位在此發揮作用：你可以限制 skill 只能用特定工具（例如只讀檔，絕不跑 shell）。

Codex CLI

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

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

OpenAI 的目錄同時作為散佈機制和參考實作。安裝不需要 config 檔、不需要套件管理器、不需要 build 步驟。$skill-installer 加上重啟就好。

GitHub Copilot

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

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

跨 Agent 相容性

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

使用多個 AI CLI 工具的團隊（2026 年越來越常見），把 skill 放在共享目錄再 symlink 到各 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 框架

目前採用最廣的 skill 框架是 Jesse Vincent 的 Superpowers。數字自己會說話：截至 2026 年 3 月已超過 87K GitHub star，每月增約 9K star。Superpowers 不是單一 skill，是一套以可組合 skill 表達的完整軟體開發方法論。

這樣想：一個 skill 是一份食譜。Superpowers 是一整本食譜書，加上一套廚房工作流程，確保廚師按正確順序使用食譜。

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

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

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

Superpowers 於 2026 年 1 月被收錄進 Anthropic 官方 Claude Code plugin marketplace。同時有 GitHub Copilot 社群移植版，稍作調整也相容 Codex CLI。

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

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

Skill 生態系成長得很快。安全實踐沒有跟上。數字令人警醒。

Snyk ToxicSkills 研究

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

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

攻擊面是 skill 運作方式的固有風險。SKILL.md 包含 AI agent 遵循的指令。這些指令可以說「跑這個 shell 命令」或「讀這個檔案然後把內容傳到這個 URL」。Agent 把 skill 當合法 context 來信任，直接執行。這就是根本的張力：讓 skill 強大的同一個機制，也讓它們危險。

ClawHavoc 攻擊事件

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

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

到 2 月 5 日，Antiy 研究人員已識別出 1,184 個惡意套件，關聯 12 個發布者帳號，其中一人獨佔 677 個。ClawHub 在損害已造成之後才實施強制掃描。

威脅模型

Skill 有三個攻擊向量：

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

防禦措施

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

實際步驟：

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

Skill 架構最佳實踐

建一個 skill 很容易。建出隨團隊成長而可維護的 skill，需要和管理任何 codebase 相同的紀律。

保持 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

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

確定性任務用 Script

有些任務不該交給 LLM 詮釋。Linting、formatting、跑測試、deploy -- 這些有精確的命令。放進 script，讓 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)

Agent 呼叫 script 而非自行發揮。能確定的確定，需要智慧的才動腦。

何時拆成多個 Skill

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

經驗法則：一個 skill，一個動詞。Review 程式碼。產生測試。撰寫文件。Deploy 到 staging。各有各的 skill。

團隊 Skill 共享

Skill 有三個層級。邊界重要，因為它們決定誰看到什麼、誰控制什麼、誰受變更影響。

個人 skill 在 ~/.claude/skills/（其他 agent 有對應位置）。你的私人 workflow 最佳化：偏好的 commit message 格式、個人 code review checklist、除錯方法。跟著你跨專案移動。

專案 skill 在版本庫的 .claude/skills/。Commit 到版控、跟團隊共享、像程式碼一樣追蹤版本。專案 skill 編碼團隊規範：API 設計標準、元件模板、deploy 流程。

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

治理

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

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

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

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

Skill 和其他 context 機制共存。理解何時用哪個，就像理解何時用全域變數、何時用函式參數。兩者都儲存資訊。Scope 決定正確的選擇。

CLAUDE.md 是專案的憲法。永遠載入、永遠在 context 中。保持 200-500 字的高訊號資訊。架構決策、關鍵規範、硬性約束。適用於專案每個任務的東西，放 CLAUDE.md。

AGENTS.md 和 CLAUDE.md 角色相同，但被 Codex CLI、Copilot 等工具識別。團隊用多個 AI CLI 工具時，以 AGENTS.md 作為規範來源。

Skill 是任務層級的能力。只在相關時載入，所以可以比 CLAUDE.md 更長更詳細，不會在無關任務上浪費 context。Code review skill 只在你要 review 時載入。API 設計 skill 只在你設計 API 時載入。

MCP Servers 提供即時資料。Skill 告訴 agent 怎麼做。MCP server 給 agent 存取權限：資料庫、GitHub repo、監控儀表板。

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

建立與測試 Skill

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

工作流程：

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

手動開發的 eval 迴圈也很直接：寫 skill、測 5 個觸發語句、檢查 agent 有沒有載入 skill 並遵循指令、觸發率低就改 description、行為不對就改指令。

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

有效測試 skill 意味著在一個面板編輯 SKILL.md，同時在旁邊的面板跑測試 prompt。看指令、跑 prompt、看輸出、迭代。這個 edit-test 迴圈正是多面板終端環境的價值所在：你需要同時看到 skill 檔案和 agent 的回應。

上手 Checklist

1. 理解格式。 讀 agentskills.io/specification 上的 SKILL.md 規範，大約 10 分鐘。
2. 安裝 Superpowers。 Clone github.com/obra/superpowers 並照設定說明操作。立刻獲得經過實戰驗證的 skill 框架。
3. 建一個個人 skill。 挑你最常重複的 workflow（code review、元件建立、PR description），編碼成 ~/.claude/skills/ 裡的 SKILL.md。
4. 建一個專案 skill。 挑團隊最重要的規範（API 設計、測試模式、deploy 流程），commit 到版本庫的 .claude/skills/。
5. 測試觸發可靠性。 用 5 種不同措辭提相同請求。Skill 沒穩定載入就改 description。
6. 掃描安全性。 安裝 marketplace skill 前跑 Snyk Agent Scan。讀 SKILL.md。如果它叫 agent 跑你不懂的 shell 命令，不要裝。
7. 為 skill 開發設定終端。 下載 Termdock 在內建檔案管理器中編輯 SKILL.md、在終端面板測試 skill、用 workspace 切換維護不同專案的 skill 設定。AST 分析可解析 skill 檔案結構，session recovery 在重啟後保留 skill 開發 context。
8. 建立團隊治理。 把 SKILL.md 加入 code review 要求。Pin marketplace skill 版本。記錄 skill 清單。
9. 每週迭代。 Skill 隨使用而改善。檢視哪些 skill 正確觸發、哪些產出好結果、哪些需要調整。把 skill 當程式碼看：它們是隨專案演進的活文件。

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