Claude Code 自訂 Skill 建立指南

日期：2026-03-17

TL;DR

Claude Code 支援自訂 Skill，讓 Claude 在特定情境自動觸發對應的工作流程。Skill 檔案放在 ~/.claude/skills/ 目錄下，只需要一個 SKILL.md 即可運作。本篇以建立「自動寫筆記」Skill 為例，紀錄完整流程。

Skill 是什麼

Skill 是一份參考指南，定義了 Claude 在特定情境下應該怎麼做。當使用者的指令符合 Skill 的觸發條件時，Claude 會自動載入並遵循該 Skill 的流程。

概念	說明
觸發方式	Claude 根據 `description` 欄位判斷是否載入
存放位置	`~/.claude/skills/skill-name/SKILL.md`
格式	Markdown + YAML frontmatter
作用範圍	所有使用該 Claude Code 環境的對話

目錄結構

~/.claude/skills/
  write-share-note/        # Skill 名稱（kebab-case）
    SKILL.md               # 主要定義檔（必要）
  vercel-react-best-practices/
    SKILL.md
    AGENTS.md              # 額外參考（選用）
    rules/                 # 支援檔案（選用）

每個 Skill 一個資料夾，資料夾名稱就是 Skill 名稱。

SKILL.md 結構

Frontmatter（YAML）

---
name: write-share-note
description: Use when the user asks to write a note, record something, or says "寫筆記". Triggers when documenting a debugging session or technique.
---

欄位	規則
`name`	只能用英文字母、數字、連字號
`description`	第三人稱，描述何時觸發，不要描述 Skill 做什麼

⚠️ 重要：description 只寫觸發條件，不要摘要流程。 如果 description 寫了「先做 A 再做 B」，Claude 可能會直接照 description 做，跳過讀取完整的 SKILL.md 內容。

內容段落

# Skill 名稱

## Workflow
具體步驟，Claude 會照著執行

## Common Mistakes
常見錯誤，避免踩坑

這個 Skill 的用途是：當使用者說「寫筆記」或「紀錄一下」時，自動將當前對話中的工作成果寫成筆記，發布到 Jekyll 筆記網站。

觸發條件

description: Use when the user asks to write a note, record something, or says "寫筆記", "紀錄", "write a note", "record this".

Workflow 重點

讀取目標 repo 的 CLAUDE.md 取得格式規範
根據規範產生正確的 frontmatter 和檔名
去除機敏資訊（帳密、內部 IP、URL）
以繁體中文撰寫，先結論後過程
Commit 並 push 到 main

建立步驟

# 1. 建立 Skill 目錄
mkdir -p ~/.claude/skills/your-skill-name

# 2. 建立 SKILL.md
# 寫入 frontmatter + 內容（見上方結構）

# 3. 完成！下次對話 Claude 就會自動偵測並使用

不需要重啟 Claude Code，新的 Skill 會在下一次對話開始時自動載入。

Description 撰寫要點

這是最關鍵的部分，決定 Claude 能不能正確找到和使用你的 Skill。

✅ 好的寫法

# 只描述觸發條件
description: Use when the user asks to write a note or says "寫筆記"

# 包含具體症狀和情境
description: Use when tests have race conditions or pass/fail inconsistently

❌ 不好的寫法

# 摘要了流程 — Claude 可能照這段做，跳過讀 SKILL.md
description: Use when writing notes - reads CLAUDE.md, generates frontmatter, strips sensitive info, commits and pushes

# 太模糊
description: For note writing

Skill 類型

類型	說明	範例
Technique	具體步驟的方法	write-share-note、condition-based-waiting
Pattern	思考問題的框架	flatten-with-flags
Reference	API 文件、語法指南	vercel-react-best-practices

進階：支援檔案

如果 Skill 需要額外的參考資料（例如 API 文件超過 100 行），可以拆成獨立檔案：

my-skill/
  SKILL.md         # 主要流程
  api-reference.md # 大量參考資料
  scripts/         # 可執行工具

大部分情況只需要 SKILL.md 就夠了。

結論

步驟	動作
1	`mkdir -p ~/.claude/skills/skill-name`
2	寫 `SKILL.md`（frontmatter + workflow）
3	description 只寫觸發條件，不要摘要流程
4	下次對話自動生效

建立 Skill 的門檻很低，但 description 的寫法直接決定 Claude 能不能正確觸發。把它想成 SEO — 你是在幫未來的 Claude 找到正確的指南。