1. 从零散技巧到稳定工作流：Claude Code 进阶能力到底解决什么问题
Claude Code 用了一段时间之后，很多人会卡在同一个瓶颈：单次对话里它能帮你改代码、跑测试、查文档，但每次开新会话，之前交代过的规范、流程、校验步骤又得重新说一遍。Skills、Subagents、Hooks、MCP 这四个能力，本质上就是把这套“每次都要重复交代”的东西沉淀成可复用的资产。Skills 负责封装团队规范和多步流程，Subagents 负责把重型分析拆到独立上下文里跑，Hooks 负责在生命周期节点上做确定性校验，MCP 负责把外部工具接进来。它们组合起来，才能把零散技巧变成稳定工作流。
这篇文章面向已经上手 Claude Code、但还没系统用过这四个能力的开发者。我会按“问题场景 → 前置准备 → 可复制配置 → 验证步骤 → 排错 → 下一步”的顺序展开，每个配置片段都能直接粘到项目里跑。如果你还没配置好模型接入，可以先用 TaoToken 模型对话 验证一下请求链路是否通，再往下做工作流编排。
先说清楚这四个能力的分工，避免混用：
| 能力 | 触发方式 | 上下文成本 | 典型用途 |
|---|---|---|---|
| Skills | 显式/命令或自动匹配 | 按需加载 | 封装多步流程、团队规范 |
| Subagents | Claude 主动委派 | 独立上下文，主会话零成本 | 重型分析、并行搜索 |
| Hooks | 生命周期事件自动触发 | 通常零成本 | 格式化、危险命令拦截 |
| MCP | Claude 主动调用工具 | 工具定义常驻 | 数据库、浏览器、项目管理 |
理解这张表，后面所有配置都不会跑偏。我试过把这四样一股脑全塞进项目，结果上下文被 MCP 工具定义占掉一大截，反而拖慢了日常编码。所以顺序很重要：先把 Skills 和 Hooks 跑通，再引入 Subagents，最后按需接 MCP。
2. 前置准备：接入配置与目录结构
在写任何 Skill 之前，先把模型接入和项目目录结构理清楚。Claude Code 的所有扩展能力都依赖一个稳定的 API 入口，这里用 TaoToken 作为接入层，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 的接口格式。
2.1 环境变量与 Base URL 配置
最省事的方式是通过环境变量注入，避免把 Key 硬编码进配置文件。在~/.zshrc或~/.bashrc里加上：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoToken密钥"如果你用的是 Claude Code 的 settings 文件，也可以写成 JSON。项目级配置放在.claude/settings.json，用户级放在~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥" } }Key 的获取入口在 TaoToken API Keys，生成后复制到上面两个位置之一即可。注意 Base URL 后面不要多加/v1，Claude Code 会自己拼接路径，多写反而会 404。
2.2 项目目录结构
Claude Code 的扩展文件有固定的查找路径，先建好骨架：
mkdir -p .claude/skills .claude/agents .claude/hooks .claude/rules touch .claude/settings.json CLAUDE.md最终结构大致是这样：
项目根/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── rules/ │ │ └── api-rules.md │ ├── skills/ │ │ └── code-review/ │ │ └── SKILL.md │ ├── agents/ │ │ └── test-runner.md │ └── hooks/ │ └── block-dangerous.sh2.3 CLAUDE.md 保持精简
CLAUDE.md 每次会话都会加载，所以只放“每次都需要”的信息。控制在 200 行以内，具体到可验证：
# 项目约定 ### 构建与测试 - 构建：`npm run build` - 测试：`npm test` - 开发：`npm run dev` ### 代码规范 - 使用 2 空格缩进 - 所有 API 端点以 `/api/v1` 为前缀 - 错误响应格式：`{ error: { code, message } }` ### 安全 - JWT_SECRET 从环境变量读取，不硬编码 - 用户输入必须用 zod 验证特定场景的规则分流到.claude/rules/，比如只对 API 路由生效的规则：
--- paths: - "src/routes/**/*.ts" --- # API 路由规则 - 每个路由文件导出 Express Router - 所有路由用 asyncHandler 包装 - 必须有对应的 zod schema这样前端规则不会干扰后端，也节省了上下文。配置完成后，用 TaoToken 接入文档 核对一下参数格式，确认 Base URL 和 Key 都正确。
3. 可复制配置：Skills、Subagents、Hooks、MCP 四件套
这一节是全文的核心，每个配置片段都能直接复制。我会按“先 Skills、再 Subagents、再 Hooks、最后 MCP”的顺序给，因为这是上下文成本从低到高的顺序。
3.1 Skills：封装团队代码审查流程
Skill 就是一个带 YAML frontmatter 的 Markdown 文件。创建.claude/skills/code-review/SKILL.md：
--- name: code-review description: 审查代码变更的质量、安全性和性能，输出分级反馈 --- # 代码审查流程 当被要求审查代码时，按以下步骤执行： 1. 运行 `git diff` 获取变更文件列表 2. 逐个文件审查，关注： - 类型安全和边界条件 - 错误处理是否完整 - 性能隐患（N+1 查询、不必要的循环） - 安全漏洞（SQL 注入、XSS） 3. 输出分级反馈： - 重要：合并前必须修复 - 小问题：建议改进 - 预先存在：不是本次变更引入的 ## 验证 - 运行 `npm test` 确认没有回归 - 运行 `npm run lint` 确认风格一致description字段写得越准，自动匹配命中率越高。调用时直接输入/code-review，或者自然语言说“帮我审查一下这个 PR”，Claude 会自动加载。
3.2 Subagents：隔离重型分析任务
子代理在独立上下文里跑，主会话只收摘要。创建.claude/agents/test-runner.md：
--- name: test-runner description: 运行测试并分析失败原因，区分真 bug 和测试本身需要更新 tools: Bash, Read, Grep model: haiku --- 你是测试分析专家。当被要求运行测试时： 1. 执行项目的测试命令 2. 如果有失败，分析失败原因 3. 区分“真正的 bug”和“测试本身需要更新” 4. 给出具体修复建议，附上文件路径和行号关键字段说明：
| 字段 | 作用 |
|---|---|
| tools | 限制可用工具，审查类只给 Read/Grep 就够 |
| model | 简单任务用 haiku，快且便宜 |
| isolation | 设为 worktree 可在隔离副本里跑 |
把探索性的、中间产物多的任务交给子代理，主会话保持干净。一个用 haiku 跑代码搜索的子代理，成本远低于在主会话里用大模型做同样的事。
3.3 Hooks：确定性校验与危险命令拦截
Hooks 在.claude/settings.json里配置。先写一个拦截危险命令的脚本.claude/hooks/block-dangerous.sh：
#!/usr/bin/env bash # 从 stdin 读取工具调用 JSON，检查是否包含危险命令 input=$(cat) command=$(echo "$input" | jq -r '.tool_input.command // empty') if echo "$command" | grep -qE 'rm -rf|DROP TABLE|TRUNCATE'; then echo "阻止执行危险命令: $command" >&2 exit 2 fi exit 0赋予执行权限：
chmod +x .claude/hooks/block-dangerous.sh然后在 settings.json 里注册：
{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" } ] } ], "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": ".claude/hooks/block-dangerous.sh" } ] } ] } }退出码 2 表示阻止操作。PostToolUse 在编辑后自动格式化，PreToolUse 在执行前拦截危险命令。这两个都是确定性的，不依赖 Claude “记得”去做。
3.4 MCP：接入数据库与外部工具
MCP 让 Claude 能主动调用外部工具。以 SQLite 为例：
claude mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite export SQLITE_DB_PATH=./app.db配置作用域用--scope project可以写进.claude/settings.json，团队共享：
{ "mcpServers": { "sqlite": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sqlite"], "env": { "SQLITE_DB_PATH": "${SQLITE_DB_PATH}" } } } }敏感信息用环境变量传递，不要硬编码。MCP 工具定义会常驻上下文，所以只添加真正需要的工具。如果你只是偶尔查一次数据库，直接在终端用 SQL 客户端更快。
4. 验证请求：一次完整任务链的跑通步骤
配置写完不算完，得验证整条链路能跑通。这一节用一个真实任务链：给一个 Express 项目加一个“获取任务列表”的端点，走完 Skill 创建、Hook 校验、Subagent 分析、MCP 查询的全流程。
4.1 验证模型接入
先确认 API 链路通。在项目根目录启动 Claude Code：
claude输入一个简单请求：
> 读取 package.json，告诉我项目用了哪些依赖如果返回了依赖列表，说明 Base URL 和 Key 都正确。如果报 401，回到第 2 节检查环境变量。如果报local proxy failed，检查 Base URL 是否多写了/v1。
4.2 验证 Skill 加载
输入/code-review，看 Claude 是否加载了审查流程。如果提示“未知命令”，检查.claude/skills/code-review/SKILL.md的路径和 frontmatter 格式。YAML 的---必须顶格，name和description不能缺。
4.3 验证 Hook 触发
让 Claude 编辑一个文件：
> 在 src/utils/logger.ts 里加一行注释编辑完成后，检查文件是否被 Prettier 格式化过。如果没生效，先确认jq已安装：
jq --version没装的话，macOS 用brew install jq，Linux 用apt install jq。
4.4 验证 Subagent 隔离
让 Claude 做一个重型分析：
> 分析 src/ 下所有文件，找出没有错误处理的异步函数Claude 会委派给子代理。你只会看到最终摘要，中间的文件读取过程不会进入主会话。如果子代理没被触发，检查.claude/agents/test-runner.md的description是否匹配任务。
4.5 验证 MCP 调用
> 查询 users 表里最近 7 天注册的用户数量Claude 会生成 SQL 并调用 SQLite MCP。如果报“工具不存在”，运行claude mcp list确认服务器已注册。如果报连接错误，检查SQLITE_DB_PATH是否指向真实文件。
4.6 完整任务链验证
把上面串起来，走一次完整流程：
> /code-review 审查当前 git diff > 分析 src/services/ 下有没有内存泄漏风险 > 查询 tasks 表里超过 30 天未更新的任务三个请求分别触发 Skill、Subagent、MCP。如果都能正常返回，说明四件套已经跑通。这套链路验证下来，你会发现每个能力各司其职，互不干扰。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
配置过程中最容易踩的坑集中在接入层和配置格式上。这一节按真实报错逐个排查。
5.1 401 Unauthorized
最常见的原因是 Key 没生效。排查顺序：
- 确认
ANTHROPIC_API_KEY环境变量已导出：echo $ANTHROPIC_API_KEY - 确认 Key 没有多余空格或换行
- 确认 Base URL 是
https://taotoken.net/api，不是首页地址 - 如果用了 settings.json，确认 JSON 格式合法：
jq . .claude/settings.json
Key 失效的话，去 TaoToken API Keys 重新生成一个。
5.2 local proxy failed
这个报错通常和 Base URL 格式有关。检查两点：
- Base URL 末尾不要加
/v1，Claude Code 会自己拼 - 不要配置额外的代理环境变量，除非你的网络环境确实需要
如果确认格式没问题还是报错，用 curl 直接测一下：
curl -X POST 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-6","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'返回正常 JSON 说明链路通，问题在 Claude Code 配置侧。
5.3 reading choices 报错
这个报错一般出现在响应解析阶段，常见原因是模型返回格式不符合预期。排查：
- 确认请求的 Model ID 拼写正确，比如
claude-sonnet-4-6 - 确认没有在请求里混用 OpenAI 格式的参数
- 如果用了自定义 MCP 服务器，检查它返回的数据结构是否符合协议
Model ID 写错是最常见的原因。对照 TaoToken 模型对话 页面上的可用模型列表核对。
5.4 OAuth 相关报错
如果你用的是 Claude Code 的 OAuth 登录流程，报错通常和 token 过期有关。排查：
- 运行
claude logout再claude login重新走一遍 - 确认系统时间准确，OAuth token 对时间敏感
- 如果同时配置了 API Key 和 OAuth，优先用 API Key，避免冲突
5.5 Hook 不触发
Hook 配置对了但没执行，检查：
matcher字段是否匹配工具名，Edit|Write是正则- 脚本是否有执行权限：
ls -l .claude/hooks/ - 脚本退出码是否正确，0 表示放行，2 表示阻止
5.6 Skill 自动匹配不命中
description写得太模糊会导致自动匹配失败。把“审查代码”改成“审查代码变更的质量、安全性和性能，输出分级反馈”，命中率会明显提升。显式调用/code-review永远有效，自动匹配只是锦上添花。
6. 把工作流沉淀下来：下一步怎么走
四件套跑通之后，接下来是把它们打包成团队资产。插件机制可以把 Skills、Agents、MCP 配置、Hooks 打包在一起分发。创建plugin.json：
{ "name": "team-workflow", "version": "1.0.0", "description": "团队标准工作流", "skills": ["skills/code-review"], "agents": ["agents/test-runner.md"], "mcp": { "servers": "mcp/servers.json" }, "hooks": { "config": "hooks/hooks.json" } }团队成员克隆仓库后用claude --plugin-dir ./plugin加载，新同事入职就能直接用上验证过的最佳实践。
如果你需要长期跑编码任务或 Agent 编排，TaoToken Coding Plan 提供了更适合持续调用的方案。配置管理入口在 TaoToken Console，可以集中查看用量和 Key 状态。
最后给一个实用建议：不要一次性把所有能力都上齐。先从 CLAUDE.md 和 Skills 开始，跑顺了再加 Hooks，等遇到重型分析任务再引入 Subagents，MCP 按需接。每加一层，观察上下文占用和响应速度的变化。工作流的价值不在于功能多，而在于稳定可复用——能让你每次开新会话都省下重复交代的时间，这套配置就值了。
