從 CLAUDE.md 失控到 15 個 Skill：我的 Claude Code Skills 設計思路

claude-skills-cover

我的 CLAUDE.md 一度長到 800 多行。我自己都懶得捲到底，更何況一個必須把它整份吃進 context 的模型。每次新開對話，token 預算還沒做事就先被自己的「規範」吃掉一半。後來我才意識到——我不是在配置 AI，而是在替它打造一座迷宮。

直到把那 800 行拆成 15 個 skill，一切才恢復清爽。

這篇是我整理過去半年的 Claude Code Skill 設計經驗，混合一些業界正在發生的事。如果你也有 CLAUDE.md 越寫越腫、跟同事分享不掉、自己也記不住到底寫了什麼的困擾，這篇是給你的。

Skills 到底是什麼，以及為什麼它不是「另一個 prompt 檔」

Anthropic 在 2025 年 10 月 16 日正式發布 Agent Skills ，又在 12 月 18 日把它開放成跨平台標準。Microsoft VS Code、GitHub、Cursor、Goose、Amp、OpenCode 全部採用了同一套 SKILL.md 格式。表面上它就是「YAML frontmatter + Markdown 內容 + 一些附屬檔」，看起來樸素到不像什麼革命性東西。

claude-skills-progressive-disclosure

關鍵不在格式，在載入時機。Skills 的設計是 progressive disclosure（漸進式揭露），分三層：

<sub>/.claude/skills/blog-writer/
├── SKILL.md          # Layer 2：只在被觸發時讀進來
├── references/       # Layer 3：SKILL.md 用到才打開
│   ├── seo.md
│   └── style-guide.md
└── scripts/          # Layer 3：需要執行才動
    └── word-counter.py

開新對話時，模型只看到 Layer 1：每個 skill 的 name 跟 description，加起來大概 100 tokens 左右。它根據對話內容判斷哪個 skill 該被啟用，這時才把 Layer 2 的 SKILL.md 整份吃進來。Layer 3 的 reference、script 則是寫進 SKILL.md 的指引「需要進階配色時讀 references/colors.md」，模型才會去讀。

這跟「把 prompt 塞進 CLAUDE.md」最大的差別是：你不再為「以防萬一會用到」而付出 token 成本。沒觸發、就不載入。我把 800 行 CLAUDE.md 拆成 skill 之後，初始 context 從快兩萬 token 降到不到三千。

Skills、Subagents、Slash Commands：三條路長得像，但通往不同地方

新手剛接觸 Claude Code 最容易混淆的就是這三個。三個都能「客製化 Claude 行為」，但設計目的完全不同。

claude-skills-vs-subagents-commands

維度	Skills	Subagents	Slash Commands
觸發方式	自動（Claude 看 description 決定）	Claude 委派或使用者明示	使用者手動輸入 `/xxx`
Context	注入主對話	獨立 context window	注入主對話（prompt 注入）
適合場景	重複性、模式化任務	多步驟工作流、需要隔離	一次性、儀式型動作
跨平台	是（開放標準）	否（Claude Code 限定）	否
可帶 scripts	是	否（透過 tools）	否

jxnl 的 context engineering 文章講得最直白：「Slash commands 就是 prompt injection。你輸入 /run-tests，那串 prompt 直接灌進主對話。Subagents 是『分身』，它們有自己的 context、自己的工具，跑完只把結論回報給你。」

我自己的判斷規則更簡單：

「我每次寫文章都會要求 Claude 走那七個步驟」→ skill
「我每次都要它走 7 個步驟，但其中第 7 步『獨立審查』必須由一個沒被 context 污染的 Claude 來做」→ skill 內部呼叫 subagent
「我偶爾才需要把當前 branch 部署到 staging」→ slash command

這三者也可以組合。我自己的 blog-writer skill 內部，最後一步就是強制呼叫一個獨立 subagent 做審查。原因是同一個 Claude 寫完文章再自己審，會合理化錯誤、看不見幻覺；只有獨立 context 的 subagent 能以「第一次讀者」的視角找問題。這個 editor/checker pattern 在業界已經被廣泛採用。

