一篇搞懂Claude Code Agents、Skills、Hooks 区别、场景、使用与完整案例

前言 🤖

很多开发者使用 Claude Code 做项目开发时，都会混淆三大扩展核心能力：Agents（代理）、Skills（技能包）、Hooks（生命周期钩子）。三者定位、触发逻辑、存储目录、适用场景完全不同，混用会导致上下文膨胀、自动化失效、任务边界混乱。

本文结合官方定义、Mermaid流程图、可直接复制的配置代码、终端命令、真实项目案例，一次性分清三者，覆盖前端/后端/全栈项目落地。

一、核心概念总览（类比团队角色快速理解）

模块	通俗类比	核心定位	触发方式	存储目录
Hooks	自动化安检/CI校验器	事件驱动强制回调，无自主思考，纯自动化拦截、校验、后置执行	生命周期事件自动触发（无需手动调用）	CLAUDE.md 顶层配置
Skills	可复用操作手册/工具脚本库	封装标准化流程、项目规范、工具指令，按需加载，轻量化上下文	手动 /命令 调用 / Claude智能匹配自动加载	.claude/skills/xxx/SKILL.md
Agents(SubAgent)	独立专项小组/专项工程师	拥有独立思考循环、隔离上下文、专属任务边界，可自主调用Skill、执行Hook	手动指派、Hook内自动拉起、主任务分流	.claude/agents/xxx/AGENT.md

二、三者完整工作流程 Mermaid 流程图

三、分模块深度解析：定义、特性、使用说明、代码案例

3.1 Hooks生命周期钩子 🛡️

1. 官方定义

Hooks 是绑定在Claude Code完整生命周期事件上的自动回调机制，只要对应事件发生就强制执行，不需要人工触发，用于强制规范、自动化校验、后置脚本、风险拦截。

2. 核心生命周期事件（常用）

• SessionStart：会话初始化时执行（加载项目全局环境变量）
• PreToolUse：调用工具/执行bash/写文件前拦截（风险命令校验）
• PostToolUse：工具执行完成后自动执行（格式化、lint、单测）
• Stop：整个任务结束后执行（生成变更日志、提交git）

3. 核心特性

1. 零上下文消耗，事件触发即运行，不会长期占用token；
2. 强制执行，无法跳过，适合团队强制规范；
3. 支持三种执行类型：command（终端命令）、prompt（LLM校验）、subagent（拉起子代理）。

4. 项目配置示例（CLAUDE.md，直接复制）

# CLAUDE.md 全局Hooks配置示例（TS/React前端项目）
hooks:
  # 1. 修改ts/tsx文件后自动格式化+eslint校验 PostToolUse事件
  PostToolUse:
    - matcher: Edit
      pattern: "*.{ts,tsx,js,jsx}"
      hooks:
        - type: command
          command: pnpm prettier --write "$CLAUDE_FILE_PATH"
          statusMessage: "🎨 自动格式化代码"
        - type: command
          command: pnpm eslint "$CLAUDE_FILE_PATH" --fix
          statusMessage: "🔍 ESLint自动修复"

  # 2. 执行bash命令前拦截危险操作 PreToolUse事件
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: prompt
          prompt: |
            检查待执行bash命令是否包含 rm -rf /、sudo rm、curl | sh 高危操作，
            如果存在，直接阻止执行并提示风险，禁止运行。

  # 3. 任务全部结束自动执行单元测试+生成changelog Stop事件
  Stop:
    - matcher: "*"
      hooks:
        - type: command
          command: pnpm test --short
          statusMessage: "🧪 运行项目单测"
        - type: command
          command: git log --oneline -n 10 > docs/CHANGELOG_TMP.md
          statusMessage: "📝 生成临时变更日志"

5. 适用场景

• 代码保存后自动格式化、Lint、类型检查；
• 拦截高危shell命令，防止误删文件；
• 任务完成自动跑测试、生成文档、提交Git；
• 会话启动自动读取项目环境、数据库配置。

