Claude Code 架构深度解析：Commands、Skills、Agents、Plugins 一文说清

TL;DR

你可能听说过 Claude Code 的 Commands、Skills、Agents、Plugins，但搞不清它们到底有啥区别？

简单说：
– Commands = 你按的按钮（手动触发）
– Skills = AI 自己判断要不要用（自动激活）
– Agents = 独立的小助手（隔离上下文）
– Plugins = 打包好的工具箱（分发容器）

这篇文章用人话讲清楚它们的本质区别，看完你就知道该用哪个了。

一、Commands：你说了算的快捷键

什么是 Commands？

Commands 就是斜杠命令，你在终端输入 /review，Claude 就去审查代码。主动权在你手里，不输入就不执行。

怎么创建？

在项目的 .claude/commands/ 目录下扔个 Markdown 文件就行。

文件名决定命令：analyze.md → /analyze

文件内容就是提示词：

---
description: Review the current code for security vulnerabilities
---

Please review the code in the current context for security vulnerabilities.
Focus specifically on:
1. SQL injection risks
2. XSS vulnerabilities
3. Hardcoded secrets

If you find issues, please suggest specific fixes.

支持参数吗？

当然支持。用 $1, $2 或 $ARGUMENTS 接收用户输入。

---
description: Run tests for a specific module
---

Run all tests for the $1 module and report any failures.

使用：/test auth → 测试 auth 模块

全局 vs 项目级

• 全局命令：~/.claude/commands/security-review.md（所有项目可用）
• 项目命令：.claude/commands/security-review.md（仅当前项目）

适用场景

Commands 适合高频、确定性任务：

• 代码审查：/review
• 生成 commit 信息：/commit
• 格式化代码：/fmt
• 运行测试：/test

你很清楚什么时候需要它，不需要 Claude 废话，直接执行就完事了。

二、Skills：AI 自己会判断的技能包

什么是 Skills？

Skills 是按需加载的能力模块。你不用显式调用，Claude 会根据对话内容自己判断要不要激活。

就像给 Claude 配了一堆工具书，它需要的时候自己翻。

核心机制：懒加载

这是 Skills 最聪明的地方：

1. 启动时：只加载元数据（名称 + 描述），不占用太多 token
2. 需要时：Claude 判断”这个任务需要 PDF 技能”，才读取完整的 SKILL.md
3. 用完后：技能内容可以从上下文中释放

这种设计让 Claude 能装备几十个技能，但不会把上下文撑爆。

怎么创建？

Skills 是一个目录，核心文件是 SKILL.md：

skills/pdf-skill/
├── SKILL.md          # 告诉 Claude 如何使用这个技能
├── extract.py        # 实际执行的脚本
└── README.md         # 说明文档

SKILL.md 示例：

---
name: pdf-processing
description: Extract data from PDF forms and documents
---

When the user asks to extract data from a PDF:
1. Run the extract.py script in this directory
2. Do not try to read PDF raw bytes directly
3. Interpret the JSON output from the script
4. Present the data in a readable format

使用体验

用户无需显式调用，只需说：

“帮我读一下 contract.pdf 里的签约日期”

Claude 会自动：
1. 识别这是 PDF 处理任务
2. 激活 PDF Skill
3. 运行 extract.py
4. 解析输出并回答

适用场景

Skills 适合模糊指令、智能化任务：

• PDF 处理：用户说”读这个文件”，Claude 自己判断是 PDF
• 代码翻译：用户说”让代码容易读点”，Claude 自动调用翻译技能
• 数据分析：用户说”分析下这个表格”，Claude 激活数据分析技能

你希望 Claude 像助手一样自动判断该做什么，而不是每次都手动指定。

三、Agents：独立工作的分身

什么是 Agents？

Agent 是拥有独立上下文和专属系统提示词的 Claude 实例。

就像主 Claude 把任务转包给了坐在旁边的”数据库专家”，这个专家有自己的记忆和设定。

核心优势：上下文隔离

这是 Agent 最大的价值：

没有 Agent 的情况：

你：帮我翻译这 100 个文件
Claude：好的
[翻译过程刷屏 10000 行]
你：刚才我们聊的那个 bug 怎么解决？
Claude：啥 bug？我上下文被翻译内容挤爆了...

有 Agent 的情况：

你：帮我翻译这 100 个文件
主 Claude：我启动 TranslatorAgent 处理
[子 Agent 独立工作，不污染主对话]
子 Agent：翻译完成，汇总报告已生成
主 Claude：翻译完了，报告在这里
你：刚才那个 bug 怎么解决？
主 Claude：记得，是 auth 模块的问题...

怎么创建？

交互式创建：

# 在 Claude Code 中输入
/agents
# 选择 "Create new agent"

配置定义（概念性描述）：

name: code-reviewer
role: 资深代码审查专家
description: 通过严格标准审查代码变更，只关注质量、可读性和潜在 bug
tools: [Read]  # 只读权限，防止意外修改
system_prompt: |
  你是一位资深的代码审查专家。
  你只提供建议，不直接写代码。
  重点关注：
  1. 代码质量和可读性
  2. 潜在的 bug 和边界情况
  3. 性能问题

