2026 年的 Claude Code Skills：如何為自己建立 Skills 程式庫

Ailoot 文件：API、金鑰與設定。

Claude Code 中的 Skill 是什麼？為什麼它不只是「更大的提示詞」？#

Claude Code Skills 是 Claude Code 的原生功能，Anthropic 於 2025 年 10 月為 Pro/Max/Team/Enterprise 推出。之後，他們將 Agent Skills 規格開放為標準，讓其他 Claude 以外的環境也能使用。程式碼中，它只是一個資料夾：

.claude/skills/
├── deploy-to-prod/
│   ├── SKILL.md
│   └── scripts/
│       └── check-migrations.sh
├── weekly-content-plan/
│   └── SKILL.md
└── triage-support-tickets/
    └── SKILL.md

每個資料夾就是一個 skill。SKILL.md 是 Markdown 檔案，頂端有 YAML frontmatter，下方則是一般指示。當使用者說「我們來部署到正式環境」，Claude 會看到 deploy-to-prod skill 的 description，辨識出「部署到正式環境」這個觸發條件，將 SKILL.md 內文載入上下文，並依照步驟執行。

漸進式載入的三個層級

Anthropic 以漸進式載入設計 skills：資料會依需求分層載入。在 Anthropic Engineering 部落格中，團隊將此稱為「讓 Agent Skills 具有彈性且可擴展的核心設計原則」（Anthropic Engineering）。

三個載入層級如下：

1. 中繼資料（永遠載入） - 工作階段開始時，Claude 只會看到各 skill 的 name 和 description。預算：約每個 skill 100 個 token。
2. 指示（觸發時載入） - 使用者提出相關需求時，Claude 會載入 SKILL.md 內文。預算：少於 5000 個 token。
3. 資源（要求時載入） - 隨附檔案（範例、範本、資料集）只有在模型自行查找時才會擷取。預算：不限。

以前，CLAUDE.md 必須容納 AI 應該「記住」的所有內容，而有 50 條規則的專案很快就會碰到上下文上限。使用 skills 後，同一個專案能輕鬆容納數十個 skill，因為初始上下文只會加入它們的 description。

Skills 的四種存放層級

優先順序：enterprise 覆蓋 personal，personal 覆蓋 project。Plugins 使用 plugin-name:skill-name 命名空間，不會互相衝突。這很方便：通用專業 skills 放在 ~/.claude/skills/，專案專用的則放在儲存庫的 .claude/skills/。

SKILL.md 裡面有什麼？#

以下是最精簡的範例——20 行就能備妥一個 skill：

---
name: weekly-content-plan
description: Prepares a weekly post plan for a Telegram channel and short-form video posts. Triggers - "make a post plan", "what should I post this week", "a 7-day channel plan". Do not activate if the request is about a website or email newsletter.
---

# Weekly Content Plan

## Steps

1. Read `knowledge/audience.md` - who we're writing for
2. Read `knowledge/tone-of-voice.md` - how we write
3. Read the last 10 posts in the channel - what has already been covered
4. Come up with 7 topics for the week: 3 sales-focused, 2 expert, 2 personal
5. For each, provide one hook line and three bullets about the post
6. Output as a table: day of the week | type | hook | plan

這樣就夠了。使用者若輸入「我們來規劃這週的貼文」，Claude 會看到 description 中的觸發條件，載入 SKILL.md、讀取指定檔案，再輸出表格。

請留意這些限制

Claude 官方 API 文件訂有嚴格限制：

• name：最多 64 個字元，只能使用小寫字母、數字和連字號，不得包含 XML 標籤。anthropic 和 claude 是保留字。
• description：API 中最多 1024 個字元；必填，不得包含 XML 標籤。
• 清單預算：在 Claude Code 中，所有 skills 的 description 合計約占上下文視窗的 1%。如果 skills 很多，description 會被截斷，Claude 用來配對的關鍵字可能因此消失。
• SKILL.md 內文：Anthropic 建議內文控制在 500 行以內。較長的內容應移到 references/、scripts/ 和 examples/ 檔案，再透過指示載入。