3.2 Skills可复用技能包 📦

1. 官方定义

Skill 是存放在 .claude/skills/ 目录的标准化流程手册，封装一套固定工作流、项目规范、操作步骤，按需懒加载，只有调用时才注入上下文，大幅节省token消耗。

2. 核心特性

1. 懒加载：仅执行 /技能名 命令时加载完整指令，平时只缓存名称；
2. 可跨会话复用，一个项目可创建多个独立Skill；
3. 可被主Agent、SubAgent、Hook统一调用；
4. 目录规范：每个Skill独立文件夹，内置 SKILL.md 作为入口。

3. 完整项目目录结构

项目根目录/
└── .claude/
    └── skills/
        ├── code-review/          # 代码评审Skill
        │   └── SKILL.md
        ├── deploy-docker/        # Docker部署Skill
        │   └── SKILL.md
        └── db-migration/         # 数据库迁移Skill
            └── SKILL.md

4. Skill完整代码示例（docker部署技能 .claude/skills/deploy-docker/SKILL.md）

# Skill名称：deploy-docker
## 触发命令：/deploy
## 适用场景：Java后端Docker镜像打包+推送部署
## 执行流程（严格按顺序执行）
1. 校验根目录是否存在 Dockerfile、docker-compose.yml
2. 执行构建命令：**```docker build -t project-api:latest .```**
3. 本地启动测试容器：**```docker-compose up -d --test```**
4. 运行健康检测脚本：**```curl http://127.0.0.1:8080/health```**
5. 检测无报错则推送镜像到私有仓库，输出部署日志到 ./deploy/log.txt

## 强制约束
- 构建失败必须终止流程，输出错误堆栈
- 禁止跳过健康检测直接推送镜像
- 所有执行命令必须打印到控制台

5. 调用方式（终端/对话命令）

在Claude Code对话框直接输入：

/deploy

Agent会自动加载该Skill全部流程，严格按照文档步骤执行。

6. 适用场景

• 标准化部署流程（Docker、K8s、服务器发布）；
• 代码评审固定检查清单；
• 数据库迁移、SQL规范校验；
• 项目脚手架创建、接口文档自动生成；
• 企业内部统一代码规范、输出模板。

3.3 Agents(SubAgent)独立代理小组 👷

1. 官方定义

Agent / SubAgent 是拥有独立思考循环、隔离上下文的专项代理，相当于独立小AI，分配专属任务边界，可单独绑定专属Skills、私有Hook，和主Agent完全隔离token池，适合复杂任务拆分。

2. 核心特性

1. 独立上下文，子Agent执行不会污染主任务对话；
2. 专属权限：可限制仅操作指定目录、仅调用指定Skill；
3. 可被主任务手动创建，也可通过Hook自动拉起；
4. 目录规范：.claude/agents/xxx/AGENT.md 定义子代理能力边界。

3. SubAgent 完整配置示例（.claude/agents/db-schema/AGENT.md）

# SubAgent名称：db-schema
## 专属任务边界：仅处理 src/db/ 目录下表结构、SQL迁移
## 可用权限
1. 仅允许读写 src/db/、docs/sql/ 目录文件
2. 仅可调用技能：/db-migration（仅该Skill可用）
3. 禁止修改前端、接口业务代码

## 工作流程
1. 接收主Agent传入需求（新增数据表、修改字段、索引优化）
2. 读取项目数据库规范，生成PostgreSQL建表语句
3. 自动生成Mermaid ER关系图，写入docs/db-er.md
4. 执行校验：pytest sql-lint 检查SQL语法
5. 校验通过后返回SQL脚本给主Agent，附带变更说明

## 内部Hook（子代理私有，仅自身执行时生效）
PostToolUse:
  - 编辑sql文件后自动格式化 pgFormatter

4. 三种拉起SubAgent的方式

1. 手动指派（对话命令）

@db-schema 帮我设计用户订单关联表，输出完整SQL

