Anthropic 工程師的 Agent Skills 完全指南 — 九大類別 × 九個技巧
Skills 不只是 markdown 檔案——這是 Thariq 在文章開頭直接點破的誤解。
Thariq（@trq212）是 Anthropic 工程師，長期深度參與 Claude Code 的開發與內部使用。他在 2026 年 3 月發布了一篇 X Article，整理了 Anthropic 內部數百個 skills 的分類框架與製作心得。這篇文章對於任何認真建設 agent 系統的團隊都是高密度的參考材料。
為什麼 Skills 重要
“Skills have become one of the most used extension points in Claude Code. They’re flexible, easy to make, and simple to distribute. But this flexibility also makes it hard to know what works best.”
Skills 的核心能力在於它們是資料夾（folder），而不只是一個文字檔。一個 skill 可以包含：
- 說明文件（SKILL.md）
- 輔助腳本（scripts/）
- 範本資產（assets/）
- 設定檔（config.json）
- 子參考檔案（sub-files，按需載入）
- 動態 hooks（PreToolUse / PostToolUse）
這讓 skills 從「提示詞片段」升級成「agent 的 action space 設計單元」。每個 skill 定義了 agent 在特定任務域的能力邊界、操作規範、和執行護欄。
九大類別總覽
| # | 類別 | 核心用途 | Thariq 範例 |
|---|---|---|---|
| 1 | Library & API Reference | 教 agent 正確使用內部函式庫 | billing-lib, frontend-design |
| 2 | Product Verification | 驅動產品驗證流程 | signup-flow-driver, checkout-verifier |
| 3 | Data Fetching & Analysis | 連接資料與監控堆疊 | funnel-query, grafana |
| 4 | Business Process & Team Automation | 自動化重複工作流 | standup-post, create-ticket |
| 5 | Code Scaffolding & Templates | 產生框架樣板 | new-workflow, create-app |
| 6 | Code Quality & Review | 強化程式碼品質 | adversarial-review, code-style |
| 7 | CI/CD & Deployment | 擷取、推送、部署 | babysit-pr, deploy-service |
| 8 | Runbooks | 症狀 → 調查 → 結構化報告 | service-debugging, oncall-runner |
| 9 | Infrastructure Operations | 有護欄的例行維護 | resource-orphans, cost-investigation |
九個製作技巧總覽
| # | 技巧 | 一句話重點 |
|---|---|---|
| 1 | 別寫 Claude 本來就知道的事 | 只放能推翻 Claude 預設行為的資訊 |
| 2 | 建立 Gotchas 區塊 | 每次踩坑就加一行，持續累積最高信號內容 |
| 3 | 使用檔案系統與漸進式揭露 | Hub + Spoke 結構，按需載入細節 |
| 4 | 避免將 Claude 限縮太死 | 寫意圖（intent），不寫步驟（steps） |
| 5 | 思考 setup 流程 | 用 config.json 儲存設定，未設定時問使用者 |
| 6 | Description 欄位是給模型的觸發條件 | 寫「什麼時候觸發」，不寫「做什麼」 |
| 7 | Memory 與資料儲存 | append-only log / JSON / SQLite，用 ${CLAUDE_PLUGIN_DATA} |
| 8 | 存放腳本讓 Claude 組合 | 提供可組合的函式，Claude 用回合做決策而非重建樣板 |
| 9 | 按需 Hooks | /careful、/freeze 等只在 skill 啟動時生效的護欄 |
SuperPortia 的對照分析
SuperPortia 目前在 superportia-ops/.claude/skills/ 有 29 個 skills。以下是對應 Thariq 框架的覆蓋情況：
| Thariq 類別 | SP 對應 Skills | 覆蓋狀況 |
|---|---|---|
| Library & API Reference | superportia-ui, dev-workflow | 部分（缺系統性 Gotchas 區塊） |
| Product Verification | — | 缺失（Bridge / Command Center 無自動驗證） |
| Data & Analysis | superset | 部分（NQ Scout pipeline 可正式化） |
| Business Automation | daily-cycle, task-dispatch, create | 良好（WO 系統是 Thariq Tasks 的對等物） |
| Scaffolding & Templates | create, architecture-doc | 良好（/create skill 涵蓋新專案流程） |
| Code Quality & Review | code-review, code-standards, codex-review | 良好（但缺 adversarial-review 子 agent 模式） |
| CI/CD & Deployment | deploy-checklist, dev-workflow | 部分（主要仍為手動 wrangler 流程） |
| Runbooks | incident-response | 部分（SRE patrol 腳本未正式化為 skill） |
| Infrastructure Ops | site-audit, deploy-checklist | 部分（SRE 腳本可轉為 skill 格式） |
三個立即可改善的行動
[!important] 優先行動 #1 — 所有 skills 加 Gotchas 區塊
目前 SP 的 skills 大多有操作說明，但缺少「踩坑記錄」。從最常用的 task-dispatch、obsidian、deploy-checklist 開始，加入 ## Gotchas 區塊，持續累積失敗模式。
[!important] 優先行動 #2 — 重寫所有 skill 的 description 欄位
現在的 description 多是「這個 skill 做什麼」，應改成「什麼時候應該觸發這個 skill」。這直接影響 Claude 的 skill 自動啟動決策。
[!important] 優先行動 #3 — 建立 Product Verification skill
Bridge 和 Command Center 目前沒有任何自動化驗證流程。參考 Thariq 的 signup-flow-driver 模式，用 Playwright 或 tmux driver 建立一個可重複執行的驗證 skill。
九篇分文導覽
以下每篇文章深入探討一個類別，包含 Thariq 的原始框架、範例解析、以及 SuperPortia 的實戰對照：
- Thariq Skills — Library & API Reference — 如何教 agent 用好內部函式庫
- Thariq Skills — Product Verification — 自動化產品驗證的正確姿勢
- Thariq Skills — Data Fetching & Analysis — 連接資料堆疊的 skill 設計
- Thariq Skills — Business Process & Team Automation — 一個指令搞定重複工作流
- Thariq Skills — Code Scaffolding & Templates — 框架樣板生成的 skill 模式
- Thariq Skills — Code Quality & Review — adversarial-review 與程式碼審查
- Thariq Skills — CI/CD & Deployment — 部署 pipeline 的 skill 封裝
- Thariq Skills — Runbooks — 症狀到報告的結構化調查流程
- Thariq Skills — Infrastructure Operations — 有護欄的例行維護自動化
我們的觀點：Skills 是 Action Space 設計
Thariq 的框架讓我們重新理解 skills 的本質。
Skills 不只是「提示詞管理工具」。在 Thariq — Seeing like an Agent 中，Thariq 描述了 agent harness 設計最難的部分——建構 action space。Skills 正是 action space 的模組化設計單元：每個 skill 定義了 agent 在特定域的感知範圍（讀哪些 context）、決策邏輯（怎麼判斷）、和執行護欄（什麼不能做）。
從「幾行 markdown」到「完整的 action space 模組」，差距在於：
- 是否有 Gotchas 記錄失敗模式
- 是否用 Hub + Spoke 結構做漸進式揭露
- description 是否寫觸發條件而非功能摘要
- 是否有 on-demand hooks 提供情境式護欄
- 是否有 config.json 記憶跨 session 的設定
SuperPortia 的 29 個 skills 已經在對的方向上，但大多數仍是「平面的 SKILL.md」——距離 Thariq 描述的「folder + scripts + assets + hooks」完整形態還有一段路。這份指南是我們持續迭代的基準。
延伸閱讀
- 原始資料來源：Thariq X Article (2026-03-17) — via 夏哥 manual ingestion
- Vault 筆記：Thariq — How We Use Skills | Thariq — Seeing like an Agent
- 相關 SP 規格：EGS §4.1 — SP 技能分類原則（Rule vs Skill vs Hook）
...派遣紀律的背後設計參考 [[Orchestrator 紀律方法論]]；關於 Thariq 的 Skills 架構如何影響這套設計，詳見 [[Thariq Agent Skills 完整指南]]。 團隊組成：五個引擎，各司其職 Claude Code Opus —...
...文章記錄我們怎麼從「靠 agent 自律」走到「靠系統約束」的過程。 延伸閱讀 本文著重 orchestrator 紀律設計。關於 agent skills 的完整架構，參考 [[Thariq Agent Skills 完整指南]]；關於多代理 CLI 協作的實戰操作，參考 [[多代理 CLI 協作實錄]]；關於 Beast Mode 自動研究如何配合 orchestrator，參考...
...這給 agent 意圖和資源，讓它自己決定執行順序——符合 Thariq 技巧 #4「避免將 Claude 限縮太死」。 回到總文 本文是九大類別系列的第四篇。完整框架與 SuperPortia 對照請見： [[Anthropic 工程師的 Agent Skills 完全指南 — 九大類別 × 九個技巧]]
...lifecycle." 好的 description（觸發條件）： "Monitors a PR until it merges. Trigger on 'babysit', 'watch CI', 'make sure this lands'." 這個原則適用於所有 SP 的 deployment skills——description 應該寫人類自然說出的觸發語句。 回到總文...
...e Quality skills 可以「run automatically via hooks or GitHub Actions」。這對應到 SP 的 PostToolUse hooks——每次 agent 寫完程式碼，hook 可以自動觸發 linter 或基本的品質檢查。 目前 SP 的 hooks 主要做安全性阻擋（防止危險指令），還沒有做主動的品質觸發。這是一個可探索的方向。 回到總文...
...訊號觸發了」而不需要人工查。 與 UB 的關係 SP 的 Cloud UB 本身就是一個「知識分析堆疊」—— 相當於一個內建的 Data Analysis skill。但它目前只被 agent 用於查知識，還沒有被用於查「agent 自身的行為數據」（哪些 skills 被觸發最多、哪些 WO 常卡住）。這是 PAM 的未來延伸方向。 回到總文 本文是九大類別系列的第三篇。完整框架與...
...* - Library & API Reference → 低 HITL（純知識提供） - Product Verification → 中 HITL（驗證結果需要人判斷） - Infrastructure Operations → 高 HITL（破壞性操作必須人確認） 設計 skill 時，提前決定「這個 skill 在哪些點需要停下來等人」，是最重要的架構決策之一。 回到總文...
...skill。 建議做法 為 Cloudflare D1 + Workers 建立一個獨立的 skill，包含： （1）D1 binding 的正確語法（容易因版本變動踩坑） （2）wrangler.toml 設定的常見錯誤 （3）Workers 環境變數 vs. Secrets 的使用邊界 從最近踩過的坑開始填，3-5 條就有效。 回到總文 本文是九大類別系列的第一篇。完整框架與...
...三個必驗的點： 1. Command Center 首頁是否正常載入（HTTP 200） 2. /api/projects 是否回傳正確格式 3. 最近一次修改的功能是否仍然運作 回到總文 本文是九大類別系列的第二篇。完整框架與 SuperPortia 對照請見：...
...調查期間，agent 有完整的讀取權限，但寫入和刪除操作被護欄阻擋——直到人工確認（HITL）才能執行修復。 回到總文 本文是九大類別系列的第八篇。完整框架與 SuperPortia 對照請見： [[Anthropic 工程師的 Agent Skills 完全指南 — 九大類別 × 九個技巧]]
L2 rule 強制要求載入。兩者缺一不可。 ADR-0010 scaffold 是最好的候選 SP 的 ADR-0010 定義了 monorepo 分拆的標準結構。這個結構——加上 的驗證——是一個非常好的 skill 強化對象： 回到總文 本文是九大類別系列的第五篇。完整框架與 SuperPortia 對照請見：...