Commands、Skills、Subagents、Rules：整理139個擴充功能後學到的經驗

在為Claude Code建立了95個hooks、44個skills、85個commands和11個rule檔案之後，我學到一件事：選錯抽象比建錯功能更浪費時間。一個本該是rule的skill讓我的上下文膨脹了40%。一個本該是skill的command迫使我每次操作API端點時都得記住輸入/fastapi。¹

TL;DR

Claude Code提供四種擴充行為的方式：Commands（使用者觸發的提示）、Skills（自動調用的上下文）、Subagents（委派的任務執行器）和Rules（始終啟用的約束）。在整理139個擴充功能之後，我發現決策框架其實很簡單：Rules用於不變量、Skills用於領域專業知識、Commands用於工作流程、Subagents用於隔離。困難的部分在於辨識出何時選錯了，以及如何遷移。

四種抽象（附真實範例）

Commands：”/commit”及其他84個

Commands在我輸入/command-name時啟動。每個command會展開成一個提示範本。²

我的85個commands包括/commit（智慧git提交）、/review（啟動程式碼審查代理）、/deploy（部署檢查清單）、/publish-check（部落格發布前驗證）和/deliberate（多代理研究）。

我犯的錯誤： 我把/fastapi建成了一個command，用來按需注入FastAPI模式。問題是：我有一半的時間忘了輸入它。每次忘記調用，就意味著代理錯過了我想強制執行的模式。解決方法是將/fastapi遷移為具有自動啟動功能的Skill。

Skills：44個自動啟動的知識模組

Skills會在對話內容匹配skill描述時自動啟動。我不需要輸入任何command；系統會根據上下文自動注入相關的專業知識。³

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

我的44個skills涵蓋： - 領域知識（8個）：FastAPI、SwiftUI、HTMX/Alpine、資料庫、測試、除錯、架構、安全性 - 部落格基礎設施（7個）：blog-writer-core、blog-evaluator、citation-verifier、SEO playbook - 理念/品質（5個）：Shokunin（Jiro）、No Shortcuts、Rubin essence、設計原則 - 多代理（3個）：deliberation、review、內容創作 - 專案專用（4個）：個人網站內容、ResumeGeni部落格、Obsidian擷取

40%上下文膨脹事件： 早期，我將完整的FastAPI模式指南（800行）放入了Rule檔案。Rules會在每個工作階段中載入。當我開發iOS應用程式、處理CSS或撰寫部落格內容時，800行不相關的FastAPI模式消耗了大量上下文token。將內容移到描述為「FastAPI backend development」的Skill後解決了問題：該skill只在API開發工作中才會載入。⁴

Subagents：隔離的審查者

Subagents在自己的上下文視窗中執行，具有受限的工具存取權限和獨立的權限。⁵

我的subagents包括security-reviewer（唯讀存取、OWASP漏洞掃描）、test-runner（執行測試、分析失敗）和conventions-reviewer（專案標準檢查）。

為什麼隔離很重要： 在程式碼審查期間，審查者不應該能夠編輯檔案。Skill可以注入審查知識，但審查仍在主上下文中進行，擁有完整的寫入權限。Subagent則從架構層面強制執行唯讀存取。

Rules：11個始終啟用的約束檔案

Rules會自動載入到每個對話中。我的11個rule檔案涵蓋：⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

大小教訓： 我的rules總共約180行，分布在11個檔案中。每一行都會載入到每個工作階段。我最初有超過400行，直到我將特定主題的內容遷移到Skills。180行的rule集合涵蓋了真正的不變量（安全性約束、git工作流程、修正規則）。其他一切都屬於Skills。

決策框架

遷移模式

我的.claude/結構經歷了三個階段的演進：

第1階段（第1-2個月）： 所有內容都放在Rules中。超過400行始終載入的上下文。iOS模式、FastAPI模式、設計指南、測試標準。每個工作階段的上下文都很臃腫。

第2階段（第3-4個月）： 將特定主題的內容遷移到Skills。Rules降至200行。Skills增長到20多個目錄。上下文膨脹減少了40%。

第3階段（第5個月以後）： 為需要隔離的任務（程式碼審查、安全性稽核）新增了Subagents。Commands穩定在85個用於明確的工作流程。隨著我增加領域專業知識，Skills增長到44個。⁷

經驗教訓：從Rules開始（成本低、始終可用），發現哪些是特定主題的內容（遷移到Skills），只在需要隔離時才新增Subagents。

Skills驅動Subagents

一個強大的模式：使用skills前置欄位將Skills注入Subagent上下文：

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

security和testing-philosophy skills將其內容注入subagent的系統提示中。審查者在其隔離的唯讀上下文中獲得專業知識。⁸

我的審查管線使用這種模式：三個subagents（correctness-reviewer、security-reviewer、conventions-reviewer）各自接收不同的skill注入。正確性審查者獲得debugging-philosophy。安全性審查者獲得安全性rule集合。慣例審查者獲得專案的編碼標準。

我的生產架構

~/.claude/
├── commands/     # 85 — User-triggered workflows
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Auto-invoked expertise
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Isolated task executors
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 files, ~180 lines — Always-on constraints
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Lifecycle event handlers
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

重點摘要

給獨立開發者： - 從Rules開始建立專案標準（總共保持在200行以下） - 為您最常用的技術棧新增Skills；自動啟動消除了「忘記調用」的問題 - 先為您最常見的三個工作流程建立Commands - 只在需要工具限制或上下文隔離時才新增Subagents

給團隊： - 在專案層級標準化Rules以確保團隊一致性 - 透過共用儲存庫分享Skills；Skills跨專案的可攜性是它們相對於專案層級配置的主要優勢

參考資料