寫好一個 Skill 有多難？Anthropic 踩了幾百個坑之後的答案
整理版優先睇
寫好 Claude Code Skill 嘅核心：善用文件系統、Gotchas 同避免寫 Claude 已知嘅嘢
呢篇文章係 Anthropic 工程師 Thariq 分享佢哋內部用咗幾百個 Skill 之後嘅經驗。佢想解決嘅問題係：好多開發者以為 Skill 係一個 Markdown 文件，但其實用好 Skill 嘅關鍵係充分利用文件夾結構、配置同埋動態 Hook。整體結論係：寫好 Skill 唔靠初始版本多完整，而係靠不斷補充 Gotchas（踩坑清單），同埋記住「唔好寫 Claude 已知嘅嘢」。
Thariq 將內部嘅 Skill 分成 9 類，包括庫參考、驗證、數據分析、自動化、腳手架、代碼質素、CI/CD、Runbook 同基礎設施運維。佢認為最好嘅 Skill 通常乾淨利落地屬於某一類，而橫跨多類反而會令人困惑。佢特別強調驗證類同自動化類最易見效，因為佢哋解決嘅係每日重複嘅痛點。
至於點樣寫好 Skill，Thariq 提出咗幾個原則：首先，重點放喺 Claude 唔識嘅嘢，例如內部約定同踩坑經驗；其次，善用文件系統做漸進式披露，例如將詳細 API 拆到獨立文件；另外，description 字段要寫俾模型睇嘅觸發條件，而唔係俾人睇嘅摘要；最後，可以透過儲存數據實現記憶，同埋放腳本俾 Claude 組合使用。呢啲原則好多都係踩過坑先領悟到嘅。
- Skill 係一個文件夾，唔係單一 Markdown 文件；善用文件夾結構同配置先叫用好。
- Anthropic 將 Skill 分為 9 類，驗證類同業務流程自動化類最易見效，建議團隊從呢度入手。
- 必寫 Gotchas 清單，記錄 Claude 成日犯嘅錯，隨住使用不斷補充，呢個先係 Skill 嘅真正價值。
- 唔好寫 Claude 已知嘅編碼規範或最佳實踐，要專注於團隊特有嘅知識同內部約定。
- description 字段要寫明「咩時候觸發」，而唔係「呢個 Skill 做咩」，咁樣模型先會準確調用。
Thariq 原文
Anthropic 工程師 Thariq 發佈嘅原文，詳細講述寫好 Claude Code Skill 嘅經驗。
Claude Code Skills 文檔
官方文檔，包含 Skill 嘅完整配置參考同 frontmatter 說明。
Agent Skills 課程
Anthropic 官方提供嘅 Agent Skills 課程，適合進階學習。
Skill Creator 博客
Anthropic 關於 Skill Creator 嘅官方博客，介紹點樣測試、衡量同改進 Agent Skills。
先糾正一個常見誤解：Skill 係文件夾，唔係單一 Markdown
好多人以為 Skill 就係一個 SKILL.md 文件，但其實呢個只係最基本嘅用法。Skill 嘅本質係一個文件夾，入面可以放 腳本、數據、模板、配置，Claude 可以主動發現、探索同操作呢啲文件。
另外，Skill 仲支援好多配置選項，包括動態註冊 Hook。Anthropic 內部用得最好嘅 Skill，恰恰係充分利用咗文件夾結構同配置選項嘅。
9 類 Skill：睇下你嘅團隊仲缺邊啲
Thariq 將內部所有 Skill 盤點之後，發現大致可以歸為 9 類。最好嘅 Skill 通常乾淨利落地屬於某一類，而令人困惑嘅 Skill 往往橫跨好幾類。呢個分類可以當作自查清單：
- 庫同 API 參考：教 Claude 正確使用某個庫、CLI 或 SDK，通常附帶代碼片段同踩坑清單。
- 產品驗證：配合 Playwright、tmux 等工具驗證代碼正確性，Thariq 認為值得工程師花一週打磨。
- 數據獲取與分析：連接到數據同監控系統，包含帶憑據嘅腳本、Dashboard ID 同常見查詢。
- 業務流程自動化：將重複工作流一鍵化，例如自動生成 standup 並發到 Slack，依賴其他 Skill 或 MCP。
- 代碼腳手架：為特定功能生成框架代碼，尤其適合有自然語言需求嘅場景。
- 代碼質量與審查：強制執行團隊編碼標準，可透過 Hook 或 GitHub Action 自動觸發。
- CI/CD 與部署：監控 PR、自動重試 flaky CI、解決合併衝突、灰度發佈自動回滾。
- Runbook：從症狀出發，走多工具調查流程，輸出結構化報告，將 on-call 經驗沉澱。
如果團隊啱開始用 Skill，可以從呢個清單出發，睇下邊幾類最快產生價值。我個人覺得驗證類同業務流程自動化類最易見效，因為佢哋解決嘅係每日重複嘅痛點。
點樣先寫好一個 Skill？六大原則幫你避開常見嘅坑
Anthropic 最近發佈咗 Skill Creator 簡化創建，但即使有工具輔助，下面呢啲原則仍然要靠自己把握。
重點一：唔好寫 Claude 已經知道嘅嘢。
Claude 本身識好多編程知識，所以 Skill 應該專注喺能夠將佢推出預設思維模式嘅資訊。例如 frontend-design Skill 會教 Claude 避免 AI 審美（例如 Inter 字體配紫色漸變），呢啲先係需要糾正嘅地方，而唔係「請寫出高質量代碼」。
重點二：好好寫 Gotchas 部分。
任何 Skill 入面信息量最高嘅就係 Gotchas（踩坑清單）。將 Claude 使用你嘅 Skill 時成日犯嘅錯記低，隨住使用不斷補充。我自己寫 Skill 嘅經驗都係：一開始二三十行，用咗一個月之後 Gotchas 部分比正文仲長。
重點三：用好文件系統同漸進式披露。
整個文件系統係 漸進式披露 嘅手段。喺 SKILL.md 話俾 Claude 知呢個 Skill 有咩文件，佢會喺適當時候去讀。最簡單係將詳細函數簽名同用法拆到 references/api.md，將模板放喺 assets/。
重點四：唔好將 Claude 釘死。
Skill 會被反覆使用，如果指令太具體，Claude 喺某啲場景下就會變得好死板。應該寫「通常流程係 A→B→C→D，但可以根據實際情況調整順序或跳過某啲步驟」，而唔係「必須按 A→B→C→D 執行」。
重點五：想清楚初始化流程。
如果 Skill 需要用戶提供上下文（例如 standup Skill 需要知道發去邊個頻道），可以將配置存到 config.json。第一次運行時如果唔存在就問用戶，之後直接讀取，唔好重複問。
重點六：description 字段係寫俾模型睇嘅。
Claude Code 啓動時會掃描所有 Skill 嘅 description，所以應該寫清楚「咩時候觸發」，例如「當用戶要求格式化代碼或代碼風格不一致時觸發」，而唔係「用於格式化代碼」。
重點七：為 Skill 加記憶同放腳本。
透過儲存數據（例如日誌文件）實現記憶，令 Claude 知道歷史變化。放輔助腳本同庫函數俾 Claude 組合，佢就可以專注喺決策而唔使寫樣板代碼。
Hook、統計同分發：令 Skill 更強大
Skill 可以包含 動態 Hook，喺被調用先激活，持續到會話結束。適合比較有態度嘅 Hook，例如 /careful 攔截 rm -rf、DROP TABLE 等危險操作，或者 /freeze 限制 Claude 編輯特定目錄之外嘅文件。
統計使用情況：用 PreToolUse Hook 記錄 Skill 使用日誌。
Anthropic 內部用一個 PreToolUse Hook 記錄每個 Skill 嘅使用情況，從而發現邊啲 Skill 高頻使用、邊啲觸發率低，幫助團隊調整。
分發方面，小團隊直接將 Skill 提交到倉庫嘅 .claude/skills 目錄就得。規模大咗之後，可以搭建內部 Plugin Marketplace，由團隊成員自行選擇安裝。Anthropic 內部冇中央團隊決定上架，而係先放 sandbox 目錄試用，有口碑再提 PR。
