Claude Code Skills 實戰：從寫第一個到避開所有坑

大家好，我是宇辰AI編程。

你有沒有遇到過這種情況：每次讓 Claude Code 幫你做代碼審查，你都要重複說一遍「先看命名規範、再查有沒有硬編碼密鑰、最後檢查測試覆蓋」？或者每次部署前都要提醒它「先跑測試、再改版本號、最後生成 changelog」？

說了三遍之後我就煩了。這些東西不應該每次都重複說，應該寫下來讓它自己記住。

這就是 Skills 要解決的問題——把你的經驗封裝成 Claude Code 能調用的技能包，寫一次，用無數次。

有個類比我覺得很貼切：MCP 給了 Claude 一間專業廚房，鍋碗瓢盆一應俱全；但光有廚房不夠，你還得給它菜譜。Skills 就是那份菜譜。

經常有人誤解 Skills「只不過是 markdown 文件」。其實 Skills 是文件夾——可以包含腳本、資源文件、參考文檔、模板，Claude 會自動發現和使用這些內容。一個 Skill 的完整結構長這樣：

my-skill/
├── SKILL.md           # 核心說明（必須有）
├── template.md        # 模板，讓 Claude 填充
├── references/
│   └── api.md         # 參考文檔（按需讀取，不佔常駐上下文）
└── scripts/
    └── validate.sh    # Claude 可以執行的腳本

和 MCP、Hooks、Subagent 的邊界也很清晰：

• MCP = 給 Claude 新的動作能力（連接瀏覽器、數據庫）
• Skills = 給 Claude 一套工作方法（怎麼做一件事）
• Hooks = 強制約束和審計（做完之後自動檢查）
• Subagent = 隔離執行環境（獨立跑一個任務）

如果你之前用過 .claude/commands/ 下的自定義命令——它已經合併進 Skills 了。舊的 commands 文件還能用，但新建的話建議直接用 skills/ 目錄。

在自己寫 Skill 之前，先看看 Claude Code 自帶的幾個——直接能用，不需要任何配置。

內置 Skills：開箱即用

◈/simplify — 自動代碼審查 + 重構

每次寫完一段代碼就跑一遍。它會並行啓動三個審查 Agent：代碼複用審查（找重複代碼）、代碼質量審查（查邏輯錯誤和邊界情況）、效率審查（找性能瓶頸），然後彙總發現並自動修復。

/simplify                          # 審查所有最近變更
/simplify focus on error handling   # 聚焦錯誤處理

相當於寫完代碼自動 Code Review + 自動重構，省掉一輪人工審查。

◈/batch — 大規模並行變更

把一個大任務拆成 5-30 個獨立單元，每個在隔離的 Git Worktree 裏並行執行。適合模式化的批量遷移——框架遷移、API 版本升級、給整個項目加 TypeScript 類型。

/batch migrate src/ from Jest to Vitest
/batch add TypeScript types to all JavaScript files in lib/

◈/loop — 定時輪詢

按間隔重複執行一個命令。監控部署、檢查 CI 狀態用得上。

/loop 5m check if the deploy finished
/loop 1h check for new PR comments

◈skill-creator — 用 AI 寫 AI 的技能

要創建新 Skill 不用手寫，直接告訴 Claude「幫我創建一個 deploy 技能」，它會自動調用 skill-creator 幫你生成 SKILL.md、配好 frontmatter、建好目錄結構。修改現有 Skill 也行：「修改我的 commit 技能，添加 changelog 生成」。

內置的先用起來。接下來教你怎麼自己寫。

寫你的第一個 Skill

◈最小示例

在 .claude/skills/review/ 下創建 SKILL.md：

---
name:review
description:Reviewcodechangesforquality,security,andstyleissues
---

## Steps
1.Run`gitdiff--cached`togetstagedchanges
2.Foreachchangedfile,check:
   -Namingconventionsmatchprojectstyle
   -Nohardcodedsecretsorcredentials
   -Errorhandlingispresent
   -Testscoverthechange
3. Output a summary:issuesfound,severity,suggestedfixes

## Output Format
-✅Pass:Noissues
-⚠️Warning:Minorissues(listthem)
-❌Fail:Criticalissues(listthemwithfixsuggestions)

保存後在 Claude Code 裏輸入 /review，它就會按這個流程審查你的代碼。

◈Frontmatter 字段

--- 之間的 YAML 頭部控制 Skill 的行為：

◈參數和動態注入

Skill 支持參數傳遞：/deploy staging 會把 staging 填入 $ARGUMENTS。

更強大的是 !`command` 語法——在 Skill 內容發給 Claude 之前先跑一段 shell 命令，把輸出注入進去：

---
name:pr-summary
description:Summarizechangesinapullrequest
context:fork
agent:Explore
---

## Pull request context
-PR diff:!`ghprdiff`
-PR comments:!`ghprview--comments`
-Changed files:!`ghprdiff--name-only`

## Your task
Summarizethispullrequest...

