Claude Skills 入門

為什麼你需要 Skill？

你已經有重複痛點，只是沒命名

先問自己幾個問題：

• 每週是不是都要做一份結構幾乎一樣的客戶報告？
• 跟 Claude 對話時，是不是常常「先貼一段背景再問問題」，而那段背景每次都差不多？
• 下班前是不是有個固定動作——寫日報、收尾 git、整理 Slack？

有任一題答「對」，恭喜——你已經有 skill 候選了，只是還沒命名、固化、收藏起來。

Skill 一句話定義

Skill = 你給 Claude 的「按鈕」。按下去，它就照你約好的流程做完一件事。

• 是一個資料夾，住在 ~/.claude/skills/<skill-name>/
• 裡面至少有一份 SKILL.md，告訴 Claude「什麼時候要用」+「該怎麼做」
• 不需要寫程式——SKILL.md 是自然語言寫的指示

Skill / Hook / Agent — 三種自動化單位

Skill 是中間那一格——你還在迴圈裡，但流程是固定的。

快速判斷四問

最佳 skill 候選 = Q1 ≥ 3 + Q2 大致一樣 + Q3 中間需判斷 + Q4 ≥ 10 分鐘。

5 分鐘體驗：跑一個現成 skill

Pre-flight check

which claude
ls ~/.claude/skills/ | head -10

看到一堆 skill 資料夾名稱列出來 = 環境 OK。看到「No such file or directory」= 還沒裝過任何 skill，先跑：

/sync-skill-lab

如果連 /sync-skill-lab 都沒反應，看部門 onboarding 文件 ~/GitHub/claude-team-skill-lab/setup/team-memhall-onboarding.md。環境問題不是你的錯——別因此打擊自己學 skill 的信心。

三種觸發方式

1. 直接打 / 命令：例如 /team-start
2. 自然語言：例如「我今天接力」「team 開場」「看部門最近做什麼」
3. 觸發詞匹配：每個 skill 在 description 宣告自己什麼時候該被叫——下一節深入

推薦先玩過的 5 個部門 skill

• /team-start — 看部門最近做什麼（每天早上跑）
• /team-wrap-up — 下班前把今天決策寫進部門記憶
• /skill-spotter — 從今天對話撈 skill 候選（第 5 節深入）
• /linkedin-post — 把專案轉成 LinkedIn 發文草稿
• /sync-skill-lab — 從 GitHub 拉最新 skill 到本機

找 skill 三步法

# Step 1 翻 index 找關鍵字
cat ~/.claude/skills/_INDEX.md | grep -i "report\|報告"

# Step 2 看候選 skill 的 description
head -10 ~/.claude/skills/<skill-name>/SKILL.md

# Step 3 看 README（如果有）
cat ~/.claude/skills/<skill-name>/README.md

SKILL.md 解剖學

Skill 資料夾標準長相

my-skill/                  # 資料夾名 = skill 名（kebab-case）
├── SKILL.md               # 必要！skill 的「主腦」
├── README.md              # 給人看的（選填）
├── references/            # 進階參考（選填，需要時才讀）
│   ├── decision-tree.md
│   └── examples.md
├── scripts/               # 輔助腳本（選填）
│   └── helper.py
└── examples/              # 範例輸入輸出（選填）

只有 SKILL.md 是必要的。其他都是隨需求加。

SKILL.md = frontmatter + body

---
name: weekly-report
description: 週報草稿。當用戶說「寫週報」「weekly report」時觸發。
version: 1.0.0
author: "@yourname"
tags:
  - workflow
  - report
---

# /weekly-report — 週報生成

## 目標
...（這裡開始是 body）

• Frontmatter（YAML metadata）：skill 的身分證。Claude 不會跑這段，只用來識別 + 決定觸發。
• Body（Markdown）：skill 的劇本。Claude 會照這段一步一步跑。

Frontmatter 必填三欄

選填但建議都寫

author: "@MakiDevelop"
tags: [workflow, report]
argument-hint: "[選填: focus 提示]"
allowed-tools:
  - Read
  - Bash(git*)              # pattern match，避免每次跳「allow?」
  - mcp__team-memhall__write_entry
status: experimental         # active / experimental / deprecated

allowed-tools 最值得寫——沒寫的話 skill 每次跑到工具都會被打斷。用 pattern match 寫，例如 Bash(git*) 只授權 git 開頭的命令；不要直接寫 Bash 裸授權。