上下文壓縮（/compact）後，Claude 會保留先前呼叫的每個 skill 前 5000 個 token。所有重新附加 skills 的總預算為 25 000 個 token。若 skill 放不進去，它的行為就會被「遺忘」。

完整的 Frontmatter Schema

至少使用 name 和 description。正式使用的 skills 也會用到其他欄位：

對於不應自動執行的內容，disable-model-invocation: true 是必要欄位。例如，設定此旗標的 deploy-to-prod skill 只有在使用者明確輸入 /deploy-to-prod 時才能呼叫。若沒有此旗標，Claude 可能會因為「程式碼看起來準備好了」就進行部署。

為什麼 Description 占了 90% 的工作？該怎麼寫？#

vibe-coder 最常犯的錯誤，是把 description 寫成「X 助手」。skill 明明就在資料夾裡，Claude 卻不會呼叫它。

不好的 Description

description: Build dashboards.

Claude 無從判斷：使用者說「給我看本週的銷售額」時，這是在問儀表板嗎？使用者說「營收圖表」時，這是在問儀表板，還是只想要一般圖表？使用者說「月報」時，這肯定不是在問儀表板嗎？

Anthropic 的自家 skill-creator直接說明了這項建議：

好的 Description 公式

分成三個部分：

1. 它會做什麼 - 用一句話說明結果，而非流程。不要寫「產生 SQL」，而要寫「將銷售資料匯出成 Telegram 頻道用的表格」。
2. 何時觸發 - 列出 3-5 個使用者實際會說的語句，並加上引號。不要猜，查看你的聊天和支援紀錄。
3. 何時不要觸發 - 列出 1-2 個相似工作，說明 skill 不應該回應哪些情況。沒有這一段，兩個相似的 skills 就會一直互相衝突。

以下是我專案中的一個強力 description 範例（已簡化並匿名化）：

description: |
  Writes and publishes an SEO guide to the blog, following the editorial policy.
  Triggers: "write a guide about X", "let's make a new pillar",
  "a blog article about Y", "build a blog guide about Z".
  Do not activate if the request is about an email newsletter,
  a Telegram post, or an internal team instruction—
  those are other skills.

這個範例的有效之處：

• 用「撰寫並發布」取代「協助」，具體說明可產生的結果。
• 四個加上引號的觸發語句涵蓋不同說法。
• 也加入英文觸發語句——若使用者改用團隊的語言，skill 一樣能運作。
• 獨立的「不要在以下情況啟用」段落可避免與電子郵件和貼文 skills 衝突。

如何測試 Description

Anthropic 在 skill-creator 中內建了 trigger-evals 方法：用 20 個提示詞檢查 skill 是否會啟用。10 個應該觸發，另外 10 個不應觸發（包括措辭相近但工作不同的近似案例）。

換成 vibe-coder 的說法：description 寫好後，開一個空白聊天，試試你常用的 5 個說法，再加上 3 個聽起來相似、但意思不同的說法。如果該啟用時沒有啟用，或不該啟用時卻啟用了，就修改 description。接著才撰寫指示內文。

我會先安裝哪 5 個 Skills？#

一開始就花兩週撰寫自己的 skills，是個會吃虧的策略。先安裝現成的 skills，看看它們如何建構，再用相同的方法加入自己的 skills。採用別人驗證過的集合並依需求調整，比從頭開始建立所有內容更省力。以下是我會先試用的五個集合：

1. anthropics/skills - 含有 skill-creator 的官方集合

儲存庫：github.com/anthropics/skills。GitHub 上有 138,000 顆星。內含 Anthropic 團隊的官方 skills：skill-creator（用來撰寫其他 skills 的 meta-skill）、claude-api（協助建立 API 整合），以及 PowerPoint、Excel、Word 和 PDF 的現成文件 skills。