這樣 Claude 讀到的 Skill 內容已經包含了最新的 PR 數據，不需要它再去跑命令。

三種 Skill 類型

寫了幾十個 Skill 之後，你會發現它們基本落在三種類型裏：

◈類型一：檢查清單型（質量門禁）

發佈前跑一遍，確保不漏項：

---
name:release-check
description:Usebeforecuttingareleasetoverifybuild,version,andsmoketest.
disable-model-invocation:true
---

## Pre-flight (All must pass)
- [ ] `cargobuild--release`passes
- [ ] `cargoclippy---Dwarnings`clean
- [ ] VersionbumpedinCargo.toml
- [ ] CHANGELOGupdated
- [ ] `kakudoctor`passesoncleanenv

## Output
Pass/Failperitem.AnyFailmustbefixedbeforerelease.

disable-model-invocation: true 是關鍵——發佈是高風險操作，只能你手動觸發，不讓 Claude 自己決定要不要跑。

◈類型二：工作流型（標準化操作）

把多步驟操作固化下來，內置回滾方案：

---
name:config-migration
description:Migrateconfigschema.Runonlywhenexplicitlyrequested.
disable-model-invocation:true
---

## Steps
1. Backup:`cp~/.config/kaku/config.toml~/.config/kaku/config.toml.bak`
2. Dry run:`kakuconfigmigrate--dry-run`
3. Apply:remove`--dry-run`afterconfirmingoutput
4. Verify:`kakudoctor`allpass

## Rollback
`cp~/.config/kaku/config.toml.bak~/.config/kaku/config.toml`

◈類型三：領域專家型（封裝決策框架）

運行時出問題，讓 Claude 按固定路徑收集證據，不要瞎猜：

---
name:runtime-diagnosis
description:Usewhenappcrashes,hangs,orbehavesunexpectedlyatruntime.
---

## Evidence Collection
1.Run`kakudoctor`andcapturefulloutput
2.Last50linesof`~/.local/share/kaku/logs/`
3. Plugin state:`kaku--list-plugins`

## Decision Matrix
|Symptom|FirstCheck|
|---|---|
|Crashonstartup|doctoroutput→Luasyntaxerror|
|Renderingglitch|GPUbackend/terminalcapability|
|Confignotapplied|Configpath+schemaversion|

## Output Format
Rootcause/Blastradius/Fixsteps/Verificationcommand

高級用法

◈context: fork — 不污染主對話

有些 Skill 會產生大量輸出（比如掃全倉庫、跑完整測試），塞進主對話會擠佔上下文。設 context: fork 讓它在獨立的子 Agent 裏跑，只把結果摘要返回主線程。

◈工具限制

allowed-tools: Read Grep Glob

只允許這個 Skill 用讀取類工具，不能寫文件也不能跑 Bash。適合審查類 Skill——你不希望審查員順手改了代碼。

◈調用頻率策略

每個啓用的 Skill，它的 description 會常駐在上下文裏，佔 token。所以：

• 高頻（>1 次/會話） → 保持默認，優化 description 長度
• 低頻（<1 次/會話） → 設 disable-model-invocation: true，手動觸發
• 極低頻（<1 次/月） → 直接移除 Skill，改寫到文檔裏

寫好 Skill 的原則與反模式

◈description 是最重要的字段

Claude 靠 description 判斷「什麼時候該用這個 Skill」。寫得太短會誤觸發，寫得太長浪費上下文：

# ❌ 太短，任何後端工作都會觸發
description:helpwithbackend

# ❌ 太長，浪費 45 tokens
description:|
  This skill helps you review code changes in Rust projects.
  It checks for common issues like unsafe code, error handling...
  Use this when you want to ensure code quality before merging.

# ✅ 精準，只有 9 tokens
description:UseforPRreviewswithfocusoncorrectness.

◈常見反模式

之前看到有人分享說自己寫了 30 個 Skills，讀完 Anthropic 官方文章後發現基本全用錯了。他犯的最典型的錯誤就是把 Skill 當成「保存的 Prompt」——寫了一大段指令塞進 SKILL.md，沒有步驟、沒有輸出格式、沒有停止條件。結果就是 Claude 每次調用這個 Skill 的表現都不一樣，有時候做多了，有時候少了一步。

後來他按官方建議重寫：每個 Skill 有明確的觸發條件、分步驟的操作流程、固定的輸出格式。改完之後效果立竿見影——Skill 不是模板，是工作流，這個區別很關鍵。

四個值得裝的 Skills 插件

自己寫 Skill 固然好，但社區裏已經有人把整套方法論打包好了。這幾個我都用過一段時間，說說真實感受。

先說背景：這幾個插件本質上在解決同一個問題——AI Agent 寫代碼太隨性了，容易跳過規劃直接動手、質量忽高忽低、改完一個地方壞了另外三個。它們的解決思路都是用工作流來約束 AI，但側重點很不一樣。

◈Superpowers — 流程紀律派