Body 標準骨架

# /skill-name — 標題

## 目標
一段話說明這個 Skill 解決什麼問題。

## 不適用場景
列出什麼情況不該用這個 Skill。      ← 不能省，避免誤觸發

## 輸入
需要什麼參數或資訊。

## 步驟
核心工作流程，step by step。      ← 要具體，不是「跟用戶討論」這種模糊指示

## 輸出
最終產出什麼。

## Quality Gates
完成後的自我檢查清單（- [ ] 形式）。

## Heuristics（選填）
經驗法則、快速判斷依據。

★ Progressive Disclosure：三層載入機制

Body 行數 sweet spot

原則：超過 150 行先問自己「是不是有東西該丟到 references/？」決策骨架留 body，詳細展開丟 references。

description 是觸發機制

回想第 3 節的 progressive disclosure——只有第 1 層（name + description）永遠在 context。意思是：你裝 100 個 skill，每個的 description 都會被 Claude 隨時看見；但 Claude 不會主動讀 SKILL.md body，除非 description 比中。

寫法公式

三段缺一不可

1. Part 1 What（功能）：「廠商方案評估（六位一體）。」
2. Part 2 How（做什麼）：「讀取廠商提案 PDF/Doc，多 Agent 協作分析技術架構、報價合理性、市場行情、廠商背景，輸出 Google Doc 報告 + Google Sheet 比較表。」
3. Part 3 When（觸發詞）：「當用戶說『評估這份提案』『vendor eval』『廠商報價分析』時使用。」

對照範例

Pushy 4 招（讓 Claude 敢觸發）

Claude 有 undertrigger 傾向——寧可不觸發也不要錯觸發。description 要主動 push 它一下。

1. 多列觸發詞（5–10 個都 OK，cover 不同講法）
2. 加「proactively apply」/「強烈建議」等指令性措辭
3. 明列適用場景（不只是觸發詞，還有業務情境）
4. 明列「不適用」——讓 Claude 知道誤觸發會被抓到，反而更敢觸發

實案：team-wrap-up 的 description

description: "部門 session 收尾。將本 session 的關鍵決策 / 進度 / 下一步寫入 team-memhall（部門共享記憶）。當用戶說「team 收工」「team-wrap-up」「部門收尾」「team session 結束」「寫進部門記憶」時使用。寫入需要先設定 team-memhall MCP server。"

What ✅ How ✅ When（5 個觸發詞）✅ 限制條件（需要 MCP server）✅。這就是範本。

從對話發現 Skill 候選

5 類訊號（按候選價值排）

Score 公式

• frequency：每週 1 次 = 1 / 每天 1 次 = 5 / 每天 ≥ 3 次 = 10
• estimated_token_saved：簡單命令 50–100 / 多步流程 500–1000 / 複雜分析 2000+
• stability（最關鍵）：完全一樣 = 1.0（其實該寫 hook） / 大致一樣 = 0.7–0.9 ✅ / 步驟會變骨架穩 = 0.5–0.7 / 每次都不一樣 = 0.0–0.4 ❌
• implementation_cost：純 prompt = 1 / 簡單 bash = 2 / decision tree = 3 / Python = 4 / MCP 整合 = 5

用 skill-spotter 自動撈

部門有 skill 專門做這件事：

/skill-spotter

它會：

1. 讀今天的 session transcript
2. 撈當日 git log + memhall episode
3. 用 5 類訊號 + Score 公式找 top 候選
4. 對每個候選用「三門診斷法」（下節）告訴你該寫 Hook / Skill / Agent
5. 產出可直接交給 skill-creator 的 spec
6. 強制做 PII scrubbing

部門慣例：下班前 5 分鐘跑一次。撈到 0 個是正常訊號（今天沒重複到值得固化）——不要硬湊，硬湊會產生一次性垃圾 skill。

三門診斷法：Hook / Skill / Agent 怎麼選

三門本質

診斷三問（決策樹）

3 個生活範例

① 每次 commit 前要跑 ruff check → Hook

Q1 規則明確？是——「commit 前一律跑 ruff」。寫 Skill 反而要你說「跑 ruff」才會跑，多一個動作。

② 客戶 onboarding 4 步驟（建 Drive、設 Slack、寄歡迎信、登 Salesforce）→ Skill

Q1 否（歡迎信內容會變）→ Q2 是（你要看 Slack channel 名稱、選歡迎信模板）。流程固定 4 步、需要你在迴圈裡——標準 Skill 場景。

