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


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

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

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

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

Anthropic 在 [2025 年 10 月 16 日正式發布 Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) ，又在 [12 月 18 日把它開放成跨平台標準](https://venturebeat.com/technology/anthropic-launches-enterprise-agent-skills-and-opens-the-standard) 。Microsoft VS Code、GitHub、Cursor、Goose、Amp、OpenCode 全部採用了同一套 SKILL.md 格式。表面上它就是「YAML frontmatter + Markdown 內容 + 一些附屬檔」，看起來樸素到不像什麼革命性東西。


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

~/.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 左右](https://bdtechtalks.substack.com/p/what-to-know-about-claude-skills) 。它根據對話內容判斷哪個 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 行為」，但設計目的完全不同。


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

[jxnl 的 context engineering 文章](https://jxnl.co/writing/2025/08/29/context-engineering-slash-commands-subagents/) 講得最直白：「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](https://pub.towardsai.net/from-claude-code-skills-to-adversarial-subagent-orchestrators-to-the-claude-agent-sdk-three-e1dedfd067b1) 在業界已經被廣泛採用。

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


把我自己的 `~/.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 的一篇實戰文章](https://towardsdatascience.com/how-to-build-a-production-ready-claude-code-skill/) 把 skill、MCP、subagent 用廚房比喻：「MCP 是廚房——刀子、鍋子、食材。Skill 是食譜，告訴你怎麼用這些工具。」我的 15 個 skill 就是 15 份食譜，每一份解決一個重複出現的具體問題。

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

寫到第七、八個 skill 的時候我才真正抓到節奏。回頭看，最早踩進去的坑跟 description 有關。我有幾個 skill 寫了 `處理文件` 這種模糊到不行的描述，結果它們從來沒被觸發過。Anthropic 的 [官方 best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/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 [那篇實戰文](https://towardsdatascience.com/how-to-build-a-production-ready-claude-code-skill/) 的作者也說「直接寫 SKILL.md 第一次就會失敗，要先設計再寫」。

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

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


[VentureBeat 報導](https://venturebeat.com/technology/anthropic-launches-enterprise-agent-skills-and-opens-the-standard) 引述 Anthropic 研究員 Barry Zhang 的觀察：他們本來以為不同領域的 agent 會長得很不同，後來發現底層 agent 其實是通用的。這句話某種程度上解釋了為什麼 Skills 會被推出、又為什麼會這麼快變成跨平台標準。

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

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

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

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

## 反模式：你不該這樣寫 Skill


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

**SKILL.md 寫成小說**。動輒 1500 行、把所有可能用到的細節都塞進主檔。這違反 progressive disclosure 的精神。Towards AI 那篇 [progressive disclosure 設計文](https://pub.towardsai.net/progressive-disclosure-in-ai-agent-skill-design-b49309b4bc07) 寫得很狠：「你不是在優化，你只是把問題從一個地方搬到另一個地方。」

**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 已經是開放標準](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) ，這套整理是可以跟著我跨工具的——Cursor、Codex、Gemini、VS Code 都吃同一份 SKILL.md。不像過去寫死在某家工具裡的 prompt 配置，換工具就要重寫。

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

## 參考資料

- [Equipping agents for the real world with Agent Skills - Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Skill authoring best practices - Claude API Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [Anthropic launches enterprise 'Agent Skills' and opens the standard - VentureBeat](https://venturebeat.com/technology/anthropic-launches-enterprise-agent-skills-and-opens-the-standard)
- [How to Build a Production-Ready Claude Code Skill - Towards Data Science](https://towardsdatascience.com/how-to-build-a-production-ready-claude-code-skill/)
- [Progressive Disclosure in AI Agent Skill Design - Towards AI](https://pub.towardsai.net/progressive-disclosure-in-ai-agent-skill-design-b49309b4bc07)
- [Skills vs Subagent: What's the difference? - eesel AI](https://www.eesel.ai/blog/skills-vs-subagent)
- [Slash Commands vs Subagents - jxnl.co](https://jxnl.co/writing/2025/08/29/context-engineering-slash-commands-subagents/)
- [Best Practices for Creating Agent Skills - GitHub: mgechev/skills-best-practices](https://github.com/mgechev/skills-best-practices)
- [What to know about Claude Skills - TechTalks](https://bdtechtalks.substack.com/p/what-to-know-about-claude-skills)
- [Agent Skills: How is it different from command and other tools? - Kau.sh](https://kau.sh/blog/claude-skills/)

## 延伸閱讀

- [awesome-claude-skills - GitHub](https://github.com/travisvn/awesome-claude-skills)
- [claudeskills.info - 官方 + 社群 skill 目錄](https://claudeskills.info/skills/)
- [Anthropic turns to 'skills' to make Claude more useful at work - The Verge](https://www.theverge.com/ai-artificial-intelligence/800868/anthropic-claude-skills-ai-agents)