我的 15 個 Skill：一份個人案例的分類學

claude-skills-personal-library

把我自己的 </sub>/.claude/skills/ 列出來，剛好 15 個，可以拆成五大類：

寫作輸出類（4 個）：blog-writer、hackmd-cheatsheet、hackmd-presentation、obsidian-article。每一個對應到不同的「輸出載體」——部落格 Markdown、HackMD 簡報、Obsidian 內部連結格式。同樣是「寫文章」，產出的格式跟引用慣例完全不同，硬塞進同一個 skill 就會像我之前的 CLAUDE.md。

程式工程類（5 個）：code-review、refactor-suggestions、generate-tests、performance-analysis、system-design。每一個對應一種「審視程式碼的角度」。code-review 看品質與安全、refactor 看結構與可維護性、performance 算複雜度。這幾個常被組合使用——大型重構前我會跑 system-design，重構中跑 refactor，跑完用 code-review 收尾。

AI 創作類（1 個）：generate-image。封裝了我跟好幾個圖片生成模型打交道的經驗（fal-ai/flux/schnell 便宜快、sora_image 高質感、Tongyi Wanxiang 適合動畫）。

產品與研究類（3 個）：product-requirements、ai-pm-lab、deep-research。這幾個是「思考輔助」型 skill。product-requirements 會用品質評分跟我多輪對話收斂出 PRD，deep-research 會強制走 sequential-thinking 多輪搜尋。

領域專用類（2 個）：taiwan-stock-report、codex-help。前者把台股研究的資料源、產業分類、DCF 計算流程封裝起來；後者是給我自己用的 Codex CLI 速查。

Towards Data Science 的一篇實戰文章把 skill、MCP、subagent 用廚房比喻：「MCP 是廚房——刀子、鍋子、食材。Skill 是食譜，告訴你怎麼用這些工具。」我的 15 個 skill 就是 15 份食譜，每一份解決一個重複出現的具體問題。

從失敗中學到的四個設計原則

寫到第七、八個 skill 的時候我才真正抓到節奏。回頭看，最早踩進去的坑跟 description 有關。我有幾個 skill 寫了 處理文件 這種模糊到不行的描述，結果它們從來沒被觸發過。Anthropic 的官方 best practices 反覆強調 description 要同時寫清楚「做什麼」+「何時使用」，例如 生成具體可執行的 git commit 訊息。當使用者請求協助撰寫 commit 或審查 staged 變更時觸發。 這樣才會被正確召喚。description 不是給人看的裝飾，是 skill 的命脈。

接著踩到的是 SKILL.md 的長度。我的 blog-writer 一度膨脹到 700 行，每次觸發都吃掉一大塊 context，主對話的可用空間被壓得很緊。後來把 SEO 細則、HackMD 對照表抽到獨立的 reference 檔，主檔縮回 280 行，觸發後也沒因此遺失資訊——Anthropic 建議的 500 行不是隨便講的，是實測過的上限。

另一個讓我重做整個 skill 的教訓是「想到什麼就寫什麼」。我前幾個 skill 都是邊想邊堆，結果 SKILL.md 結構鬆散、步驟之間缺乏邏輯。後來改成先寫 2-3 個「具體會發生的場景」，再倒推需要哪些步驟。Towards Data Science 那篇實戰文的作者也說「直接寫 SKILL.md 第一次就會失敗，要先設計再寫」。

最近一次的覺醒是「skill 寫完別自己驗收」。我把 blog-writer 的 Step 7 改成「強制呼叫獨立 subagent 做終審」，理由很實在：同一個 Claude 寫完文章後對內容有偏見，會合理化自己的選擇，看不出幻覺、看不出虛構連結。subagent 用獨立 context 重讀，等於請一個沒參與的編輯來把關。實測下來，每次都能揪到主對話自己完全沒注意的問題。

業界正在發生：從特化 agent 轉向通用 agent + 特化 skill 庫

claude-skills-ecosystem