③ 老闆問「RAG 要不要做」→ Agent

Q1 否 → Q2 否（你不知道流程）→ Q3 是（需要自主研究）。寫不出固定流程的事就交給 Agent。

④ 寫今年聖誕 party 策劃 → 不做

Q1 否 → Q2 是但只做一次。寫 skill 的成本要付——一次性的事用普通對話解決就好。「不做」也是合理答案。

寫第一個 Skill

skill-creator = 寫 skill 的對話教練

它不是自動寫 skill 的 AI——它會問你問題、給你模板、檢查你寫得好不好。5 個階段：

1. Capture Intent：問你「該讓 Claude 做什麼 / 何時觸發 / 預期輸出」
2. Interview & Research：問細節、邊界場景、跟既有 skill 重疊性
3. Write SKILL.md：草擬一份給你看
4. Run Test Cases（進階）：跑 with-skill / without-skill 對照
5. Iterate：根據你的回饋改

Vibe vs Eval 模式

第一次寫 skill 一律走 Vibe。寫過 3-5 個再考慮 Eval。

實戰：weekly-report skill 草稿

---
name: weekly-report
description: "週報草稿生成器。掃描本週 git log + memhall episode，整理成「本週完成 / 下週計畫 / 阻塞」三段式週報，總長 < 500 字。當用戶說「寫週報」「weekly report」「禮拜五的報告」「跟主管交差」「整理本週進度」時使用。不適用於月報或季報。"
version: 0.1.0
author: "@yourname"
tags: [workflow, report]
status: experimental
allowed-tools:
  - Bash(git*)
  - mcp__team-memhall__search_entries
  - Read
---

# /weekly-report — 週報草稿生成器

## 目標
每週五讓你 5 分鐘寫完週報，不用回想做了什麼。

## 不適用場景
- 月報 / 季報（用 monthly-report）
- 不在 git repo（會降級為純 memhall mode）

## 步驟
1. 撈本週 git log（`git log --since='1 week ago' --all --oneline`）
2. 查 memhall（namespace=shared, since 7 天, type=episode）
3. 整理「本週完成」5-8 條 bullet
4. 問用戶「下週計畫」整理 3-5 條
5. 問用戶「阻塞」整理 1-3 條
6. 輸出三段式 markdown

## Quality Gates
- [ ] 三段都有內容
- [ ] 總長 < 500 字
- [ ] 沒有公司敏感字串

Quality Gates 8 條（部門標準）

任一條不過 = 不該宣稱完成。Gate 1 第一份通常不過——這正常。其他 7 條應該都要過。

避 5 大坑

坑 1：PII / 公司敏感資訊外洩 ⚠️

SKILL.md 不像 prompt——它留在檔案裡，會 sync 到 git，可能上 PR，可能被同事看到。任何寫死的客戶名 / token / 內部 URL 都回不去。

解法：參數化

坑 2：一次性垃圾 Skill

你寫了 2026-q2-okr-helper——Q3 開始就用不到。但它還在目錄，每個 session 都載入它的 frontmatter，浪費 context。

解法：stability ≥ 0.5 + 預估有效期 ≥ 3 個月。不確定就不寫。每季跑 ls -lat ~/.claude/skills/ | tail -20 找出 3 個月沒用的，刪或標 deprecated。

坑 3：過度抽象 Skill

原則：一個 skill = 一個動詞 + 一個受詞。寫不出來就是範圍太大，先拆。

坑 4：Context Bloat（SKILL.md 過長）

body 1000 行——所有 edge case、歷史脈絡、範例都塞進去。第 3 節提過，body 觸發後永久壓在 context。越長 LLM 越分心。

解法：body 只放決策骨架（步驟 + 失敗處理 + Quality Gates），詳細丟 references/。Body < 150 行。

坑 5：allowed-tools 太鬆 / 太緊

絕不直接授權：Bash(rm*) / Bash(sudo*) / Bash(chmod*) / Bash(curl * | sh)。skill 真的需要這些 → 不要寫進 allowed-tools，讓它每次跳出來給你看再 yes。

Bonus：用 audit-skill 做安全審查

/audit-skill ~/.claude/skills/<your-skill>/

會檢查 telemetry / 對外網路 / 敏感檔案 / outbound API / allowed-tools 合理性 / PII。寫完 skill → 跑 audit-skill → 才 PR，這是部門慣例。

