Skills

The Problem: AI Agents Forget, but the Task Doesn’t End 技術社群已經習慣「給人類看的 RFC」— Architecture Decision Records、incident postmortem、設計文件，模板都很成熟。但給 AI agent 之間用的非同步協作文件呢？少有公開討論。 最近處理一個跨三個 repo 的 schema migration：後端表結構改、前端 GraphQL 切換、行動端讀寫遷移，估計要 30+ 天，會跨越十多個獨立的 Claude session（不同時段、不同任務切片、不同筆電）。每次 session 結束、下一輪起來，前次的 context window 就消失了。問題不只是「上下文遺忘」，還包括： 上次 session 進度到哪？沒人記得。 之前否決過的方案？新 session 很容易「自信地重新提案」。 跨 repo 的「我改完了、等你那邊配合」訊息，怎麼跨越 session 邊界？ 某次踩的坑，下次會不會重蹈？ 我們最後長出一份 CUTOVER.md 放在獨立的 metadata repo，作為跨 session、跨 repo 的 out-of-band control plane。實戰一個月後，這份文件結晶出 8 個對 AI agent 特別有效的設計模式 — 它們幾乎都對應到分散式系統的經典概念。 The Architecture flowchart LR subgraph code[Code repositories] R1[backend repo] R2[frontend repo] R3[mobile repo] end subgraph plane[Control plane] DOC[CUTOVER.md<br/>append-only<br/>own repo] end subgraph time[AI sessions over time] S1[t1: backend session] S2[t2: frontend session] S3[t3: mobile session] S4[t4: backend session] end S1 -.modifies.-> R1 S2 -.modifies.-> R2 S3 -.modifies.-> R3 S4 -.modifies.-> R1 S1 -->|pull / push| DOC S2 -->|pull / push| DOC S3 -->|pull / push| DOC S4 -->|pull / push| DOC classDef p fill:#cce5ff,stroke:#007bff,color:#004085 classDef s fill:#d4edda,stroke:#28a745,color:#155724 classDef c fill:#f5f5f5,stroke:#333,color:#333 class DOC p class S1,S2,S3,S4 s class R1,R2,R3 c 每個 AI session 開場先 pull doc → 讀完上下文 → 完成任務 → push update。Doc 自己是獨立 repo，與三個 code repo 解耦，扮演純控制平面角色。 ...

前言：一個月燒掉 $100 的真實故事 如果你正在考慮升級 Claude Code 的訂閱方案，或者已經升級了卻發現 token 還是不夠用，那你來對地方了。 這不是一篇推銷文，而是一個真實的使用心得。 我從 Pro Plan（$20/月） 開始使用 Claude Code，很快就發現 token 不夠用。心想：「升級到 Max Plan（$100/月）應該就沒問題了吧？」 結果呢？ Max Plan 的 token 也不夠用。 更尷尬的是，我花了大把的 token 去處理一些看似簡單的 bug，像是： 體脂率的小數點精度問題 排便次數顯示 null 和 0 的差異 這些問題聽起來簡單，實際上卻各花了大量 token 去「探索」程式碼。 直到我發現問題的根源不是 token 不夠 (Pro plan是真的不夠！)，而是我沒有找到對的 Skill 來處理這類問題。 問題分析：Token 都燒去哪了？ 讓我用一張圖來說明沒有使用正確 Skill 時的除錯流程： graph TD A[發現 Bug] --> B[讓 AI 搜尋程式碼] B --> C[讀取 file_a.dart] C --> D[沒找到，讀取 file_b.dart] D --> E[還是沒找到，讀取 file_c.dart] E --> F[發現可能相關，展開搜尋] F --> G[讀取更多檔案...] G --> H[終於找到問題] H --> I[提出修復方案] I --> J{修復成功？} J -->|否| B J -->|是| K[完成] style B fill:#ff6b6b,color:#000 style C fill:#ff6b6b,color:#000 style D fill:#ff6b6b,color:#000 style E fill:#ff6b6b,color:#000 style F fill:#ff6b6b,color:#000 style G fill:#ff6b6b,color:#000 style K fill:#51cf66,color:#000 看到問題了嗎？ ...

