Claude Code Skill 開發標準與 Plugin Marketplace 完整攻略

八千字的 SKILL.md 灌進 context window，Claude 還沒開始幹活，token 就先燒掉一半。

這就是很多人寫 Skill 踩的第一個坑——把所有東西塞進同一個檔案，以為越詳細越好。結果 Claude 讀完規格就沒剩多少空間做事了。Anthropic 的設計其實有一套漸進式揭露的機制，但不翻文件的話你根本不會知道有這回事。

這篇把 Skill 開發的完整流程拆開來講：從目錄結構、三層載入機制、SKILL.md 撰寫規範，到 Plugin 打包和 Marketplace 發佈。

三層載入：省 token 的關鍵設計

Skill 不是一股腦全丟進去的。它分成三層，按需載入：

層級	內容	載入時機	建議大小
L1 元資料	name + description（YAML frontmatter）	永遠在 context 中	~100 字
L2 SKILL.md	核心流程、快速參考、資源指引	Skill 被觸發時	1,500–2,000 字
L3 Bundled Resources	references/、examples/、scripts/	Claude 判斷需要時	無上限

L1 永遠佔著 context，所以要精簡。L2 是你的主戰場，觸發時才載入。L3 放詳細規範和完整範例，Claude 覺得需要才會去讀。

這套機制的核心原則：SKILL.md 只放指引，細節全部移到 references/ 目錄。

目錄結構

標準的 Skill 長這樣：

skill-name/
├── SKILL.md              # 必要：核心指引（L2）
├── references/           # 選用：詳細文件（L3）
│   ├── patterns.md
│   └── advanced.md
├── examples/             # 選用：可複製的範例
│   └── example.sh
└── scripts/              # 選用：可執行腳本
    └── validate.sh

沒有 references 需求就不用建，空目錄反而造成混亂。

SKILL.md 怎麼寫

Frontmatter 的眉角

---
name: skill-name
description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use".
---

三個規則：

第一，用第三人稱。寫 This skill should be used when...，不是 Use this skill when...。因為讀這段話的是 Claude 本身，它需要知道「什麼時候該觸發我」。

第二，放具體觸發短語。使用者會怎麼說？直接引用那些話。"create a hook" 比 Provides guidance for hooks 精準十倍。

第三，列場景而非功能。Claude 需要判斷的是「使用者現在的意圖」，不是「這個 Skill 能做什麼」。

Body 用祈使句

這點很容易忽略。Body 裡面的指引全部用祈使句：

✅ Parse the frontmatter using sed.
❌ You should parse the frontmatter...

為什麼？因為 SKILL.md 本質上是對 Claude 的指令，不是寫給人看的教學文件。祈使句更直接，Claude 的遵循率也更高。

內容分配

放 SKILL.md 的：

核心概念一句話概覽
必要執行流程（步驟別超過 10 個）
快速參考表
指向 references/ 的指引
最常見的 2-3 個使用場景

移到 references/ 的：

完整格式規範
進階技巧和邊界情況
API 文件
大量範例

開發六步驟

一個 Skill 從無到有的流程：

Step 1 — 理解使用情境。 先不要寫 code。列出所有可能的觸發場景，搞清楚使用者期望什麼輸出。

Step 2 — 規劃可重用資源。 哪些東西會重複出現？重複的程式碼放 scripts/，參考文件放 references/，輸出範本放 assets/。

Step 3 — 建目錄。 一行搞定：

1 2	mkdir -p plugin-name/skills/skill-name/{references,examples,scripts} touch plugin-name/skills/skill-name/SKILL.md

Step 4 — 寫內容。 順序很重要。先寫 references/ 和 scripts/，再寫 SKILL.md。因為 SKILL.md 需要引用那些資源，先寫它你不知道要指向什麼。

Step 5 — 驗證。 跑一次 checklist：

SKILL.md 有 frontmatter？
description 用第三人稱 + 具體短語？
Body 是祈使句？
字數 ≤ 2,000？
所有引用的檔案都存在？

Step 6 — 迭代。 實際用個幾天，看 Claude 的觸發率和執行品質，再回頭調整觸發短語和內容分配。

Plugin：讓 Skill 可以被安裝

單獨的 Skill 只是一堆檔案。要讓別人用，得包成 Plugin：

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Plugin 定義
├── skills/
│   └── my-skill/
│       ├── SKILL.md
│       ├── references/
│       └── scripts/
└── README.md

plugin.json 長這樣：

{
  "name": "git-tools",
  "description": "Git 工作流工具集",
  "version": "1.0.0",
  "author": { "name": "Cheng" },
  "license": "MIT",
  "category": "productivity",
  "skills": ["./skills/diff-summary"],
  "keywords": ["git", "commit-message"]
}

每次改 Skill 都要升版 version。不升版的話，別人跑 plugin update 拉不到新版。踩過這個坑的人應該不少。

Marketplace：讓 Plugin 可以被發現

Marketplace 就是一個 GitHub Repo，裡面裝一到多個 Plugin：

forge/
├── .claude-plugin/
│   └── marketplace.json     # Marketplace 定義（必要）
├── plugins/
│   ├── git-tools/           # Plugin 1
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   └── another-plugin/      # Plugin 2
└── README.md

根目錄一定要有 .claude-plugin/marketplace.json，沒有的話 claude plugin marketplace add 會直接報錯。Plugin 各自保留自己的 plugin.json。

常用指令

操作	指令
加入 Marketplace	`claude plugin marketplace add <owner>/<repo>`
安裝 Plugin	`claude plugin install <plugin-name>`
指定來源安裝	`claude plugin install <plugin>@<marketplace>`
更新	`claude plugin update <plugin>@<marketplace>`
查看已安裝	`claude plugin list`
移除	`claude plugin uninstall <plugin>@<marketplace>`

四個常見錯誤

1. 觸發描述太模糊

Provides guidance for working with hooks. 這種寫法 Claude 很難判斷什麼時候該觸發。改成 This skill should be used when the user asks to "create a hook", "add a PreToolUse hook" 就明確多了。

2. SKILL.md 塞太多

一個 8,000 字的 SKILL.md 直接吃掉 context 預算。拆成 1,800 字的 SKILL.md 加兩個 references 檔案，效果好得多。

3. 用第二人稱寫

You should start by reading the configuration file. 應該改成 Start by reading the configuration file. 祈使句，直接下指令。

4. 忘記引用 references

你辛辛苦苦寫了 references/patterns.md，但 SKILL.md 裡完全沒提到它。Claude 不知道有這個資源，自然不會去讀。在 SKILL.md 末尾列出所有 references 檔案和它們的用途。

實戰：forge/git-tools/diff-summary

我們實際做的第一個 Skill 拆解：

層級	檔案	內容
L1	SKILL.md frontmatter	name + 6 個觸發短語
L2	SKILL.md body	7 步驟執行流程 + 邊界情況表 + 資源指引
L3	references/commit-format.md	Conventional Commits 完整規範
L3	references/announcement-format.md	版本公告 JSON 格式 + 情境範例