一篇搞懂Claude Code Agents、Skills、Hooks 区别、场景、使用与完整案例前言 很多开发者使用Claude Code做项目开发时都会混淆三大扩展核心能力Agents代理、Skills技能包、Hooks生命周期钩子。三者定位、触发逻辑、存储目录、适用场景完全不同混用会导致上下文膨胀、自动化失效、任务边界混乱。本文结合官方定义、Mermaid流程图、可直接复制的配置代码、终端命令、真实项目案例一次性分清三者覆盖前端/后端/全栈项目落地。一、核心概念总览类比团队角色快速理解模块通俗类比核心定位触发方式存储目录Hooks自动化安检/CI校验器事件驱动强制回调无自主思考纯自动化拦截、校验、后置执行生命周期事件自动触发无需手动调用CLAUDE.md顶层配置Skills可复用操作手册/工具脚本库封装标准化流程、项目规范、工具指令按需加载轻量化上下文手动/命令调用 / Claude智能匹配自动加载.claude/skills/xxx/SKILL.mdAgents(SubAgent)独立专项小组/专项工程师拥有独立思考循环、隔离上下文、专属任务边界可自主调用Skill、执行Hook手动指派、Hook内自动拉起、主任务分流.claude/agents/xxx/AGENT.md二、三者完整工作流程 Mermaid 流程图PreToolUse/Edit/Write等事件无事件触发是输入/匹配/执行 /xxx 命令否是否用户发起项目任务主Agent启动独立思考循环读取CLAUDE.md全局Hooks规则触发生命周期事件?执行对应Hook命令/校验/拦截/通知主Agent分析任务匹配可用SkillsHook执行完成回到主流程是否需要执行标准化流程?加载对应Skill注入上下文执行标准化步骤主Agent直接编写代码、调用工具任务复杂度高需拆分专项工作?拉起独立SubAgent隔离上下文分配专属Skill权限SubAgent内部执行自有Hook、调用专属SkillsSubAgent完成返回结果给主Agent主Agent修改文件、执行脚本触发PostToolUse/Stop后置Hook自动lint、测试、文档更新任务闭环输出交付结果三、分模块深度解析定义、特性、使用说明、代码案例3.1Hooks生命周期钩子 ️1. 官方定义Hooks是绑定在Claude Code完整生命周期事件上的自动回调机制只要对应事件发生就强制执行不需要人工触发用于强制规范、自动化校验、后置脚本、风险拦截。2. 核心生命周期事件常用SessionStart会话初始化时执行加载项目全局环境变量PreToolUse调用工具/执行bash/写文件前拦截风险命令校验PostToolUse工具执行完成后自动执行格式化、lint、单测Stop整个任务结束后执行生成变更日志、提交git3. 核心特性零上下文消耗事件触发即运行不会长期占用token强制执行无法跳过适合团队强制规范支持三种执行类型command终端命令、promptLLM校验、subagent拉起子代理。4. 项目配置示例CLAUDE.md直接复制# CLAUDE.md 全局Hooks配置示例TS/React前端项目hooks:# 1. 修改ts/tsx文件后自动格式化eslint校验 PostToolUse事件PostToolUse:-matcher:Editpattern:*.{ts,tsx,js,jsx}hooks:-type:commandcommand:pnpm prettier--write $CLAUDE_FILE_PATHstatusMessage: 自动格式化代码-type:commandcommand:pnpm eslint $CLAUDE_FILE_PATH--fixstatusMessage: ESLint自动修复# 2. 执行bash命令前拦截危险操作 PreToolUse事件PreToolUse:-matcher:Bashhooks:-type:promptprompt:|检查待执行bash命令是否包含 rm -rf /、sudo rm、curl | sh 高危操作 如果存在直接阻止执行并提示风险禁止运行。# 3. 任务全部结束自动执行单元测试生成changelog Stop事件Stop:-matcher:*hooks:-type:commandcommand:pnpm test--shortstatusMessage: 运行项目单测-type:commandcommand:git log--oneline-n 10docs/CHANGELOG_TMP.mdstatusMessage: 生成临时变更日志5. 适用场景代码保存后自动格式化、Lint、类型检查拦截高危shell命令防止误删文件任务完成自动跑测试、生成文档、提交Git会话启动自动读取项目环境、数据库配置。3.2Skills可复用技能包 1. 官方定义Skill是存放在.claude/skills/目录的标准化流程手册封装一套固定工作流、项目规范、操作步骤按需懒加载只有调用时才注入上下文大幅节省token消耗。2. 核心特性懒加载仅执行/技能名命令时加载完整指令平时只缓存名称可跨会话复用一个项目可创建多个独立Skill可被主Agent、SubAgent、Hook统一调用目录规范每个Skill独立文件夹内置SKILL.md作为入口。3. 完整项目目录结构项目根目录/ └── .claude/ └── skills/ ├── code-review/ # 代码评审Skill │ └── SKILL.md ├── deploy-docker/ # Docker部署Skill │ └── SKILL.md └── db-migration/ # 数据库迁移Skill └── SKILL.md4. 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对话框直接输入/deployAgent会自动加载该Skill全部流程严格按照文档步骤执行。6. 适用场景标准化部署流程Docker、K8s、服务器发布代码评审固定检查清单数据库迁移、SQL规范校验项目脚手架创建、接口文档自动生成企业内部统一代码规范、输出模板。3.3Agents(SubAgent)独立代理小组 1. 官方定义Agent / SubAgent是拥有独立思考循环、隔离上下文的专项代理相当于独立小AI分配专属任务边界可单独绑定专属Skills、私有Hook和主Agent完全隔离token池适合复杂任务拆分。2. 核心特性独立上下文子Agent执行不会污染主任务对话专属权限可限制仅操作指定目录、仅调用指定Skill可被主任务手动创建也可通过Hook自动拉起目录规范.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文件后自动格式化 pgFormatter4. 三种拉起SubAgent的方式手动指派对话命令db-schema 帮我设计用户订单关联表输出完整SQLSkill内部自动拉起在SKILL.md中添加指令复杂库表设计时自动调用 db-schemaHook事件触发拉起在CLAUDE.md的Stop钩子中配置type: subagent任务结束自动启动文档生成Agent5. 适用场景大型项目任务拆分数据库、前端页面、接口开发、测试用例分不同代理隔离高危操作数据删除、生产环境操作交给独立子Agent管控多角色协作一个主Agent统筹多个专项SubAgent并行处理不同模块超长复杂任务拆分避免主上下文溢出。四、三者核心差异对比表避坑重点对比维度HooksSkillsAgents(SubAgent)运行逻辑事件自动触发无自主决策纯执行脚本/校验人工/智能匹配调用按固定手册执行流程独立LLM思考循环自主规划分步执行上下文占用几乎无消耗临时执行不缓存调用时加载执行完成释放token完全隔离独立上下文占用独立token预算人工干预无法手动触发自动运行需要输入/xxx命令调用代理名 手动指派或自动拉起存储位置CLAUDE.md 全局配置.claude/skills/ 独立目录.claude/agents/ 独立目录能否拆分任务不能仅做后置/前置操作不能只能执行固定标准化流程可以自主拆分多步骤复杂任务依赖关系可执行命令、拉起SubAgent可执行命令、调用Hook、拉起SubAgent可调用Skill、触发自身私有Hook典型定位强制规范、自动化安检标准化工具流程手册独立专项开发工程师五、真实项目综合落地案例全栈JavaTS项目需求背景全栈项目要求修改代码自动格式化、LintHook实现一键Docker打包部署Skill实现 /deploy数据库表结构独立专人维护隔离上下文SubAgent db-schema任务完成自动生成测试报告、变更日志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完整操作命令链路需求新增订单数据库表db-schema 设计订单表包含用户关联、支付状态、创建索引SubAgent自动加载 /db-migration Skill生成SQL私有Hook自动格式化SQL文件主Agent拿到SQL后写入src/db/migrate目录触发PostToolUseHook自动运行sql-lint开发完成后执行部署/deploySkill执行Docker构建、健康检测全部完成触发StopHook运行全量单元测试、生成CHANGELOG文档六、常见踩坑避坑指南 ⚠️混淆Skill与Hook错误把部署流程写进Hook正确Hook是自动校验标准化流程必须用Skill否则每次编辑文件都会执行构建严重拖慢速度。复杂任务不用SubAgent大型数据库设计、全模块重构直接交给主Agent会导致上下文溢出、逻辑混乱拆分SubAgent隔离上下文。Hook大量写入LLM PromptPreToolUse等高频事件Hook尽量使用command执行终端脚本prompt类型会频繁消耗token。Skill内写动态逻辑Skill仅适合固定标准化流程需要自主思考、多分支判断的工作交给SubAgent。七、快速选型决策口诀开发时快速判断用哪个只要自动触发、强制校验→ 选Hooks固定标准化操作、一键执行流程部署/评审/迁移→ 选Skills复杂独立专项任务、需要隔离上下文、自主分步思考 → 选Agents(SubAgent)