社區裏 Star 最多的 Skills 框架，裝上之後 Claude 每一輪都會走完整流程：先寫 spec → 出計劃 → 拆任務 → 執行 → 跑測試 → 代碼審查 → 提交。

裏面有幾個 Skill 是真的解決了痛點：

• verification-before-completion — Claude 最讓人頭疼的毛病就是「說修好了但其實沒修好」。這個 Skill 強制它在宣稱完成之前跑驗證，必須拿到通過的證據才算完
• systematic-debugging — 不讓 Claude 瞎猜 bug 原因，按四階段收集證據、定位根因
• test-driven-development — 強制先寫測試再寫實現，不是寫完代碼再補測試

說實話，大任務用 Superpowers 效果很好。但小任務——比如改個按鈕樣式、加個字段——也按這套完整流程走，就太重了。一個五分鐘能搞定的事被拉成半小時，授權確認點到手痠，token 也燒得快。

◈Compound Engineering — 知識複利派

這個插件的核心理念是「80% 規劃和評審，20% 執行」。聽起來像廢話，但它有一個別人沒有的殺手級功能：/ce:compound。

每次完成一個任務後跑一遍 /ce:compound，它會把這次犯的錯、學到的東西、踩過的坑沉澱到知識庫裏。下次遇到類似情況，Claude 不會再犯同樣的錯。這就是它叫「複利」的原因——用得越久，Claude 越聰明。

另一個有意思的是 /ce:ideate，它會針對項目提出改善建議，還會排優先級、過濾掉不重要的。不過說實話，我實際用下來，它提出的改善點經常不痛不癢，需要你自己判斷哪些值得做。

◈Gstack — 產品打磨派

YC 現任總裁 Garry Tan 做的。這個定位就不太一樣了——其他框架關注的是「怎麼把代碼寫好」，Gstack 關注的是「你到底應不應該寫這段代碼」。

它把 Claude Code 變成一支 23 個 Agent 組成的虛擬團隊，最讓我印象深刻的是 /office-hours——真的像 YC 的 office hours 一樣，對你的產品邏輯進行靈魂拷問。「你的用戶是誰？」「這個功能解決了什麼問題？」「有沒有更簡單的方案？」被 AI 追問幾輪之後，很多你以為想清楚的事其實沒想清楚。

/plan-ceo-review 從戰略視角挑戰你的計劃，/retro 做每週覆盤，/learn 把項目知識持續積累。不過它偏產品思維，如果你只是做純技術重構、改個 bug，這套工具就有點大材小用了。

◈我的搭配方式

這幾個不是互斥的，可以組合：

• 從 0 做產品 → 先用 Gstack 的 /office-hours 打磨方向，確認要做了再用 Superpowers 執行
• 日常開發 → Superpowers 就夠了，但小任務關掉它直接對話
• 長期維護的項目 → Compound Engineering 沉澱知識，減少團隊重複踩坑

◈Baoyu Skills — 不寫代碼的人也能用

如果你像我一樣，不只是寫代碼，還做公眾號、寫內容，那 Baoyu Skills 必裝。19 個 Skills 覆蓋了內容創作全鏈路——從信息圖生成（21 種佈局 × 20 種風格）到 Markdown 轉微信排版再到一鍵發佈公眾號。

這個系列文章的所有信息圖和封面圖就是用它生成的。

Plugins 機制

上面三個都是通過 Plugins 機制安裝的。Plugins 是 Skills 的分發包——把 Skills、Agents、Hooks、MCP Server 打包成一個可安裝的插件。用 /plugin 命令管理：

# 查看已安裝的插件
/plugin list

# 從 Marketplace 安裝
/plugin install plugin-name@marketplace-name

# 卸載
/plugin uninstall plugin-name

官方 Marketplace 在 /plugin 命令裏直接瀏覽，分為代碼智能、外部集成、開發工作流、輸出樣式四大類。GitHub 上搜 claude-skills 也能找到大量社區貢獻的 Skills。

◈什麼時候用 Skill，什麼時候直接對話

寫在最後

回過頭看，Skills 的門檻其實很低——就是一個文件夾加一個 SKILL.md。但寫好和寫對之間差距很大。我自己最深的教訓是早期裝了太多 Skill，每個都開着自動調用，結果上下文被描述符佔了一大塊，Claude 反而變遲鈍了。後來把低頻的全改成手動觸發、極低頻的直接刪掉，才恢復正常。

說白了，Skills 不是裝得越多越好，而是每一個都要有明確的存在理由。

到這裏為止，Claude Code 能做的事還是侷限在本地——讀代碼、跑命令、改文件。但如果你想讓它幫你抓網頁數據、查數據庫、調第三方 API 呢？

下一篇聊 MCP，讓 Claude Code 真正走出本地文件系統。

如果你在 Claude 的訂閲、安裝或使用中遇到任何問題，歡迎關注【宇辰AI編程】公眾號，回覆關鍵詞「claude」加羣交流，羣裏有不少老用戶分享經驗，我也會盡力幫大家排坑。