使用 Claude Code 安裝：

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

最有價值的是 skill-creator。它會根據你的描述撰寫 SKILL.md，接著執行 20 個 trigger-evals，並持續修改 description，直到 skill 能在適當情況下啟用。簡單來說，它是「用來建立 skills 的 skill」。

2. mattpocock/skills - TypeScript 專家的熱門集合

當中有 12 個實用 skills，包括：

安裝：

npx skills@latest add mattpocock/skills
/setup-matt-pocock-skills

3. coreyhaines31/marketingskills - 行銷人員的集合

如果你經營線上課程、擔任自由行銷人員或經營代理商，就不必花半年撰寫自己的 skills。已經有一半的工作被包裝成現成工具了。

4. vercel-labs/agent-skills - 不帶 AI 感的設計

儲存庫：github.com/vercel-labs/agent-skills。其中最受歡迎的 skill 是 web-design-guidelines，每週安裝次數約 133,000 次。它會依照 100 多項無障礙、效能和易用性規則稽核 UI 程式碼。

另外還有 Anthropic frontend-design，每週安裝次數超過 110,000 次。它會先讓 AI 選擇風格，再開始寫程式碼。沒有它的話，Claude 產生的每個頁面都會使用 Inter 字型、紫色漸層和網格卡片。每個人得到的結果都一樣。

5. obra/superpowers - 多代理工作流程

總而言之，如果你安裝清單中的前三個——anthropics/skills、mattpocock/skills 和 coreyhaines31/marketingskills——Claude Code 就會有數十個現成 skills，足以涵蓋創業者第一個月大部分的工作。

哪些重複性工作應該整理成 Skill？#

在客戶工作和其他人的專案中，我看過這種情況數十次。有人每次都「從頭做那件事」。每週一都要寫同類型的報告。每次有新客戶加入，都要走相同流程。每篇內容都依照相同範本製作。每次卻要花 30-90 分鐘，因為他們必須重新回想步驟、開啟正確檔案，並重新撰寫給 Claude 的提示詞。

解決方法是一次把流程整理成 skill。之後你只要說一句話，Claude 就會載入方法、讀取必要資料，並產出結果。以下是不同領域的三個範例：

範例 1. 自由行銷人員 - weekly-content-plan Skill

手動處理方式：每週一，為三位客戶準備一週份的 Telegram 貼文。他們會開啟客戶的品牌語氣指南、檢視近期貼文、依照產品行事曆構思主題，再整理成含有 hook 和重點項目的表格。

將其整理成 skill 後，就會成為五步驟指示：讀取客戶的 tone-of-voice 檔案、讀取產品行事曆、檢查最近 10 篇貼文以避免重複、按類型（銷售導向、專業知識、個人內容）構思七個主題，最後輸出成表格。

只要輸入「我們來規劃客戶 X 本週的貼文」，原本一小時的準備工作就變成等待三分鐘。行銷人員檢查結果、針對特定項目修改，再傳給客戶。

範例 2. 外包會計師 - monthly-receipts-close Skill（作者範例）

手動處理方式：每個月為客戶名單中的每位客戶匯出銀行對帳單、與會計系統中的付款資料核對、標記尚未分類的款項、準備初步收入報告，並將收入結構與上個月比較。

這個 skill 包含六步驟指示，以及放在 scripts/ 資料夾中用來解析銀行對帳單的幾個 shell scripts。只要輸入「幫客戶 X 結算五月」，Claude 就會在 4-5 分鐘內產出一份標記異常項目的報告。

範例 3. 線上課程經營者 - welcome-letter-new-participant Skill

手動處理方式：新學員已付款，需要撰寫歡迎信。好的歡迎信必須個人化：考量學員來自哪個管道、購買哪個產品、加入哪一期課程，以及應附上哪些教材。「嗨，歡迎加入」的範本做不到這些。