VentureBeat 報導引述 Anthropic 研究員 Barry Zhang 的觀察：他們本來以為不同領域的 agent 會長得很不同，後來發現底層 agent 其實是通用的。這句話某種程度上解釋了為什麼 Skills 會被推出、又為什麼會這麼快變成跨平台標準。

過去兩年，主流做法是「為每個用途打造一個特化 agent」——客服 agent、coding agent、研究 agent。Skills 的設計反過來：一個通用 agent + 一個會根據任務動態載入的 skill 庫。根據 The Verge 報導，10 月 16 日 Skills 發布當天，Box、Rakuten、Canva 就已經是首批使用者；兩個月後 Anthropic 把 Skills 開放成標準時，VentureBeat 報導揭露的合作夥伴目錄擴大到 10 家，包括 Atlassian、Figma、Stripe、Zapier 等。這些公司都是把自家的領域知識封裝成 skill，而不是各自做 agent。

社群這邊也跟得很快。我隨便逛幾個 marketplace（以下數字截至 2026 年 4 月）：

claudeskills.info 累積了官方加社群的數百個免費 skill
skillsmp.com 跨 Claude / Codex / ChatGPT
GitHub: travisvn/awesome-claude-skills 是 awesome 系列的 curated 清單
skills.pawgrammer.com 已經累積超過 280 個社群 skill

而且這些 skill 在不同 IDE 之間是互通的。你寫一個 SKILL.md，Cursor 認、Codex CLI 認、Gemini CLI 認，連 Microsoft 的 VS Code 都認。這個跨平台層級的標準化，在前一代 prompt 配置工具（CLAUDE.md、.cursorrules、AGENTS.md）時代是不存在的。

反模式：你不該這樣寫 Skill

claude-skills-antipatterns

寫了 15 個之後，我也看了不少別人的 skill。最常見的反模式整理如下：

SKILL.md 寫成小說。動輒 1500 行、把所有可能用到的細節都塞進主檔。這違反 progressive disclosure 的精神。Towards AI 那篇 progressive disclosure 設計文寫得很狠：「你不是在優化，你只是把問題從一個地方搬到另一個地方。」

description 籠統到沒人召喚得到。寫 處理資料 跟 Helps with documents 的 skill，最後都成了 skill 庫裡永遠不會被觸發的死檔。

過度條列、缺乏敘事。整個 SKILL.md 都是 bullet list，沒有 workflow、沒有判斷邏輯、沒有「在這個情況下要 X、那個情況下要 Y」。Claude 讀完不知道該怎麼動作。

從 CLAUDE.md 直接搬移過來不重構。這正是我一開始犯的錯。把 800 行的全域規範切成 5 個 skill，但每個還是 160 行的「子 CLAUDE.md」，根本沒享受到漸進揭露的好處。重構的關鍵是：每個 skill 應該是「為某個具體任務設計的食譜」，而不是「某個分類的規範總集」。

深度巢狀引用。Anthropic 官方明確建議「file references are one level deep」。SKILL.md 引用 references/style.md 是 OK 的，但 style.md 又引用 references/sub/detail.md 就太深了，模型不會跟到底。

結語：找一個重複五次的指引，把它變成第一個 skill

寫 skill 半年下來，我的 CLAUDE.md 從 800 行壓回 8 行，剩下的 792 行散佈在 15 個 skill 裡，按需載入。每寫一個 skill，等於把一段我重複講過的指引外掛到 Claude 上，下次它自己會觸發。

而且因為 Agent Skills 已經是開放標準，這套整理是可以跟著我跨工具的——Cursor、Codex、Gemini、VS Code 都吃同一份 SKILL.md。不像過去寫死在某家工具裡的 prompt 配置，換工具就要重寫。

如果你還沒寫過自己的 skill，最務實的起步方式是：翻一下過去三個月，找一個你「至少跟 Claude 講過五次同樣的指引」的場景，把它寫成第一個 skill。從一個小、好驗證的 use case 開始，比一次規劃 20 個 skill 卻沒一個跑得起來實在得多。

參考資料

延伸閱讀

本文最初發布於 HackMD @BASHCAT。

搜尋此網誌

BASHCAT