自己寫一個 skill：從 SKILL.md 到進階組織術

上一篇搞懂了 skill 的原理，這篇直接動手。我們來寫一個「PR 描述」skill，教 Claude 每次都用同一個格式幫你寫 pull request 說明。寫 skill 本身大概十分鐘，但之後每一次相關任務都省下重講的時間，這筆帳很划算。

後半段是進階內容：怎麼寫出觸發得準的 description、怎麼用 allowed-tools 上安全鎖、名稱撞名時誰贏，以及大型 skill 的組織術 progressive disclosure。

動手：十分鐘寫出第一個 skill

我們做一個個人 skill，讓它跨所有專案可用。第一步，在家目錄的 skills 資料夾裡建一個目錄，目錄名稱要跟 skill 名稱一致：

mkdir -p ~/.claude/skills/pr-description

第二步，在裡面建立 SKILL.md。整份檔案就兩段：frontmatter 與指示內文：

---
name: pr-description
description: Writes pull request descriptions. Use when
  creating a PR, writing a PR, or when the user asks to
  summarize changes for a pull request.
---

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed.

## Changes
- Bullet points of specific changes made
- Group related changes together

第三步，測試。Claude Code 在啟動時載入 skill，所以先重啟，確認清單裡看得到它，然後在有修改的分支上說「幫我的修改寫一份 PR 描述」。它會標示正在使用這個 skill、查你的 diff、照你的模板產出，而且每次格式都一樣。

之後要更新就改 SKILL.md，要移除就刪掉資料夾，改完都要重啟。「每次格式都一樣」正是 skill 的價值所在：你把一次性的口頭交代，升級成了可以重複執行的標準流程。

把 description 寫到觸發得準

skill 不觸發，九成是 description 的問題。一份好的 description 要回答兩個問題：這個 skill 做什麼？Claude 什麼時候該用它？光寫「幫忙處理文件」太模糊，連人都不知道該做什麼，Claude 也一樣。實用的做法是把你實際會說的話寫進去：如果你會說「幫我看看這段為什麼慢」，就把這類語句放進 description，用你自己的措辭當觸發詞，命中率自然高。

拿一個效能分析 skill 當例子：使用者可能說「幫我 profile 這段」「為什麼這麼慢」「讓它跑快一點」，三句話用詞完全不同，但意圖相同。測試的方法就是把這些變化句逐一講一遍，哪一句沒觸發，就把那句的關鍵字補進 description。description 不是寫給搜尋引擎的，是寫給未來的你自己的嘴巴的。

進階欄位：allowed-tools 與 model

frontmatter 必填的只有 name（小寫字母、數字、連字號，上限 64 字元）與 description（上限 1024 字元），另外有兩個選填欄位很實用：

---
name: codebase-onboarding
description: Helps new developers understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

• allowed-tools：skill 啟用期間 Claude 只能用列出的工具。像上面這個新人導覽 skill 只給讀取與搜尋，保證不會改到任何檔案，適合唯讀或安全敏感的流程；不填就不限制。
• model：指定這個 skill 用哪個模型執行，讓輕量任務跑快的模型、複雜任務跑強的模型。

撞名了誰贏：優先權階層

如果你 clone 的 repo 帶了一個跟你個人 skill 同名的 skill，誰說了算？順序固定：Enterprise、Personal、Project、Plugins，由高到低。企業管理設定最優先，讓組織能強制推行標準；再來是你的個人目錄、專案目錄，外掛最低。被蓋掉的解法通常很簡單：把你的 skill 改個更具體的名字，例如把 review 改成 frontend-review。

skill 也不是只能自用。放進 repo 的 .claude/skills 就會隨版本控制全隊共享；不綁特定專案的通用 skill，可以打包成 plugin 發佈到 marketplace 讓更多人安裝；企業則能透過管理設定全組織部署，強制推行合規與安全標準。你的 skill 寫得好，受益的可以不只你一個人。

大型 skill 的組織術：progressive disclosure

skill 跟你的對話共用 context window，把兩千行內容全塞進一份 SKILL.md，既佔空間又難維護。progressive disclosure（漸進揭露）的解法很簡單：SKILL.md 只放核心指示，細節拆到附屬檔案，並在 SKILL.md 裡寫清楚「什麼情況去讀哪個檔」。有人問系統架構，Claude 才去讀架構文件；沒問到，那個檔案永遠不進 context。

出問題時的排查清單

寫好之後也建議跑一次官方的 skill 驗證工具，它會先抓出結構性問題（目錄、檔名、frontmatter 格式），比自己瞎猜省時間。剩下的常見狀況，對照這份清單處理：

• 不觸發：補強 description，把你實際的說法加進去。
• 載入不了：檢查 SKILL.md 是否在具名資料夾內、檔名大小寫是否正確、YAML 是否合法。
• 用錯 skill：幾個 skill 的描述太像，把它們改寫得更有區別。
• 被蓋掉：檢查優先權階層，必要時改名。
• 執行期出錯：檢查相依套件有沒有裝、腳本有沒有執行權限、路徑一律用正斜線。