1. 先搞清楚这六类扩展到底插在哪
Claude Code 的扩展机制经常被混在一起讲，但它们在代理循环里插入的位置完全不同。你可以把一次会话想象成一条流水线：会话启动 → 加载上下文 → 模型思考 → 调用工具 → 执行动作 → 返回结果。CLAUDE.md 插在「加载上下文」这一步，每个会话都会读；Skills 是模型在思考时按需调用的知识包；subagents 是模型决定「这件事我自己干太乱，派个分身去干」时开出的隔离循环；hooks 挂在生命周期事件上，比如文件编辑后、工具调用前，属于后台自动化；MCP 是把外部服务接成工具，让模型能查数据库、发消息；plugins 则是把上面这些东西打包分发。
选型的核心判断只有一句话：这件事是「每次都要知道」还是「用到才需要」？是「模型自己决定」还是「事件强制触发」？每次都要知道的规则写进 CLAUDE.md；可复用的工作流写成 Skill；需要隔离上下文或并行跑的交给 subagent；必须在某个事件上无条件执行的用 hook；要连外部系统的走 MCP；要分发给团队或跨项目复用的，用 plugin 打包。
我见过最常见的误用是把一大堆项目规范全塞进 CLAUDE.md，结果每次会话都吃掉几千 token，模型还容易忽略重点。另一个极端是把该强制执行的检查写成 Skill，指望模型每次都记得调用，结果漏掉。下面按这六类逐个给骨架和验证动作，最后讲怎么用 TaoToken 统一 Key 通道。
2. TaoToken 前置：统一 Key 与 API 通道
在配这些扩展之前，先把模型通道理顺。Claude Code 默认走 Anthropic 官方端点，但如果你希望用统一的 Key 管理、方便切换模型或做用量观察，可以把它指向 TaoToken 的兼容通道。TaoToken 提供的是标准 API 接入，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。
你需要先拿到一个 API Key。登录后进控制台，在 API Keys 页面创建一个，复制出来。这个 Key 后面会写进环境变量，Claude Code 和 MCP 配置都会读它。
# 写入 shell 配置，按你实际用的 shell 选一个 echo 'export ANTHROPIC_BASE_URL="https://taotoken.net/api"' >> ~/.bashrc echo 'export ANTHROPIC_API_KEY="sk-你的TaoToken密钥"' >> ~/.bashrc source ~/.bashrc # 验证环境变量生效 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8注意ANTHROPIC_BASE_URL不要带末尾斜杠，也不要带 UTM 参数，UTM 只用于官网跳转统计。配好后 Claude Code 启动时会读这两个变量。如果你用的是 zsh，把~/.bashrc换成~/.zshrc。
提示：Key 不要提交进 Git。建议放在 shell 的私有配置里，或者用
.env并加进.gitignore。
3. 六类扩展的配置骨架与最小验证
3.1 CLAUDE.md：每次会话都加载的持久上下文
CLAUDE.md 放在项目根目录，Claude Code 启动时会自动读取。它适合写「始终执行」的规则：包管理器用哪个、提交前跑什么、目录结构约定。
# 项目约定 ## 包管理 - 使用 pnpm，不要用 npm 或 yarn - 安装依赖：pnpm add <pkg> ## 提交前 - 运行 pnpm lint 和 pnpm test - 提交信息用中文，格式：类型: 描述 ## 目录 - 源码在 src/，测试在 tests/ - 不要修改 generated/ 下的文件验证动作：在项目里启动 Claude Code，直接问「这个项目用什么包管理器」，它应该能答出 pnpm。如果答不出，检查 CLAUDE.md 是否在启动目录下。
3.2 Skills：可复用的知识与工作流
Skill 是一个 markdown 文件，放在.claude/skills/目录下，文件名就是调用名。你可以用/deploy这样的命令手动调用，模型也会在相关时自动加载。
--- name: deploy description: 部署清单，包含构建、测试、发布步骤 --- # 部署流程 1. 运行 pnpm build 2. 运行 pnpm test，全部通过才继续 3. 更新 version 字段 4. 执行 pnpm publish 5. 在 CHANGELOG.md 追加本次变更验证动作：在会话里输入/deploy，看它是否按步骤执行。如果没反应，确认文件路径是.claude/skills/deploy.md，且 frontmatter 格式正确。
3.3 subagents：隔离上下文的专用工作者
subagent 适合「读很多文件但只返回关键结论」的任务。配置放在.claude/agents/下，每个 agent 一个文件。
--- name: researcher description: 研究代码库中某个功能的实现，只返回关键发现 tools: Read, Grep, Glob --- 你是一个代码研究员。收到任务后，在代码库中搜索相关实现， 阅读必要文件，最后只返回： - 涉及的文件路径 - 核心逻辑摘要（不超过 200 字） - 潜在风险点 不要返回大段代码，不要修改任何文件。验证动作：让主会话调用这个 subagent 去研究某个功能，观察返回结果是否只有摘要，而不是一堆文件内容。
3.4 hooks：生命周期事件上的强制自动化
hooks 配在.claude/settings.json里，挂在事件上，比如文件编辑后自动跑 lint。这是「必须执行」的自动化，不依赖模型记性。
{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "pnpm eslint --fix $CLAUDE_FILE_PATH" } ] } ] } }验证动作：让 Claude Code 编辑一个.ts文件，故意留个格式问题，看保存后是否自动被 eslint 修掉。如果没触发，检查 matcher 是否匹配工具名，以及命令里的文件路径变量是否正确。
3.5 MCP：连接外部服务
MCP 让模型能调用外部工具。配置在.claude/settings.json或全局配置里，指向一个 MCP server。
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] } } }验证动作：启动 Claude Code 后问「列出 MCP 可用的工具」，看 filesystem 相关工具是否出现。如果没出现，检查 npx 是否能正常拉包，以及路径是否有权限。
3.6 plugins：打包分发
plugin 是把 CLAUDE.md、Skills、subagents、hooks、MCP 配置打成一个包，方便团队共享。结构大致如下：
my-plugin/ ├── plugin.json ├── CLAUDE.md ├── skills/ │ └── deploy.md ├── agents/ │ └── researcher.md └── settings.jsonplugin.json里声明名称、版本、包含哪些组件。验证动作：把 plugin 目录放到.claude/plugins/下，重启会话，看里面的 Skill 是否能被/调用出来。
4. 验证请求与成功结果
配完上面这些，做一次端到端验证。先确认通道通：
curl -s 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字段带文本，说明 Key 和基址都对。然后在项目里启动 Claude Code，依次验证：问项目约定（CLAUDE.md 生效）、输入/deploy（Skill 生效）、让 subagent 研究一个功能（隔离上下文生效）、编辑文件看 lint 是否自动跑（hook 生效）、问 MCP 工具列表（MCP 生效）。全部通过，说明六类扩展的骨架都立住了。
5. 本篇常见错排查
CLAUDE.md 不生效：最常见是文件不在启动目录，或者文件名大小写不对。Claude Code 只读当前工作目录及父目录的 CLAUDE.md，子目录里的不会自动加载。
Skill 调不出来：检查.claude/skills/路径，以及 frontmatter 的name和description是否都有。缺 description 时模型不会自动加载，只能手动/调用。
hook 不触发：matcher 写的是工具名，不是文件类型。Edit|Write匹配编辑和写入工具，如果你用的是别的工具名，要对应改。命令里的$CLAUDE_FILE_PATH变量在部分版本里叫法不同，先用echo打出来确认。
MCP 连不上：先单独在终端跑一遍npx命令，确认包能拉下来、路径有权限。MCP server 启动失败时 Claude Code 通常只在日志里提示，不会弹窗。
subagent 返回一堆代码：说明它的 prompt 没约束好。在 agent 文件里明确写「只返回摘要，不要返回代码块」，并限制可用工具，去掉 Write 和 Edit。
Key 报 401：检查ANTHROPIC_API_KEY是否有多余空格或换行，以及ANTHROPIC_BASE_URL是否误带了 UTM 参数。基址只到/api，后面不要加/v1。
6. 按场景选型与接入入口
回到选型本身，给你一张对照表：
| 需求 | 选什么 | 关键判断 |
|---|---|---|
| 每次会话都要知道的规则 | CLAUDE.md | 不写会出错，且每次都相关 |
| 可复用的工作流 | Skill | 用到才需要，可手动或自动触发 |
| 隔离上下文、并行任务 | subagent | 读多写少，只要结论 |
| 事件强制自动化 | hook | 不能靠模型记性，必须无条件跑 |
| 连外部服务 | MCP | 需要查库、发消息、控浏览器 |
| 团队分发 | plugin | 上面几类要打包共享 |
通道层面，如果你要长期跑编码任务或 Agent 工作流，建议用 Coding Plan 统一管理用量，入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ；只是想先验证模型对话是否通，用模型对话页面更快，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ；接入细节和参数说明看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。先把 Key 和基址配好，再按上面的骨架逐个加扩展，比一上来全塞进去稳得多。