使用方式

主 Claude 会根据任务自动调用，或者你显式指派：

你：让 code-reviewer 检查我最新的改动
主 Claude：好的，我让审查专家看看
[启动 code-reviewer Agent]
code-reviewer：发现 3 个问题...
主 Claude：审查完成，这是建议清单

适用场景

Agents 适合复杂、耗时、多步骤任务：

• 代码审查：独立分析，不污染主对话
• 安全审计：专注安全问题，隔离敏感信息
• 批量处理：翻译几百个文件，只返回汇总
• 深度调研：爬取大量文档，提炼关键信息

防止复杂任务的中间过程刷屏，导致之前的对话记忆被挤掉。

四、Plugins：打包好的工具箱

什么是 Plugins？

Plugin 不是功能本身，而是分发容器。

就像水果篮：Command 是苹果，Skill 是橙子，Agent 是香蕉，Plugin 是装它们的篮子。

为什么需要 Plugins？

假设你做了一套代码审查工具：
– /review 命令：快速审查
– code-quality Skill：自动检测代码质量
– security-auditor Agent：深度安全审计

你想分享给同事，难道要他们手动复制 3 个文件到 3 个目录？

用 Plugin 打包：

my-code-review-plugin/
├── commands/
│   └── review.md
├── skills/
│   └── code-quality/
│       └── SKILL.md
└── agents/
    └── security-auditor.yaml

同事只需：

claude plugin install my-code-review-plugin

所有功能一次性装好。

Plugin 的价值

1. 统一分发：一个命令安装所有功能
2. 版本管理：统一更新，不会漏掉某个组件
3. 团队协作：确保所有人用同样的工具链
4. 生态共享：发布到 Anthropic 官方插件市场

官方插件市场

Anthropic 提供了官方插件仓库，你可以：
– 浏览社区插件
– 一键安装常用工具
– 发布自己的插件

五、三者的本质区别

最容易混淆：Command vs Skill

它们都能封装提示词或脚本，但控制权不同：

例子：你写了个代码格式化脚本 format_code.py

• 做成 Command：每次必须手动输入 /fmt 才运行
• 做成 Skill：你说”这代码太乱了”，Claude 自动运行脚本

逻辑重叠：Agent vs Skill

都能让 Claude 变专业，但上下文是否独立：

例子：SQL 查询优化

• Skill：给当前 Claude 一本《SQL 手册》，它现学现卖，但还是同一个 Claude
• Agent：转包给”数据库专家”，专家有自己的记忆和设定，处理完只返回结果

六、决策树：我该用哪个？

面对一个需求，到底该用 Command、Skill 还是 Agent？用这个决策树：

┌─────────────────────────────────┐
│  这个功能需要手动精确触发吗？  │
└────────────┬────────────────────┘
             │
      ┌──────┴──────┐
      │ 是          │ 否
      ▼             ▼
  Command      ┌─────────────────────────────┐
  (/foo)       │ 任务复杂，会污染主对话吗？ │
               └──────────┬──────────────────┘
                          │
                   ┌──────┴──────┐
                   │ 是          │ 否
                   ▼             ▼
                 Agent         Skill
              (独立分身)    (工具书)

实战案例 1：代码翻译成文档

需求：将代码翻译成中文文档

方案 A – Command：

# .claude/commands/trans.md
---
description: Translate code to Chinese documentation
---
Translate $1 to Chinese documentation with examples.

使用：/trans file.py

适用场景：你很清楚什么时候需要翻译，高频使用

方案 B – Skill：

# skills/translation/SKILL.md
---
name: code-translator
description: Translate code to readable Chinese documentation
---
When user says "make this easier to read" or "document this":
1. Analyze code structure
2. Generate Chinese documentation
3. Add usage examples

使用：你说”帮我把这文件弄得容易读一点”

适用场景：模糊指令，希望 Claude 自动判断

方案 C – Agent：

name: translator-agent
role: 技术文档翻译专家
tools: [Read, Write]
system_prompt: |
  你专注于将代码翻译成高质量中文文档。
  处理大量文件时，只返回汇总报告。

使用：你说”翻译整个项目的代码”

适用场景：批量处理几百个文件，防止刷屏

实战案例 2：安全审计

需求：检查代码安全漏洞

方案对比：

实战案例 3：测试覆盖率

需求：检查测试覆盖率

Command 方案：

/coverage auth
# 立即检查 auth 模块的测试覆盖率

Skill 方案：

你：这个模块测试够不够？
Claude：[激活 test-coverage Skill]
Claude：当前覆盖率 65%，建议补充边界测试

Agent 方案：

你：分析整个项目的测试质量
主 Claude：启动 test-analyzer Agent
[Agent 独立分析几百个文件]
Agent：生成测试质量报告，发现 12 个未覆盖的关键路径