上 PR 給部門共享

個人 vs 部門

判準：解決的問題至少 2 個同事也有 → 上 PR。只綁你個人習慣 → 留個人目錄不要污染部門。

部門 repo 結構

claude-team-skill-lab/
├── skills/
│   ├── workflow/         # 業務流程、評估、報告、部署、收尾
│   ├── engineering/      # Code review, testing, debugging
│   ├── research/         # 技術調研、市場分析
│   └── writing/          # 文件、blog、公告
├── skill-spec-drafts/    # spec 暫存（從 skill-spotter hand-off）
├── SKILL_CONVENTION.md   # 部門撰寫規範
└── README.md

上 PR 6 步驟

1. 確認在個人目錄能跑——實戰用過 ≥ 3 次再考慮上 PR
2. 跑 audit-skill：/audit-skill ~/.claude/skills/<your-skill>/
3. 搬到 repo 對應分類：cp -r ~/.claude/skills/weekly-report ~/GitHub/claude-team-skill-lab/skills/workflow/
4. 對齊 SKILL_CONVENTION.md——name / description / body 結構 / frontmatter 必填欄位
5. 開 PR：

cd ~/GitHub/claude-team-skill-lab
git checkout -b add-weekly-report-skill
git add skills/workflow/weekly-report/
git commit -m "feat(skill): 新增 weekly-report — 週報草稿生成器

每週五掃 git log + memhall episode，整理成 3 段式週報。
v0.1 experimental，已實戰 5 次，待部門 review。

驗證：audit-skill pass / 已用 3 次"
git push -u origin add-weekly-report-skill

6. Review 期間做什麼？maintainer 通常給 3 類回饋：格式（description 不夠 pushy / body 太長）、安全（PII / allowed-tools 太鬆）、重疊（跟既有 skill 太像）。1-3 輪後 merge。

skill-optimize：從 experimental 升 active

Skill merge 進部門後 status 一開始是 experimental。要升 active 跑一次 ratchet：

/skill-optimize ~/.claude/skills/<your-skill>/

它對 SKILL.md 跑 9 維 rubric 打分 → 提案改進 → commit → 獨立 subagent 重新打分 → 只保留有量化進步的改動。跑 5-10 輪分數收斂後才改 status。

部門 skill 文化的三層

整個 funnel 走通 = 你從消費者升級成貢獻者。

速查表

[一句話功能]。
[具體做什麼]。
當用戶說「A」「B」「C」「D」時使用。
不適用於 [鄰近 skill 領域]。

priority = (frequency × tokens × stability)
           ─────────────────────────────────
                 implementation_cost

stability < 0.5 → 直接淘汰

Q1 規則明確不需 Claude 判斷？
   是 → Hook
Q2 多步流程 + 你在迴圈裡？
   是 → Skill
Q3 需要自主推理？
   是 → Agent
否 → 不做（一次性 / 太模糊）

☐ 1. 實際用過 ≥ 2-3 次
☐ 2. 一個 skill 解一類問題
☐ 3. description ≥ 4 個觸發詞
☐ 4. 步驟具體不模糊
☐ 5. 輸入輸出明確
☐ 6. 有「不適用場景」≥ 2-3 條
☐ 7. 無 PII（token / 客戶 / IP）
☐ 8. body < 150 行

1. PII 外洩      → 全部參數化
2. 一次性垃圾    → stability >= 0.5
3. 過度抽象      → 一動詞 + 一受詞
4. body 過長     → < 150 行 + references
5. allowed 太鬆  → pattern match

---
name: <kebab-case-name>
description: "<一句話功能>。<具體做什麼>。當用戶說「A」「B」「C」「D」時使用。<不適用場景>。"
version: 0.1.0
author: "@<your-github-handle>"
tags:
  - <category>
argument-hint: "[選填: ...]"
allowed-tools:
  - Read
  - Bash(git*)
status: experimental
---

/team-start        早上開場
/team-wrap-up      下班收尾
/skill-spotter     撈 skill 候選
/skill-creator     寫 skill 教練
/audit-skill       安全審查
/skill-optimize    ratchet 跑分
/sync-skill-lab    拉最新部門 skill

Layer 3  active 部門 skill
   ↑ skill-optimize
Layer 2  experimental 部門 skill
   ↑ audit-skill + PR
Layer 1  個人 skill
   ↑ skill-creator + 實戰
Layer 0  對話痛點
   ↑ skill-spotter