Claude Code 扩展三件套官方规范：Subagents / Hooks / Plugins

来源：Claude 官方文档（code.claude.com）提炼日期：2026-05-18 分类：AI 方法论文档链接：
Subagents: https://code.claude.com/docs/en/sub-agents
Hooks Guide: https://code.claude.com/docs/en/hooks-guide
Plugins: https://code.claude.com/docs/en/plugins

TL;DR

Subagent、Hooks、Plugin 是 Claude Code 在 Skill/Command 之上的三层扩展能力：Subagent 是带独立上下文窗口的专业化助手（解决"主对话不被污染"），Hooks 是生命周期事件的 Shell 命令（解决"必须发生的事不能忘"），Plugin 是把上述所有能力打包分发的容器（解决"团队和社区怎么共享"）。三者解决的是不同抽象层级的问题，组合使用才能构建完整工作流。

核心观点

1. Subagent 的核心价值是上下文隔离，而非"另一个模型"

每个 Subagent 在自己的上下文窗口工作，结束后只把结果返回主对话。这让"代码审查"、"运行测试"、"批量重构"这类会产生大量中间输出的任务不会污染主上下文，主线程可以保持在高级目标层面。这与 model 维度的差异（用 Sonnet 还是 Opus）是两回事。

2. Plugin = 把零散配置打包成可分发的产品

如果只是个人项目，直接放 .claude/ 目录最便捷；要团队共享、要版本号、要避免命名冲突，就要用 Plugin。Plugin 的价值不在于功能更强，而在于具备产品化属性：命名空间、语义化版本、Marketplace 分发。

3. Plugin 自动扫描，不要在 plugin.json 中显式声明子目录

commands/、agents/、skills/ 是 Claude Code 自动扫描的——在 plugin.json 中加 "commands": "./commands/" 这类字段反而会导致清单验证失败。repository 字段必须是字符串而非对象。这是实战中最容易踩坑的点。

关键知识点

三件套对比

维度	Subagent	Hooks	Plugin
定义	专业化的 AI 助手	生命周期事件的 Shell 命令	可分享的功能扩展包
触发方式	Claude 自动委托或手动调用	特定事件自动触发	安装后自动可用
配置位置	`.claude/agents/` 或 `~/.claude/agents/`	`settings.json`	`.claude-plugin/plugin.json`
用途	任务隔离、专业领域处理	自动化操作、确定性控制	打包分享功能

Subagents（子代理）

官方定义

Subagents are pre-configured AI personalities that Claude Code can delegate tasks to. They enable more efficient problem-solving by providing task-specific configurations with customized system prompts, tools and a separate context window.

每个 Subagent：

有特定的目的和专业领域
使用独立于主对话的上下文窗口
可配置允许使用的工具
包含指导行为的自定义系统提示

四大优势

优势	说明
Context preservation（上下文保留）	每个 Subagent 在自己的上下文中工作，防止污染主对话
Specialized expertise（专业化）	可针对特定领域调优指令，提高指定任务的成功率
Reusability（可复用）	一次创建，跨不同项目使用，可与团队共享
Flexible permissions（灵活权限）	每个 Subagent 可有不同工具访问级别

存放位置与优先级

类型	路径	范围	优先级
项目级	`.claude/agents/`	当前项目可用	最高
用户级	`~/.claude/agents/`	所有项目可用	较低
CLI 定义	`--agents` JSON 参数	当前会话	中等
插件提供	Plugin 的 `agents/` 目录	安装插件的用户	-

名称冲突时项目级优先。

文件格式

markdown

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3    # 可选 - 不填则继承主线程所有工具
model: sonnet                  # 可选 - 模型别名或 'inherit'
permissionMode: default        # 可选 - 权限模式
skills: skill1, skill2         # 可选 - 自动加载的 Skills
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

配置字段说明

