前言

前面章節我們一直都是使用別人所做好的東西（官方），實際上有可能官方的東西可以滿足我們的需求嗎？其實很難。

這一篇我們將會來試著建立屬於自己的 Skill，依照個人需求去建立一個專屬的 Skill，讓我們的工作流程更順暢。

回憶一下 SKILL 結構

那麼前面我們有快速介紹過 SKILL，以及認識它的結構：

.claude/
└── skills/
    └── commit-message/   ← 這個資料夾的名字就是 SKILL 的名字
        └── SKILL.md

所以 SKILL 本質就是一個資料夾 ＋ 一個 Markdown 檔案，資料夾的名稱就是這個 Skill 的名稱，而 Markdown 檔案就是這個 Skill 的內容。

那這個 SKILL 你可以自己建立，也可以請 AI 幫你建立，但要怎麼建立就又是另一回事了，所以我將會深入解析 SKILL.md 的結構，讓你可以自己建立一個專屬的 Skill。

Note
需要注意不同 AI 廠商所放置 Skill 的位置可能不同，Claude Code 是放在專案的 .claude/skills/，但 Codex 是放在專案的 .agents/skills/，所以要依照不同的 AI 廠商去放置 Skill 的位置。

做一個 commit-message SKILL

目前我們的 money-note 專案一個 SKILL 都沒有，這邊我們就要來從零建立一個 SKILL。

那......我們要建立什麼 SKILL 呢？其實我們可以來建立一個「自動觸發」撰寫 Commit 訊息的 SKILL。

那我們該怎麼寫呢？基本上一個 SKILL 的呼叫方式會有兩種，分別是：

• 一種是自動觸發。
• 一種是手動觸發。

那這邊我們先不講手動觸發的部分，先講自動觸發的原因，基本上自動觸發依賴於 SKILL.md 的 frontmatter 裡的 description，所以這個 description 的寫法就非常重要。

Note
frontmatter 指的就是 SKILL 最上方用兩個 --- 包起來的區塊，你可以想像成履歷最上面的個人資料，那部分專門放「關於這份檔案的資訊」，其中部落格文章常拿它放標題、作者、日期（包含我撰寫 這篇文章的 metadata 也是放在 frontmatter 裡）。

那 description 到底要怎麼寫呢？基本上我認為，description 的寫法要包含三個重點：

• 觸發時機： 什麼時候要觸發這個 SKILL。
• 它會做什麼： 這個 SKILL 會做什麼事情。
• 重要邊界： 這個 SKILL 的重要限制。

有點難懂吧？所以這邊我們就來實際建立一個 commit-message SKILL，並且拆解它的內容吧！

首先請你在你的專案根目錄，以我們的 money-note 專案為例，建立一個 .claude/skills/commit-message/ 資料夾，然後在裡面建立一個 SKILL.md，並且把下面這份第一版貼進去：

---
name: commit-message
description: 當使用者要求 commit、提交或存檔變更時使用。先檢查變更範圍，依本專案格式提出繁體中文 commit 訊息，取得使用者確認後才提交。
---

# commit 訊息規範

格式：`<型別>: <一句話描述做了什麼>`

## 型別

- feat：新功能
- fix：修 bug
- style：視覺調整（不動邏輯）
- docs：文件（SPEC、DESIGN、CLAUDE.md 等）
- refactor：重構（行為不變）
- test：測試
- chore：雜務（設定、套件等）

## 規則

- 先讀 git status 與 diff，列出預計提交的檔案；不要自動把所有未追蹤檔加入
- 看到 `.env`、金鑰、憑證或無法判斷的檔案就停下來提醒
- 先提出 commit 訊息與範圍，取得使用者確認後才執行 git add 與 git commit
- 描述用繁體中文，講「做了什麼」，不是「改了哪個檔案」
- fix 的描述要帶出原因，方便日後翻歷史
- 一次 commit 對應一件事，混了就先拆

