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（启动代码审查agents）、/deploy（部署检查清单）、/publish-check（博客发布前验证）和/deliberate（多agent研究）。

我犯过的错误： 我把/fastapi构建为一个command，用于按需注入FastAPI模式。问题在于：我有一半的时间忘记输入它。每次忘记调用，agent就会遗漏我希望强制执行的模式。解决方案是将/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、设计原则 - 多agent（3个）：deliberation、review、内容创作 - 项目专属（4个）：个人网站内容、ResumeGeni博客、Obsidian capture

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-2个月）： 所有内容都放在Rules中。400多行始终加载的上下文。iOS模式、FastAPI模式、设计指南、测试标准。每个会话的上下文都很臃肿。

第二阶段（第3-4个月）： 将特定主题的内容迁移到Skills。Rules缩减至200行。Skills增长到20多个目录。上下文膨胀减少了40%。

第三阶段（第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。安全审查者获得安全规则集。规范审查者获得项目的编码标准。

我的生产架构

~/.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跨项目的可移植性是其相对于项目级配置的主要优势

参考文献