字段	必填	说明
`name`	是	唯一标识符，使用小写字母和连字符
`description`	是	Subagent 用途的自然语言描述
`tools`	否	逗号分隔的工具列表。省略则继承主线程所有工具
`model`	否	模型别名（sonnet/opus/haiku）或 'inherit' 使用主对话模型
`permissionMode`	否	default / acceptEdits / bypassPermissions / plan / ignore
`skills`	否	逗号分隔的 Skill 名称，Subagent 启动时自动加载。Subagent 不继承父对话的 Skills

CLI 临时定义方式

bash

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

使用方式

bash

/agents                                                # 打开 Subagent 管理界面
> Use the code-reviewer subagent to check my recent changes  # 显式调用

Hooks（钩子）

官方定义

Claude Code hooks are user-defined shell commands that execute at various points in Claude Code's lifecycle. Hooks provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them.

核心价值：把建议（CLAUDE.md 自然语言指令）转变为应用级代码，每次预期运行时都会执行。

可用事件

事件	触发时机	能力
`PreToolUse`	工具调用前	可阻止工具调用
`PermissionRequest`	显示权限对话框时	可允许或拒绝
`PostToolUse`	工具调用后	-
`UserPromptSubmit`	用户提交提示后、Claude 处理前	-
`Notification`	Claude Code 发送通知时	-
`Stop`	Claude Code 完成响应时	-
`SubagentStop`	Subagent 任务完成时	-
`PreCompact`	压缩操作前	-
`SessionStart`	新会话开始或恢复时	-
`SessionEnd`	会话结束时	-

配置示例

自动格式化 TypeScript（PostToolUse）：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

安全提示

你必须在添加 Hooks 时考虑安全影响，因为 Hooks 在代理循环中使用当前环境的凭据自动运行。例如，恶意 Hooks 代码可能泄露你的数据。始终在注册前审查你的 Hooks 实现。

Plugins（插件）

官方定义

Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.

何时用 Plugin vs 独立配置

方式	命令名称	适用场景
独立配置 (`.claude/`)	`/hello`	个人工作流、项目特定定制、快速实验
Plugin（含 `.claude-plugin/plugin.json`）	`/plugin-name:hello`	团队分享、社区分发、版本发布、跨项目复用

用独立配置当：单个项目自定义、配置不需分享、想要短命令名。 用 Plugin 当：想团队/社区分享、跨项目复用、想要版本控制、Marketplace 分发。

标准目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 必需：插件清单
├── commands/             # 可选：斜杠命令
│   └── hello.md
├── agents/               # 可选：Subagents
│   └── reviewer.md
├── skills/               # 可选：Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks.json            # 可选：Hooks 配置
└── mcp-servers/          # 可选：MCP 服务器

plugin.json 字段规范

json

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "homepage": "https://github.com/...",
  "repository": "https://github.com/...",
  "license": "MIT"
}

字段	必填	类型	说明
`name`	是	string	唯一标识符，作为命令命名空间前缀
`description`	是	string	在插件管理器中浏览或安装时显示
`version`	是	string	语义化版本
`author`	是	object	作者信息
`homepage`	否	string	主页 URL
`repository`	否	string	仓库 URL（必须字符串，不能用对象格式）
`license`	否	string	许可证类型

易错点

commands/、agents/、skills/ 由 Claude Code 自动扫描，不要在 plugin.json 中显式声明：

json

// 错误：这些字段会导致清单验证失败
{
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": "./skills/"
}

// 错误：repository 不能是对象
{
  "repository": { "type": "git", "url": "..." }
}

使用方式

bash

claude --plugin-dir ./my-plugin   # 测试插件（开发时）
/plugin                            # 管理已安装插件
/my-plugin:hello                   # 使用插件命令

Plugin 包含的组件

Slash Commands：commands/ 目录中的 Markdown 文件
Agents：agents/ 目录中的 Subagent 定义
Skills：skills/ 目录中的 SKILL.md 文件
Hooks：hooks.json 配置文件
MCP Servers：MCP 服务器连接

三件套关系