2. Skill内部自动拉起
   在SKILL.md中添加指令：复杂库表设计时自动调用 @db-schema
3. Hook事件触发拉起
   在CLAUDE.md的Stop钩子中配置type: subagent，任务结束自动启动文档生成Agent

5. 适用场景

• 大型项目任务拆分：数据库、前端页面、接口开发、测试用例分不同代理；
• 隔离高危操作：数据删除、生产环境操作交给独立子Agent管控；
• 多角色协作：一个主Agent统筹，多个专项SubAgent并行处理不同模块；
• 超长复杂任务拆分，避免主上下文溢出。

四、三者核心差异对比表（避坑重点）

对比维度	Hooks	Skills	Agents(SubAgent)
运行逻辑	事件自动触发，无自主决策，纯执行脚本/校验	人工/智能匹配调用，按固定手册执行流程	独立LLM思考循环，自主规划分步执行
上下文占用	几乎无消耗，临时执行不缓存	调用时加载，执行完成释放token	完全隔离独立上下文，占用独立token预算
人工干预	无法手动触发，自动运行	需要输入 /xxx 命令调用	@代理名 手动指派，或自动拉起
存储位置	CLAUDE.md 全局配置	.claude/skills/ 独立目录	.claude/agents/ 独立目录
能否拆分任务	不能，仅做后置/前置操作	不能，只能执行固定标准化流程	可以，自主拆分多步骤复杂任务
依赖关系	可执行命令、拉起SubAgent	可执行命令、调用Hook、拉起SubAgent	可调用Skill、触发自身私有Hook
典型定位	强制规范、自动化安检	标准化工具流程手册	独立专项开发工程师

五、真实项目综合落地案例（全栈Java+TS项目）

需求背景

全栈项目，要求：

1. 修改代码自动格式化、Lint（Hook实现）
2. 一键Docker打包部署（Skill实现 /deploy）
3. 数据库表结构独立专人维护，隔离上下文（SubAgent db-schema）
4. 任务完成自动生成测试报告、变更日志（Hook Stop事件）

完整配套文件结构

项目根目录
├── CLAUDE.md          # 全局Hooks配置
├── .claude/
│   ├── skills/
│   │   ├── deploy-docker/SKILL.md
│   │   └── db-migration/SKILL.md
│   └── agents/
│       └── db-schema/AGENT.md
├── src/
│   ├── api/  # Java后端
│   └── web/  # TS前端
└── docker-compose.yml

完整操作命令链路

1. 需求：新增订单数据库表

@db-schema 设计订单表，包含用户关联、支付状态、创建索引

2. SubAgent自动加载 /db-migration Skill生成SQL，私有Hook自动格式化SQL文件
3. 主Agent拿到SQL后写入src/db/migrate目录，触发 PostToolUse Hook自动运行sql-lint
4. 开发完成后执行部署

/deploy

5. Skill执行Docker构建、健康检测，全部完成触发 Stop Hook：运行全量单元测试、生成CHANGELOG文档

六、常见踩坑避坑指南 ⚠️

1. 混淆Skill与Hook
   错误：把部署流程写进Hook；正确：Hook是自动校验，标准化流程必须用Skill，否则每次编辑文件都会执行构建，严重拖慢速度。
2. 复杂任务不用SubAgent
   大型数据库设计、全模块重构直接交给主Agent，会导致上下文溢出、逻辑混乱，拆分SubAgent隔离上下文。
3. Hook大量写入LLM Prompt
   PreToolUse等高频事件Hook尽量使用command执行终端脚本，prompt类型会频繁消耗token。
4. Skill内写动态逻辑
   Skill仅适合固定标准化流程，需要自主思考、多分支判断的工作交给SubAgent。

七、快速选型决策口诀（开发时快速判断用哪个）

• 只要自动触发、强制校验 → 选 Hooks
• 固定标准化操作、一键执行流程（部署/评审/迁移）→ 选 Skills
• 复杂独立专项任务、需要隔离上下文、自主分步思考 → 选 Agents(SubAgent)