七、Subagent 架构深度解析

什么是 Subagent？

Subagent 是 Agent 的底层实现机制，理解它能让你更好地设计 Agent。

核心原理：
– 独立上下文窗口：每个 Subagent 有自己的 context window
– 专属系统提示词：定制化的 system prompt
– 可配置工具集：只给必要的工具权限
– 并行执行能力：多个 Subagent 同时工作

Orchestrator-Worker 模式

Claude Code 的 Agent 系统采用”编排者-工人”模式：

主 Claude (Orchestrator)
    ├─ 规划任务
    ├─ 分配工作
    └─ 汇总结果
         │
         ├─→ Subagent A (Code Reviewer)
         │      └─ 独立上下文，只读权限
         │
         ├─→ Subagent B (Test Engineer)
         │      └─ 独立上下文，读写权限
         │
         └─→ Subagent C (Security Auditor)
                └─ 独立上下文，只读权限

Token 效率优化

Subagent 的最大价值是防止上下文污染：

没有 Subagent：

主对话上下文：
- 你的问题 (100 tokens)
- 代码审查过程 (5000 tokens)
- 测试分析过程 (5000 tokens)
- 安全审计过程 (5000 tokens)
总计：15100 tokens，主对话记忆被挤爆

有 Subagent：

主对话上下文：
- 你的问题 (100 tokens)
- Subagent A 汇总 (200 tokens)
- Subagent B 汇总 (200 tokens)
- Subagent C 汇总 (200 tokens)
总计：700 tokens，主对话记忆完整保留

设计 Subagent 的最佳实践

1. 明确职责边界

# 好的设计
name: security-auditor
responsibility: 只检查安全漏洞，不修复代码

# 坏的设计
name: code-helper
responsibility: 审查、修复、测试、文档...（职责过多）

2. 最小权限原则

# 审查类 Agent：只读
tools: [Read, Grep, Glob]

# 修复类 Agent：读写
tools: [Read, Write, Edit, Bash]

3. 清晰的输出格式

system_prompt: |
  审查完成后，必须返回 JSON 格式：
  {
    "issues": [...],
    "severity": "high|medium|low",
    "recommendations": [...]
  }

八、常见误区与避坑指南

误区 1：Command 能做的就不用 Skill

错误想法：Command 更简单，能用 Command 就别用 Skill

真相：Command 需要用户记住命令名，Skill 是自然语言触发

场景：PDF 处理
– Command：用户必须记住 /pdf-extract contract.pdf
– Skill：用户说”读一下这个合同”，Claude 自动识别并处理

结论：高频、确定性任务用 Command，模糊指令用 Skill

误区 2：Agent 比 Skill 高级

错误想法：Agent 更复杂，所以更强大

真相：Agent 是为了隔离上下文，不是为了”更强”

场景：单次代码审查
– Skill：够用，审查结果直接在主对话里
– Agent：过度设计，启动 Agent 反而增加开销

结论：单次任务用 Skill，批量/复杂任务用 Agent

误区 3：Plugin 只是打包工具

错误想法：Plugin 就是把文件打包在一起

真相：Plugin 是生态系统的基础设施

Plugin 的真正价值：
– 版本管理：统一更新所有组件
– 依赖管理：自动安装必要的依赖
– 配置管理：统一的配置文件
– 团队协作：确保所有人用同样的工具链

误区 4：Skill 的懒加载不重要

错误想法：反正最后都要加载，懒加载没啥用

真相：懒加载是 Skill 系统的核心设计

场景：你装了 50 个 Skill
– 没有懒加载：启动时加载 50 个 SKILL.md，消耗 10000+ tokens
– 有懒加载：启动时只加载 50 个元数据，消耗 500 tokens

结论：懒加载让你能装备大量 Skill，而不会撑爆上下文

九、快速参考表

功能对比矩阵

选择决策表

十、总结

核心要点

1. Command = 按钮：你说了算，手动触发，高频确定性任务
2. Skill = 工具书：AI 自己判断，懒加载，模糊指令智能化
3. Agent = 分身：独立上下文，批量复杂任务，防止刷屏
4. Plugin = 工具箱：打包分发，版本管理，团队协作

设计原则

• 简单优先：能用 Command 就别用 Skill，能用 Skill 就别用 Agent
• 职责单一：每个 Agent 只做一件事，做好一件事
• 最小权限：只给必要的工具权限，防止意外修改
• 上下文隔离：复杂任务用 Agent，保护主对话记忆

下一步

现在你已经理解了 Claude Code 的架构，可以：

1. 创建第一个 Command：把高频操作封装成斜杠命令
2. 尝试 Skill：让 Claude 自动识别你的需求
3. 设计 Agent：处理复杂的批量任务
4. 打包 Plugin：分享给团队使用

没了。

参考资料

• Claude Code Official Documentation
• Anthropic Engineering Blog
• Claude Code Skills System
• Anthropic Academy – Claude Code Course
• Claude Code Plugins Repository