這個 skill 會指示 Claude 讀取 knowledge/audience.md（這些人是誰）、knowledge/products/<product>.md（他們會得到什麼），以及最近三封歡迎信（避免重複），再依照以下結構撰寫郵件：hook - 產品細節 - 前三個步驟 - 結尾。

速度比手動操作快很多。品質也更一致，因為 Claude 會記得檢查三個來源，而忙碌的人常常會漏掉其中一個。

哪些事情不該整理成 Skill

• 一次性的工作。如果你一年只在報稅時做一次，直接在聊天中向 Claude 說明即可。重複 3+ 次後，skill 才能發揮效益。
• 範圍太廣的工作。「幫我做行銷」不是 skill，而是整個行銷領域。skill 應該是「每週內容計畫」——具體的行動和具體的結果。
• 沒有固定重複步驟的工作。每次流程都不同，就不適合做成 skill；那是一次性的工作。

Skill Creator 如何替你撰寫 Skills？#

難處在於，一開始就寫出好的 skill 並不容易。description 常常太狹窄或太廣泛，漏掉使用者實際會用的語句，或是和相鄰的 skill 衝突。Anthropic 為此發布了 skill-creator，這是一種能建立其他 skills 的 meta-skill。

安裝 anthropics/skills 後，告訴 Claude /skill-creator（或直接說「我們來為每週報告建立一個 skill」），接著依照六階段流程進行：

1. 起草 - skill-creator 會詢問 skill 應該做什麼、使用哪些觸發語句、讀取哪些資料，以及遵循哪些步驟。結果是第一版 SKILL.md。
2. 測試 - skill-creator 產生 20 個測試提示詞：10 個應觸發 skill，另外 10 個聽起來像觸發條件、但實際上不應觸發（近似案例）。
3. 評估 - 它會在全新的聊天中逐一執行提示詞，檢查 skill 是否啟用。如果不該啟用時啟用了，或該啟用時沒有啟用，就會標示結果。
4. 反覆修改 - 根據失敗案例改寫 description，再次執行測試。
5. 最佳化 - 最後潤飾：檢查是否超過 1024 個字元的限制，以及是否與現有專案 skills 衝突。
6. 封裝 - 依照正確結構打包最終版 SKILL.md 和參考檔案。

實際上，你會和 Claude 討論 15-20 分鐘、回答 7-8 個釐清問題，最後得到一個可直接使用、經過測試並能在適當觸發條件下啟用的 skill。

另一個好處是，skill-creator 本身就是 SKILL.md 寫作風格的優秀範例。你可以打開它自己的檔案，看看步驟的格式、語氣和結構。這是工具示範自身的案例——讀一讀就能學會如何寫自己的 skill。

Skills、CLAUDE.md、Subagents、MCP、Hooks：該用哪一種？#

我審閱過的專案中，最常見的問題是把專案規則、逐步發布指示、commit 範本和資料庫說明全部放進 CLAUDE.md。這會讓上下文過度負載，而且實際上也行不通：Claude 不會在「使用者要求發布」時執行這些指示，因為模型會把 CLAUDE.md 的所有內容視為沒有明確觸發條件的一般上下文。

解決方法是為每項內容選擇合適的機制：

簡言之，整體邏輯如下：Skills 和 MCP 涵蓋大多數工作流程；Hooks 自動執行例行工作，例如程式碼檢查、測試和防護措施；上下文變得沉重時才需要 Subagents。最常見的錯誤，是該用 skill 時卻建立 subagent。

決策樹

當你想著「我需要 Claude 做 X」時：