## 範例

- feat: 新增支出統計頁與圓餅圖
- fix: 刪除改用 id 避免排序後 index 錯位

那目前來講，你的專案結構應該會長的像這樣：

當然，你也可以直接把上面這些丟給 AI 讓 它幫你建立，這樣就不用自己手動建立了。

請在專案根目錄建立 `.claude/skills/commit-message/SKILL.md`，內容如下：
---
name: commit-message
description: 當使用者要求 commit、提交或存檔變更時使用。

......略過

那這邊我所提供的範例 SKILL 就是一個最基本的 commit-message SKILL，只要當使用者要求 commit、提交或存檔變更時，AI 就會呼叫這個 SKILL，然後會依照 SKILL 的規則，先檢查變更範圍，依本專案格式提出繁體中文 commit 訊息，取得使用者確認後才提交。

因此 description 類似於 Google 搜尋的關鍵字，Claude 會依照使用者的需求去比對 description，如果符合就會自動觸發這個 SKILL，而這邊解釋的就是「自動觸發」。

那「手動觸發」呢？其實手動觸發很簡單，手動觸發會基於你的資料夾名稱而來，舉例來講我們資料夾就叫做 commit-message，所以手動觸發的指令就是 /commit-message，這樣就可以直接叫用這個 SKILL。

那為什麼不一開始就直接把整份 SKILL 掛進來呢？反而是透過 description 去比對使用者的需求呢？有些人可能會有這樣的疑問，其實原因很簡單

因為這樣可以避免 context 被灌爆

因此 AI 平常不會把每個 skill 全文攤在桌上（那太佔 context），它只看得到名稱跟描述，靠這段資訊判斷「現在的任務用不用得上」，對上了才展開全部內容。

而 SKILL 的撰寫方式也有一定推薦的格式，也就是：

1. 格式： 一眼看懂的骨架，讓人知道這個 SKILL 的結構。
2. 規則： 判斷的依據，讓人知道這個 SKILL 的規則。
3. 範例： 模仿的樣板，讓人知道這個 SKILL 的範例。

有發現嗎？我把 AI 當作人來教，這個三段結構跟我們前面講的「教人 SOP」的方式是一模一樣的，因為對 AI 來講，範例特別有效，它照著樣板寫比照著規則推理穩得多，所以寫 skill 的時候範例永遠不要省。

但我自己來講，我的實際應用 SKILL 還會有底下資訊：

metadata:
  author: Ray
  version: "2026/09/01"

這個 metadata 並非是 SKILL 硬性規定，SKILL 只有硬性要求要有 name 與 description，而 metadata 是官方提供的欄位，並不是我亂掰的，但 AI 並不會拿它做任何事，所以我就拿來放作者跟版本啦～

那什麼時候可以封裝成 SKILL 呢？基本上我認為同一件事講三遍以上，就可以寫成 SKILL，這樣就不用每次都要重複講了。

Note
當然 SKILL 裡面還有很多其他的設定可以調整，像是限制這個 SKILL 只能用哪些工具的 allowed-tools、不讓 AI 自動觸發、只准你手動呼叫的 disable-model-invocation，甚至可以讓 SKILL 像斜線指令一樣接收參數。這些今天先不展開，等你的 SKILL 越寫越多自然會遇到，需要的時候翻官方文件就有。

結語

那麼這一篇也差不多到這邊結束了，一樣來收尾一下吧～

• SKILL 可以基於專案或個人偏好去建立，專案使用放 .claude/skills/，個人使用放 ~/.claude/skills/
• description 是自動觸發的核心，撰寫方式很簡單，越像是「當使用者要求某某時使用」就越容易被自動觸發
• SKILL 核心內容為三段：
  1. 格式。
  2. 規則。
  3. 範例，尤其是範例千萬不要省。
• 什麼時候要封裝成 SKILL？同一件事講三遍以上就可以

那我們明天見啦～