1. 从一次“提交翻车”说起四层扩展到底解决什么问题很多人第一次接触 Claude Code 的扩展机制都是从单个功能开始的写个/review命令觉得挺爽装个 Skill 觉得挺智能配个 Hook 觉得挺安全。但真正到了团队协作场景问题就来了——命令里塞了几百行提示词越来越难维护Skill 该不该自动加载全靠模型心情Sub-agent 跑完一堆测试日志把主对话冲得乱七八糟Hook 又经常在你不希望它触发的时候跳出来拦一刀。我试过在一个中型项目里把这四个机制拆开单独用结果就是“每个都能跑合起来就乱”。后来才想明白Command、Skill、Sub-agent、Hook 不是四个可以互相替代的工具而是四个不同维度的协作层。它们分别回答四个问题——用户怎么快捷触发、Claude 怎么获得专业能力、复杂子任务怎么隔离执行、流程怎么自动化保障。这篇笔记就按“四层协同架构”来拆从 Command 的触发入口到 Skill 的能力封装再到 Sub-agent 的任务分派最后到 Hook 的生命周期拦截。每一层我都会给出可复制的文件结构、配置片段和验证动作最后用一个完整的“自动审计 → 并行测试 → 拦截错误提交 → 规范提交信息”链路把四层串起来跑一遍。如果你正在用 Claude Code 做工程化落地或者想把零散的扩展点整理成一套可维护的架构这篇应该能帮你少走一些弯路。需要先说明一点下面所有示例里的模型调用入口我都会统一走 TaoToken 的 API 通道https://taotoken.net/api这样 Base URL、Key、Model ID 三件套在一个地方管理切换模型时不用改一堆配置文件。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 需要看文档的话从那里进就行。2. 四层扩展机制的前置认知与 TaoToken 接入准备在动手写配置之前得先把四层的职责边界和触发方式理清楚否则很容易写出“Command 里干 Skill 的活、Hook 里做 Sub-agent 的事”这种耦合代码。Command 是用户手动触发的。它就是一个放在.claude/commands/下的 Markdown 文件文件名就是命令名。你输入/github-auto-commitClaude 就把这个文件的内容注入当前对话上下文相当于你亲手打了一段长提示词。它的特点是确定性——你按了才执行不按永远不执行而且注入的内容会一直占着主上下文的 token。Skill 是Claude 自动判断加载的。它是一个文件夹里面有SKILL.md通过name和description让模型检索。会话启动时 Claude 只读所有 Skill 的 name description大约 100 token判断相关了才把完整正文加载进来。这就是“渐进式披露”——你可以装几十个 Skill无关任务根本不会被加载不会拖慢对话。Sub-agent 是主 Claude 显式启动的独立实例。它有自己的上下文窗口、系统提示、工具集和模型参数。主 Claude 判断某个子任务适合独立处理时启动一个全新的 Claude 实例去干干完返回结果摘要然后销毁中间所有工具调用和输出都不进入主对话。价值就是任务隔离和并行执行。Hook 是事件驱动、确定性执行的。你在.claude/settings.json里配置监听哪些生命周期事件PreToolUse、PostToolUse、UserPromptSubmit、SessionStart等事件一触发对应的 shell 命令必然执行不依赖模型判断。它不占对话上下文但可以通过退出码和标准输出反过来影响 Claude 的行为。四层要协同前提是模型调用通道统一。我习惯把 TaoToken 作为统一入口这样 Command、Skill、Sub-agent 里涉及模型调用的部分都指向同一个 Base URLKey 也只维护一份。准备动作很简单在 TaoToken 控制台创建一个 API Key记下 Base URL 和你要用的 Model ID。控制台入口是 https://taotoken.net/console Key 管理在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。这三件套后面在配置片段里会反复出现建议先准备好。3. 可复制的四层配置从 Command 到 Hook 的完整文件结构这一节是全文最“重”的部分我会把四层各自的定义文件、配置片段和目录结构都写出来你可以直接复制到项目里改。先看整体目录结构这是四层协同的物理基础your-project/ ├── .claude/ │ ├── commands/ │ │ └── github-auto-commit.md # Command 定义 │ ├── skills/ │ │ └── code-audit/ │ │ ├── SKILL.md # Skill 定义 │ │ └── scripts/ │ │ └── complexity-check.sh │ ├── agents/ │ │ └── test-runner.md # Sub-agent 定义 │ ├── hooks/ │ │ └── auto-commit-linter.sh # Hook 脚本 │ └── settings.json # Hook 注册 模型通道配置3.1 Command 定义把长流程压缩成一个斜杠命令.claude/commands/github-auto-commit.md的内容就是一段预置提示词它负责编排整个流程请按以下步骤执行自动提交流程 1. 加载 code-audit Skill对暂存区代码执行完整审计。 如果审计发现问题输出修正建议并终止流程。 2. 启动 test-runner Sub-agent在隔离环境并行运行全部测试套件。 等待 Sub-agent 返回结果摘要。 3. 如果审计和测试均通过基于暂存区变更生成符合 Conventional Commits 规范的 commit message展示给用户确认。 4. 用户确认后执行 git commitHook 会自动校验信息格式。 5. 校验通过后执行 git push。注意这里 Command 只做“编排”不写具体审计标准也不写测试命令——那些是 Skill 和 Sub-agent 的职责。这就是四层协同的第一条原则Command 只负责入口和流程顺序。3.2 Skill 定义把专业规范封装成可复用知识包.claude/skills/code-audit/SKILL.md的头部是元信息正文是审计标准--- name: code-audit description: 对暂存区代码执行质量审计检查圈复杂度、未使用变量、依赖漏洞和测试覆盖率。当用户要求审计代码或提交前检查时使用。 --- # 代码审计规范 ## 审计维度 1. 圈复杂度单个函数超过 15 判定为超标输出函数名和行号。 2. 未使用变量扫描所有声明但未引用的变量。 3. 依赖漏洞检查 package.json 中已知漏洞版本。 4. 测试覆盖率低于 80% 的文件需要标记。 ## 输出格式 按严重程度分级BLOCKER / WARNING / INFO。 BLOCKER 级别问题必须阻塞提交流程。Skill 的关键在于description写得准不准——它决定了 Claude 能不能在正确的时机自动加载。写得太泛会误激活写得太窄会漏激活。3.3 Sub-agent 定义把重任务隔离出去.claude/agents/test-runner.md定义了一个独立的测试执行者--- name: test-runner description: 在隔离环境中并行运行单元测试、集成测试和端到端测试返回结果摘要和失败用例列表。 model: claude-sonnet-4-20250514 tools: - Bash - Read --- 你是一个测试执行专员。你的任务是 1. 并行运行以下测试套件 - npm run test:unit - npm run test:integration - npm run test:e2e 2. 收集所有输出只返回摘要 - 通过数量、失败数量 - 失败用例的文件名和测试名 - 每个失败用例的错误摘要不超过 3 行 3. 不要返回完整日志不要返回堆栈跟踪全文。Sub-agent 的model字段可以单独指定这里我统一走 TaoToken 的通道在settings.json里配好 Base URL 和 Key 之后Sub-agent 启动时会自动继承。3.4 Hook 注册与脚本确定性拦截.claude/settings.json里注册 Hook同时配置模型通道{ model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: claude-sonnet-4-20250514 }, hooks: { UserPromptSubmit: [ { matcher: git commit, command: ./.claude/hooks/auto-commit-linter.sh } ], PreToolUse: [ { matcher: Bash, command: ./.claude/hooks/audit-bash-guard.sh } ] } }apiKey用环境变量引用不要把 Key 硬编码进仓库。Hook 脚本.claude/hooks/auto-commit-linter.sh#!/usr/bin/env bash # 校验 commit message 是否符合 Conventional Commits 规范 MESSAGE$(echo $CLAUDE_INPUT | grep -E ^git commit -m | sed s/^git commit -m // | sed s/$//) if [[ ! $MESSAGE ~ ^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-z]\))?: ]]; then echo Commit 被 Hook 拦截提交信息不符合 Conventional Commits 规范 2 echo 请使用格式type(scope): subject例如 feat(auth): add login validation 2 exit 2 fi echo Commit message 格式校验通过 exit 0退出码2表示拦截Claude 会收到这个错误信息并引导用户修正。退出码0表示放行。这就是 Hook 的确定性——不依赖模型判断脚本说不行就是不行。4. 验证四层协同一次完整调用链路与成功结果配置写完不代表能跑通得实际验证一遍。我建议按“单层验证 → 两层联动 → 四层全链路”的顺序来这样出问题容易定位。单层验证 Command在 Claude Code 里输入/github-auto-commit观察它是否读取了.claude/commands/github-auto-commit.md的内容。如果命令没出现在补全列表里检查文件路径和文件名是否匹配。单层验证 Skill直接问 Claude“帮我审计一下暂存区代码”看它是否自动加载code-auditSkill。如果没加载检查SKILL.md的description是否覆盖了你的提问关键词。单层验证 Sub-agent在对话里说“启动 test-runner 跑一遍测试”看主 Claude 是否调用了start_agent工具。Sub-agent 跑完后主对话里应该只有一段结果摘要没有完整测试日志。单层验证 Hook手动执行git commit -m 随便写的看 Hook 是否拦截并返回格式错误提示。如果没拦截检查settings.json里matcher是否匹配到了你的命令。四层全链路的验证就是完整跑一次/github-auto-commit。预期结果是这样的[用户] /github-auto-commit [Claude] 正在加载 code-audit Skill... 审计完成发现 2 个 WARNING0 个 BLOCKER。 正在启动 test-runner Sub-agent... [Sub-agent 返回] 通过: 243失败: 3 失败用例: login.spec.js, api/auth.test.js, utils/format.test.js [Claude] 测试未全部通过流程终止。请先修复失败用例。如果测试全部通过流程会继续走到 commit message 生成然后 Hook 在UserPromptSubmit事件触发时校验格式。格式不对就拦截格式对了就放行并 push。这里有个细节值得注意Sub-agent 返回的失败用例列表是摘要不是完整日志。完整日志留在 Sub-agent 的独立上下文里随着它销毁而消失。这就是任务隔离的价值——主对话不会被几百行测试输出淹没。验证模型调用是否走了 TaoToken 通道可以在 Sub-agent 执行时观察网络请求或者临时把baseUrl改成一个错误地址看是否报连接失败。如果报错信息里出现了taotoken.net相关域名说明通道配置生效了。需要确认模型可用性的话可以从 https://taotoken.net/models 进模型对话页面手动测一下。5. 四层协同常见报错与排查对照这一节列几个我在实际配置中踩过的坑都是真实报错对照着排查能省不少时间。报错一401 Unauthorized或invalid api key这是模型通道配置问题。检查settings.json里的apiKey是否正确引用了环境变量以及环境变量本身是否已导出。如果你用的是 TaoToken 的 Key确认 Key 没有过期并且baseUrl写的是https://taotoken.net/api注意不要多加路径。排查命令echo $TAOTOKEN_API_KEY | head -c 8 curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回200说明 Key 和通道都正常返回401就是 Key 的问题。报错二local proxy failed或connection refused通常是baseUrl写错或者本地网络策略拦截。确认baseUrl是https://taotoken.net/api不要写成http://或者带多余端口。如果公司网络有出口限制检查是否放行了该域名。报错三reading choices相关解析错误这个报错一般出现在 Sub-agent 返回结果时说明模型返回的 JSON 结构不符合预期。常见原因是 Sub-agent 的model字段指定了一个不存在的 Model ID或者通道返回了非标准格式。检查settings.json和 Sub-agent 定义里的modelId是否一致并且确认该模型在 TaoToken 通道里可用。报错四OAuth相关报错或登录态失效如果你之前用的是官方 OAuth 登录方式切换到 API Key 通道后需要清理旧的登录态。检查~/.claude/下是否有残留的凭据文件必要时重新走一次配置流程。TaoToken 的接入文档里有完整的切换步骤从 https://taotoken.net/doc 可以进。报错五Hook 不触发或误触发Hook 不触发先检查settings.json里的事件名拼写UserPromptSubmit不是UserPromptSubmitted再检查matcher是否匹配到了实际命令。Hook 误触发通常是matcher写得太宽比如用git匹配到了所有 git 命令。建议matcher尽量精确到具体子命令。报错六Skill 不自动加载先确认SKILL.md的description是否包含了用户提问里的关键词。如果用户问“检查代码质量”而你的 description 只写了“审计暂存区”模型可能判断不相关。另外确认 Skill 目录名和name字段一致路径在.claude/skills/下。排查顺序建议先确认模型通道401 类问题再确认单层配置Hook/Skill 不触发最后确认四层联动Sub-agent 返回异常。大部分问题都出在通道配置和路径拼写上真正涉及逻辑的反而少。6. 把四层用起来从单点工具到工程化协作回到最开始那个问题为什么四个机制单独用都能跑合起来就乱因为大多数人把它们当成四个并列的工具而不是四个协作的层。Command 是入口层Skill 是能力层Sub-agent 是隔离层Hook 是保障层——它们各自解决一个维度的问题组合起来才是一套完整的工程化方案。我的建议是不要一上来就四层全上。先从 Command 开始把高频操作压缩成斜杠命令等命令内容开始重复了抽成 Skill等某个子任务输出太多污染主对话了拆成 Sub-agent等某个操作需要强制规范了加 Hook。每一步都是被真实痛点驱动的而不是为了架构而架构。模型调用通道这块统一走 TaoToken 的好处是配置只维护一份Command、Skill、Sub-agent 都继承同一套 Base URL Key Model ID。需要长期跑编码任务或者 Agent 编排的话可以从 https://taotoken.net/coding-plan 进 Coding Plan 页面看看按需选就行。API Key 管理和接入文档分别在 https://taotoken.net/api-keys 和 https://taotoken.net/doc 配置过程中遇到通道问题优先查这两个地方。最后留一个实用技巧四层协同的调试最有效的方式是给每一层加日志。Command 执行时打印当前步骤Skill 加载时打印 nameSub-agent 启动和返回时打印摘要Hook 触发时打印事件类型和退出码。这样一旦链路断了你能立刻定位到是哪一层没接上。日志不要写进主对话写到独立文件里用tail -f盯着看就行。