1. 這項知識是否一直都需要？ 例如「專案有指定語言」或「我們不用 em-dashes」。→ 放進 CLAUDE.md。
2. 這是目前由你手動執行、需要觸發條件的流程嗎？ 例如「我每週一寫報告」。→ 建立 skill。
3. 你需要存取外部系統嗎？ 例如 Stripe API 或 CRM。→ 連接 MCP server。
4. Claude Code 是否應該自動回應事件？ 例如每次 Edit 後執行 linter。→ 撰寫 hook。
5. 任務是否很繁重、會耗盡上下文，而且你需要同時處理其他事情？ → 在 subagent 中執行。

創業者和 vibe-coder 的工作有 90% 屬於第 1-3 類。Hooks 和 subagents 是進階工具，適用於你不再「一次只做一件事」之後。

Slash Commands 和 Skills 是同一回事

Claude Code 有一項重要改變：舊的 slash-command 系統（.claude/commands/）和 skills 實際上已經合併。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都會建立 /deploy 命令。若名稱相同，skill 會優先。因此，如果你還在使用舊的 slash-command 格式，請改用 skills；語法更清楚，功能也更多。

讓 Skill 無法運作的 7 個錯誤#

1. Description 沒有觸發語句：Skill 不會啟用

症狀：你寫了 skill、檢查了結構，所有內容都有效，但 Claude 不會在使用者提出需求時呼叫它。原因幾乎都一樣：description 寫成「內容撰寫助手」之類的描述。Claude 不知道要回應哪些語句。修正方法：在 description 中直接加入 3-5 個使用者實際會說的語句，並加上引號。

2. SKILL.md 超過 500 行：注意力開始分散

Anthropic 明確建議將檔案內文控制在 500 行以內。如果指示有 2,000 行，Claude 就會失去焦點，只部分遵循步驟，並搞混順序。修正方法：將較大的章節移到附近的檔案，例如 examples/、references/、scripts/，再從 SKILL.md 引用它們。

3. 不要用一個「所有內容都包辦」的 Skill，改做三個小型 Skills

一種看似方便的設定，是用一個大型 content skill 包含 Telegram 貼文、登陸頁和電子郵件。這樣行不通。skill 會在錯誤的需求下啟用、混淆不同方法，產出折衷的結果。修正方法：一個 skill 對應一種可重複執行的動作。如果你確實有三種「內容」工作流程，就建立三個 skills：telegram-post、landing-section、email-broadcast。

4. Skill 沒有「何時不要使用」段落：會發生衝突

症狀：專案中有兩個相似的 skills，而 Claude 呼叫了錯的那個。例如，一個 skill 專門處理電子報，另一個專門處理課程參與者的歡迎信。若沒有明確寫上「若需求與一般郵寄清單有關，請勿啟用」，歡迎信 skill 就會在提到「電子郵件」時一律觸發。修正方法：在 description 中明列不適用的情況。

5. 專案中有 50 個 Skills：Descriptions 會被截斷

摘自 Claude Code 文件：

如果你從市集下載了 50 個 skills 集合，其中一些 descriptions 就會被截斷。你原本仰賴的關鍵字可能因此消失。修正方法：在作用中的專案中保留最實用的 10-15 個 skills。其餘放在所有可搜尋 skills 目錄外的未啟用封存，例如自有資料中的 skill-archive/，需要時才裝到專案或個人範圍。~/.claude/skills/ 是跨專案可見的已安裝個人庫，移到這裡不會停止搜尋。

6. 來自未驗證來源的 Skills：安全風險

Anthropic 在官方文件中提出警告：

隨意找到的 GitHub repo 可能藏有會在你第一次呼叫時洩漏 API 金鑰的 skill。修正方法：安裝前先開啟 SKILL.md，親自閱讀。重要專案不要執行來路不明作者的 skills。

7. 沒有知識資料夾的 Skill 會產出「普通的 ChatGPT」內容

最隱晦、也最常見的反模式。skill 提供的是方法，但沒有上下文，方法本身就沒有意義。如果你寫了一個「撰寫歡迎信」skill，專案卻沒有說明受眾的檔案，也沒有品牌語氣檔案，Claude 寫出的就會是普通的 ChatGPT 郵件，和其他人產生的內容沒有差別。

