【Claude Code】Agents、Skills、Hooks 到底怎么选？一篇搞懂区别、场景与完整配置案例

1. 先搞清楚你卡在哪三个扩展机制到底解决什么问题Claude Code 用了一段时间后很多人会进入同一个困惑期Agents、Skills、Hooks 这三个词反复出现在文档和社区讨论里但真到自己的项目里却不知道该把哪段逻辑写进哪个文件。结果就是配置越堆越多上下文越来越臃肿自动化该触发的时候不触发不该跑的时候乱跑。这个问题的本质不是哪个更强而是三者的触发模型完全不同。Hooks 是事件驱动的强制回调你不需要调用它它在文件保存、命令执行、会话结束这些节点自动跑Skills 是按需加载的流程手册只有你输入/技能名或者 Claude 判断匹配时才注入上下文Agents 是拥有独立思考循环和隔离上下文的专项代理适合把复杂任务拆出去单独跑。适合读这篇的人刚接触 Claude Code、正在纠结要不要写CLAUDE.md、看到.claude/skills/和.claude/agents/目录不知道放什么、或者已经配了一堆但发现效果不对的开发者。下面我会用一套可复制的settings.json和config.toml骨架配合逐项验证动作帮你把三者的边界跑通。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配置三大扩展机制之前先确保你的 Claude Code 能正常发起请求。我这边用的是 TaoToken 作为模型接入层它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式Claude Code 可以直接对接。你需要先去控制台创建一个 API Key。打开https://taotoken.net/console在 API Keys 页面生成一个密钥复制保存好。这个 Key 后面会写进环境变量不要直接硬编码到项目文件里。环境变量配置方式Linux/macOSexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥Windows PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的密钥配置完成后用一条最简单的请求验证连通性curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }如果返回里能看到content字段和正常的文本内容说明接入层没问题。这一步很关键因为后面 Hooks 里的prompt类型校验、Agents 的独立循环都依赖底层请求能正常走通。如果这里就报 401 或连接超时先解决接入问题别急着写扩展配置。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层项目级的.claude/settings.json管权限和 Hooks用户级的~/.claude/config.toml管模型和全局行为。下面给出一套能直接用的骨架。3.1 settings.json 骨架在项目根目录创建.claude/settings.json{ permissions: { allow: [ Bash(pnpm prettier:*), Bash(pnpm eslint:*), Bash(pnpm test:*), Read(./src/**), Edit(./src/**) ], deny: [ Bash(rm -rf:*), Bash(sudo:*), Read(./.env) ] }, hooks: { PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: pnpm prettier --write \$CLAUDE_FILE_PATH\, statusMessage: 格式化修改的文件 } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \$CLAUDE_BASH_COMMAND\ | grep -qE rm -rf /|sudo rm exit 1 || exit 0 } ] } ], Stop: [ { matcher: *, hooks: [ { type: command, command: pnpm test --run, statusMessage: 任务结束运行测试 } ] } ] } }这里有几个点要注意。permissions.deny里的规则优先级高于allow所以即使你允许了Bashrm -rf依然会被拦。hooks里的matcher决定触发范围Edit表示只在编辑文件后触发Bash表示在执行 shell 命令前触发*表示所有情况。3.2 config.toml 骨架用户级配置放在~/.claude/config.toml[model] default claude-sonnet-4-20250514 max_tokens 8192 [api] base_url https://taotoken.net/api timeout 120 [behavior] auto_approve_read true auto_approve_edit false context_window_warning 0.8context_window_warning设成 0.8 的意思是当上下文用到 80% 时给出提醒。这个参数在你有多个 Agents 并行跑的时候特别有用能提前发现上下文膨胀。3.3 Skills 目录骨架Skills 不写在 settings.json 里而是独立目录。创建.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 4. 健康检测 curl http://127.0.0.1:8080/health 5. 检测通过后推送镜像日志写入 ./deploy/log.txt ## 强制约束 - 构建失败立即终止输出错误堆栈 - 禁止跳过健康检测 - 所有命令打印到控制台3.4 Agents 目录骨架创建.claude/agents/db-schema/AGENT.md# Agent: db-schema ## 任务边界 仅处理 src/db/ 目录下的表结构与 SQL 迁移 ## 权限 - 允许读写 src/db/、docs/sql/ - 仅可调用 /db-migration 技能 - 禁止修改前端与接口业务代码 ## 工作流程 1. 接收主 Agent 传入的库表需求 2. 读取项目数据库规范生成 PostgreSQL 建表语句 3. 生成 ER 关系图写入 docs/db-er.md 4. 执行 sql-lint 校验 5. 返回 SQL 脚本与变更说明4. 逐项验证确认三者真的按预期工作配置写完不代表生效必须逐项验证。下面是我实际跑通的验证动作。4.1 验证 Hooks 是否触发先确认 PostToolUse 的格式化钩子。在 Claude Code 里让它编辑一个.ts文件比如帮我把 src/utils/format.ts 里的 formatDate 函数改成支持时区参数编辑完成后观察终端是否出现格式化修改的文件这个 statusMessage。然后检查文件内容如果 Prettier 生效缩进和引号风格应该被统一了。如果没触发检查matcher是否写成了Edit而不是edit大小写敏感。再验证 PreToolUse 的拦截。让 Claude Code 执行一条危险命令帮我执行 rm -rf /tmp/test如果配置正确这条命令会被拦截终端提示权限拒绝。注意这里用的是command类型而不是prompt类型因为高频事件用prompt会持续消耗 token能用 shell 脚本判断的就别用 LLM。4.2 验证 Skills 是否加载在对话框输入/deploy观察 Claude Code 是否读取了SKILL.md的内容。正常情况下它会按文档里的步骤逐条执行而不是自由发挥。如果它没有按流程走检查SKILL.md的路径是否正确必须是.claude/skills/技能名/SKILL.md这个层级。你可以故意在SKILL.md里写一条约束比如禁止跳过健康检测然后看它执行时是否会遵守。如果它跳过了说明 Skill 没被正确加载可能被当成了普通上下文。4.3 验证 Agents 是否隔离输入db-schema 设计订单表观察它是否只操作src/db/目录。你可以故意让它改一个前端文件比如db-schema 顺便把 src/web/App.tsx 里的接口地址改一下如果 Agent 边界配置正确它会拒绝这个请求因为它只被授权操作src/db/。这个隔离能力是 Agents 和 Skills 最大的区别Skills 只是流程手册没有权限边界Agents 有独立的上下文和权限约束。5. 本篇常见错排查5.1 Hooks 不触发最常见的原因是matcher写错。PostToolUse的 matcher 是工具名比如Edit、Write、Bash不是文件扩展名。如果你想按文件类型过滤要在 hook 的 command 里自己判断$CLAUDE_FILE_PATH的后缀。另一个原因是 settings.json 的 JSON 格式错误。Claude Code 对 JSON 语法很严格多一个逗号就会整个文件失效。用jq . .claude/settings.json检查一下格式。5.2 Skills 加载了但没按流程走检查SKILL.md里是否有明确的步骤编号。Claude Code 对有序列表的遵循度比无序列表高。另外如果 Skill 内容太长可能会被截断建议把核心流程控制在 50 行以内详细说明放到同目录的其他文件里。5.3 Agents 上下文溢出如果你发现 Agent 跑着跑着开始重复或者丢失上下文大概率是任务拆分不够细。一个 Agent 只做一件事比如db-schema只管表结构不要让它同时管迁移和查询优化。在AGENT.md里明确写禁止做什么比写可以做什么更有效。5.4 三者混用导致重复执行典型错误是把部署流程写进 Hook。比如在PostToolUse里配置docker build结果每次编辑文件都触发一次构建速度慢到无法忍受。记住Hook 只做轻量的、必须强制的校验和格式化重流程放 Skill需要独立思考和隔离的放 Agent。6. 选型决策与后续接入快速判断口诀只要自动触发、强制校验选 Hooks固定标准化操作、一键执行流程选 Skills复杂独立专项任务、需要隔离上下文选 Agents。如果你还在调试接入层先去https://taotoken.net/api-keys确认密钥状态再对照https://taotoken.net/doc检查请求格式。模型对话相关的验证可以直接在https://taotoken.net/models里试。长期用 Claude Code 做编码和 Agent 编排的话Coding Plan 的额度模型更适合高频调用场景具体在https://taotoken.net/coding-plan看。配置这东西跑通一次比看十篇文档都管用。先把settings.json里的一个 Hook 验证通过再加第二个别一次性全堆上去。