┌─────────────────────────────────────────────────────────┐
│                      Plugins                             │
│        (可分享的功能扩展包，包含以下组件)                  │
└───────────────────────┬─────────────────────────────────┘
                        │ 包含
         ┌──────────────┼──────────────┬──────────────┐
         ▼              ▼              ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  Commands   │ │  Subagents  │ │   Skills    │ │    Hooks    │
│ (快捷命令)   │ │ (专业助手)   │ │ (知识能力)   │ │ (生命周期)   │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘

选择指南

需求	使用
隔离上下文处理特定任务	Subagent
在特定事件时自动执行操作	Hooks
分享功能给团队/社区	Plugin
给 Claude 专业知识（自动触发）	Skill
快捷触发工作流（手动触发）	Command

组合使用：团队代码审查工作流

Plugin 打包所有功能
Subagent code-reviewer：专门的代码审查 AI 助手
Skill coding-standards：团队编码标准知识
Command /review：快速触发审查
Hooks PostToolUse：审查后自动格式化代码

启发与思考

Subagent 的"独立上下文"是工程视角下最被低估的能力：日常使用 Claude Code 处理大型重构时，最大瓶颈是上下文被搜索结果、错误日志填满。把"批量搜索"、"批量改代码"、"跑测试"这种容易爆量的步骤拆给 Subagent，主线程才能保持清醒。
Plugin 是 Skill/Command/Agent 的"产品化外壳"：从 PM 视角，独立配置 → Plugin 的演化路径，等价于"个人脚本 → 共享工具 → 平台产品"。一旦想清楚"谁在用、要不要版本号、要不要更新通道"，就该转 Plugin 形态。
Hooks 是"AI 不能信任时的最后一道防线"：当某条规则的执行成本远低于忘记的代价（自动格式化、提交前测试、敏感文件防护），用 Hooks 锁死比依赖 LLM 自觉更稳。

原文精华

Subagents are pre-configured AI personalities that Claude Code can delegate tasks to.

Hooks provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them.

Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams.

原文链接：

claude-code

hermes

Claude Code 扩展三件套官方规范：Subagents / Hooks / Plugins

TL;DR

核心观点

关键知识点

三件套对比

Subagents（子代理）

官方定义

四大优势

存放位置与优先级

文件格式

配置字段说明

CLI 临时定义方式

使用方式

Hooks（钩子）

官方定义

可用事件

配置示例

安全提示

Plugins（插件）

官方定义

何时用 Plugin vs 独立配置

标准目录结构

plugin.json 字段规范

易错点

使用方式

Plugin 包含的组件

三件套关系

选择指南

组合使用：团队代码审查工作流

启发与思考

原文精华

Claude Code 扩展三件套官方规范：Subagents / Hooks / Plugins ​

TL;DR ​

核心观点 ​

关键知识点 ​

三件套对比 ​

Subagents（子代理） ​

官方定义 ​

四大优势 ​

存放位置与优先级 ​

文件格式 ​

配置字段说明 ​

CLI 临时定义方式 ​

使用方式 ​

Hooks（钩子） ​

官方定义 ​

可用事件 ​

配置示例 ​

安全提示 ​

Plugins（插件） ​

官方定义 ​

何时用 Plugin vs 独立配置 ​

标准目录结构 ​

plugin.json 字段规范 ​

易错点 ​

使用方式 ​

Plugin 包含的组件 ​

三件套关系 ​

选择指南 ​

组合使用：团队代码审查工作流 ​

启发与思考 ​

原文精华 ​

Claude Code 扩展三件套官方规范：Subagents / Hooks / Plugins

TL;DR

核心观点

关键知识点

三件套对比

Subagents（子代理）

官方定义

四大优势

存放位置与优先级

文件格式

配置字段说明

CLI 临时定义方式

使用方式

Hooks（钩子）

官方定义

可用事件

配置示例

安全提示

Plugins（插件）

官方定义

何时用 Plugin vs 独立配置

标准目录结构

plugin.json 字段规范

易错点

使用方式

Plugin 包含的组件

三件套关系

选择指南

组合使用：团队代码审查工作流

启发与思考

原文精华