只有先依照關於 CLAUDE.md 的指南所述原則，建立好專案的 Second Brain，skill 才能發揮最佳效果。先建立知識結構，再建立依賴它的 skills。順序反過來，就只會得到制式、普通品質的內容，而不是符合你風格的個人化成果。

如何在 30 分鐘內建立第一個 Skill#

以下是我在自己的專案中建立第一批 skills 時使用的具體計畫：

步驟 1. 選擇一項重複工作

打開過去一個月的行事曆。找出至少做過 4-5 次、每次需花 30-60 分鐘的工作。不要選「行銷」這種大範圍事項，而要選具體的工作：「星期一的銷售報告」、「新客戶 onboarding」或「更新促銷價格表」。

描述越精確，skill 就越簡單，觸發條件也越明確。

步驟 2. 手動寫下流程

在另一個檔案中，或在與 Claude 的聊天中（不是 skill，而是草稿），寫下你會採取的步驟：

1. Open the client database
2. Filter by status "awaiting welcome email"
3. Check which channel the client came from
4. Get the email template for that channel from the "templates" folder
5. Fill in the name, product, and start date
6. Send

這還不是 skill，只是筆記。但沒有這些筆記，撰寫 SKILL.md 一開始就會讓你不知所措。

步驟 3. 建立資料夾結構

mkdir -p .claude/skills/welcome-email-new-client
touch .claude/skills/welcome-email-new-client/SKILL.md

如果想在所有專案中使用 skill，就把它放進 ~/.claude/skills/。

步驟 4. 使用範本撰寫 SKILL.md

基本架構：

---
name: welcome-email-new-client
description: |
  Prepares a welcome email for a new client using the template for their acquisition channel.
  Triggers: "write a welcome email for new client X",
  "onboard new participant Y", "welcome email for client from channel Z".
  Do not activate if the request is about a general mailing list
  or an email campaign—those are other skills.
---

# Welcome Email for a New Client

## Steps

1. Read `knowledge/audience/segments.md` - what client segments we have
2. Read `knowledge/templates/welcome/` - templates by channel
3. Identify the client's channel from the request context
4. Insert the client's name, product name, and start date
5. Check the length—it should be no more than 800 characters
6. Output the final email text in a copy-ready format

## Important

- Do not use “dear friend” or “hello”—use natural speech
- One paragraph, one idea
- End with one call to action, not two

步驟 5. 用 5-8 個提示詞測試

在此專案中開啟 Claude Code 的空白聊天。試試你實際會用的 5 種說法，再試 3 種相似、但不應啟用 skill 的說法：

應觸發：

• “Write a welcome email for new client Ivanov”
• “Onboard a new participant who bought program X”
• “Welcome email for a client from Instagram”

不應觸發：

• “Send a promotion email to the whole list”
• “Email campaign for the New Year holidays”
• “Write a follow-up to a client who hasn't paid”

逐一檢查 skill 是否啟用。如果它在不該啟用的情況下啟用了，就縮小 description 的範圍。如果它在應該啟用時沒有啟用，就擴大觸發語句的範圍。

步驟 6. 反覆修改 Description

每次測試失敗後，只修改 description，不要碰指示內文。反覆修改 2-3 次後，skill 就會穩定啟用。儲存、commit，然後每天使用它。

最後的建議：不要追求第一個 skill 十全十美。先讓它能運作。等到第五或第十個 skill 再來潤飾，那時你會開始看出自己措辭和 Claude 回覆中的模式。

從這週的行事曆中挑一項反覆進行的工作，空出 30 分鐘，照著上面的六個步驟做。Claude 就會依照你的方法工作，而不是靠猜測。

如果你需要透過 Ailoot 使用 AI 模型，請參閱 Ailoot。