系列文章第 4 篇（完結篇）：整理所有實用技巧、最佳實踐和疑難排解方法，並提供 30 個立即可用的 Skill 靈感。 前言 歡迎來到「Claude Code Skills 完全指南」系列的最終篇！ 在前三篇文章中，我們從概念到實戰，從基礎到進階，全面探索了 Skills 系統。今天，讓我們將這些知識轉化為實用的指引和建議。 你將獲得： ✅ 完整的最佳實踐清單 ✅ 常見問題與解決方案 ✅ 除錯和優化技巧 ✅ 30 個實用 Skill 靈感 ✅ 可直接使用的完整模板 預計閱讀時間：15 分鐘 讓我們開始吧！ 最佳實踐指南 1. 命名規範 Skill 名稱 ✅ 好的命名： name: pdf-editor name: api-tester name: blog-writer name: code-reviewer ❌ 避免的命名： name: PDF Editor # 不要用空格和大寫 name: apiTester # 不要用駝峰式命名 name: Blog_Writer # 不要用底線 name: skill-1 # 不要用無意義的名稱 規則： ...

系列文章第 3 篇：探索企業級 Skills 的設計模式，深度解析官方範例，學習 Skills 組合使用。 前言 在前兩篇文章中，我們了解了 Skills 的概念並動手建立了第一個 Skill。今天，讓我們更進一步，探索企業級應用和進階技巧。 你將學到： ✅ 企業級 Skills 的設計模式 ✅ 官方 Document Skills 深度解析 ✅ Webapp Testing Skill 的偵查後行動模式 ✅ Skills 組合使用策略 ✅ 在不同平台使用 Skills 預計閱讀時間：12 分鐘 企業級 Skill 範例：API 整合測試器 讓我們看一個更複雜的企業級範例，展示 Skills 在實際業務場景的應用。 使用場景 問題： 團隊有 10 個微服務，每次部署前都要手動測試 API 整合，耗時且容易出錯。 解決方案： 建立一個 API 整合測試 Skill 目錄結構 api-integration-tester/ ├── SKILL.md ├── scripts/ │ ├── run_tests.py # 主要測試執行器 │ ├── generate_report.py # 產生測試報告 │ └── notify_slack.py # Slack 通知 ├── references/ │ ├── api-endpoints.md # API 端點文件 │ ├── test-scenarios.md # 測試情境說明 │ └── auth-guide.md # 認證方式指南 └── assets/ ├── test-data/ # 測試資料 │ ├── valid-requests.json │ └── invalid-requests.json └── report-template.html # 報告模板 SKILL.md 設計重點 --- name: api-integration-tester description: 自動化 API 整合測試工具。此 Skill 用於執行微服務間的整合測試、驗證 API 回應、產生測試報告，並在發現問題時通知團隊。適用於 CI/CD 流程或手動測試需求。 --- # API 整合測試器 ## 快速開始 \`\`\`bash # 執行所有測試 python scripts/run_tests.py --env production # 執行特定服務測試 python scripts/run_tests.py --service user-service --env staging # 產生報告 python scripts/generate_report.py --output ./reports/ \`\`\` ## 測試流程 1. **載入測試情境** - 從 `references/test-scenarios.md` 讀取 2. **準備測試資料** - 使用 `assets/test-data/` 中的資料 3. **執行測試** - 呼叫各 API 端點並驗證回應 4. **產生報告** - 使用 `assets/report-template.html` 5. **通知團隊** - 若有失敗，透過 Slack 通知 ## 重要檔案說明 ### references/api-endpoints.md 包含所有微服務的端點資訊。由於檔案較大，可用 grep 搜尋： \`\`\`bash grep -A 10 "user-service" references/api-endpoints.md \`\`\` ### scripts/run_tests.py 主要測試執行器，支援參數： - `--env`: 環境（development/staging/production） - `--service`: 特定服務名稱 - `--verbose`: 詳細輸出 - `--fail-fast`: 遇到錯誤立即停止 關鍵設計模式 1. 黑盒腳本模式 **Always run scripts with `--help` first** DO NOT read the source until absolutely necessary. 這些腳本很大，會污染上下文視窗。 它們被設計為「黑盒」直接調用，而不是讀取理解。 為什麼這樣設計？ ...

系列文章第 2 篇：從零開始建立一個企業級實用的 Skill，完整的程式碼和詳細步驟教學。 前言 在上一篇文章中，我們了解了 Skills 的核心概念。今天，讓我們捲起袖子，動手打造一個真正實用的企業級 Skill！ 你將學到： ✅ Skills 的完整目錄結構 ✅ 如何規劃和設計企業級 Skill ✅ 撰寫 SKILL.md 的技巧 ✅ 建立 scripts、references 和 assets ✅ 產生視覺化儀表板 ✅ 整合監控和告警系統 專案目標： 建立一個「微服務健康監控儀表板」Skill 這個 Skill 能夠： 🔍 自動檢查所有微服務健康狀態 📊 產生視覺化即時儀表板 📈 追蹤服務回應時間趨勢 ⚠️ 偵測異常並自動告警 📄 產生專業監控報告 🔄 支援定期自動執行 預計閱讀時間：15 分鐘 實作時間：40-50 分鐘 讓我們開始吧！ 為什麼選擇這個範例？ 與 Postman 的本質差異 很多人會問：「這不就是 Postman 嗎？」 完全不同！讓我們看看差異： 比較項目 Postman 我們的監控 Skill 使用場景 開發時測試單一 API 營運時監控所有服務 執行方式 手動點擊測試 自動化定期執行 目標 驗證功能正確性 確保服務健康運作 使用者 開發者個人 整個團隊 + 管理層 視覺化 簡單的回應顯示 完整的儀表板 + 趨勢圖 告警 無 自動 Discord/Email 通知 歷史記錄 無 完整趨勢追蹤 CI/CD 整合 需要 Newman + 複雜設定 一行指令 簡單來說： ...

系列文章第 1 篇：探索 Claude Code Skills 的核心概念，了解它如何改變你與 AI 的協作方式。 前言 想像一下這個場景： 你是一家新創公司的開發者，每次需要寫技術文件時，都要花 30 分鐘向 AI 解釋公司的文件格式、品牌規範、SEO 要求⋯⋯重複這些指令讓人疲憊不堪。 或者，你的團隊有一套複雜的 API 測試流程，每次都要重新告訴 AI 測試步驟、端點位置、驗證規則⋯⋯ 如果有一種方法，能讓 AI 「記住」這些專業知識，就像真正的團隊成員一樣？ 這就是 Claude Code Skills 要解決的問題。 在這個系列文章中，我將帶你深入了解 Skills 系統，從基礎概念到實戰應用。今天的第一篇，讓我們先理解什麼是 Skills，以及為什麼它值得你投資時間學習。 什麼是 Claude Code Skills？ 核心定義 Skills 是一種模組化、自包含的套件，用於擴展 Claude 的能力。 更具體來說，Skills 就像是： 📚 員工手冊 - 告訴 Claude 你的工作流程和規範 🧰 工具箱 - 提供可重複使用的腳本和模板 🎓 專業訓練 - 傳授特定領域的知識和最佳實踐 一個簡單的比喻 想像你在咖啡廳雇用了一位新員工： 沒有 Skills（傳統方式）： 你：請幫我做一杯拿鐵 新員工：好的！怎麼做？ 你：先用這個咖啡豆，磨成這個粗細，萃取 25 秒... （每次都要重複解釋） 隔天... 你：請做一杯拿鐵 新員工：好的！怎麼做？ 你：（又要重複一次）😩 使用 Skills： ...