1. 为什么四个概念总让人绕晕从一次真实踩坑说起Claude Code 用久了你一定会遇到这个场景项目里.claude/目录越堆越乱settings.json里塞了一堆配置commands、agents、skills三个文件夹各有一堆 Markdown但真到用的时候你根本说不清某个能力到底是靠哪个机制触发的。我试过在一个中型 Node 项目里同时挂了 6 个 Skill、4 个 Command、3 个 Sub-Agent结果一次重构任务里 Claude 反复调用同一个 SkillCommand 却完全没被触发排查了半天才发现是description写得和任务语义不匹配。这就是本文要解决的问题把 Skills、Commands、Agents、Plugins 四个扩展机制拆成可复制、可验证的配置骨架让你在本地跑通一条完整调用链而不是停留在概念层面。适合已经装好 Claude Code、能跑通基础对话、但配置一多就失控的开发者。核心检索词先摆出来Claude Code 的 Skills 是自动触发的操作手册Commands 是手动触发的提示词快捷方式Agents 是任务分工的执行单元Plugins 是打包分发机制——四者不在同一层混着配必然乱。我会从settings.json和config.toml两个骨架文件出发逐个拆解配置项、触发方式、验证动作最后说明如何通过 TaoToken 统一 Key 和 API 通道接入让本地配置和线上调用走同一条链路。全程给可复制的片段你跟着改就能跑。2. 前置准备TaoToken 统一 Key 与 API 通道在动配置文件之前先把接入层理顺。Claude Code 默认走 Anthropic 官方端点但如果你希望统一管理 Key、方便切换模型、或者团队共享一套通道可以用 TaoToken 作为 API 入口。它的作用是提供一个兼容 Anthropic Messages API 的地址你只需要改环境变量不用动 Claude Code 本身的逻辑。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个不加 UTM。接入方式就是设置两个环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的TaoToken密钥密钥在控制台生成地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后建议写进 shell 的 profile 文件而不是每次手动 export否则新开终端就失效。注意环境变量名必须是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKENClaude Code 只认这两个。写成ANTHROPIC_API_KEY在某些版本里不生效这是很多人第一次接入时卡住的地方。配置完成后先别急着写 Skills用一条最小请求验证通道是否通。这一步很关键因为后面所有扩展机制的调试都依赖这条链路正常。3. 可复制配置骨架settings.json 与 config.tomlClaude Code 的配置分两层settings.json管权限、MCP、hooks、插件启用config.toml部分版本用~/.claude/config.toml管模型、端点、默认行为。两者职责不同别混写。先看settings.json的骨架放在项目根目录.claude/settings.json{ permissionMode: plan, enableSkills: true, mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./src] } }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node scripts/audit-command.js } ] } ] } }permissionMode建议先用plan它会禁止写入和 Shell 操作适合调试扩展机制时避免误改文件。等配置稳定了再切到auto。enableSkills必须为true否则.claude/skills/下的内容不会被加载。再看config.toml它管的是模型和端点[model] default claude-sonnet-4-20250514 fallback claude-haiku-3-5-20241022 [api] base_url https://taotoken.net/api timeout_seconds 120 [behavior] auto_load_claude_md true max_context_tokens 180000base_url指向 TaoToken 的 API 端点这样所有请求都走统一通道。max_context_tokens设成 180000 而不是 200000是给 Skills 的元数据留出余量——每个 Skill 的 name 和 description 大约占 30 到 50 token挂 20 个就是 1000 token 左右留点空间更稳。四个扩展机制的目录结构长这样放在项目根目录.claude/ ├── settings.json ├── skills/ │ └── conventional-commit/ │ └── SKILL.md ├── commands/ │ └── review.md ├── agents/ │ └── code-reviewer.md └── plugins/ └── (插件安装后自动生成)Skills 和 Agents 用 YAML 前置元数据加 Markdown 正文Commands 是纯 Markdown 提示词Plugins 是打包目录。下面逐个拆。3.1 Skills 配置自动触发的操作手册Skill 的核心是SKILL.md前置元数据里的description决定了它什么时候被自动触发。写不好这个字段Skill 就是摆设。--- name: conventional-commit description: Generate git commit messages following Conventional Commits. Use when user asks to commit changes or write commit message. --- # Conventional Commit Skill Follow the Conventional Commits specification: type[optional scope]: description ## Allowed Types - feat: new feature - fix: bug fix - docs: documentation - refactor: code change without behavior change - test: adding or fixing tests ## Process 1. Run git diff --staged to inspect changes 2. Determine type and scope from the diff 3. Write imperative description, no trailing period 4. Add BREAKING CHANGE footer if applicable关键点description里必须包含触发场景的自然语言描述比如 Use when user asks to commit changes。Claude 是靠语义匹配来决定加载哪个 Skill 的描述越贴近真实对话触发越准。我踩过的坑是描述写得太抽象比如 helps with git结果 Claude 从来不加载它。验证 Skill 是否被识别启动 Claude Code 后输入/skills能看到列表里出现conventional-commit就说明加载成功。然后说一句帮我写个 commit message观察它是否自动调用。3.2 Commands 配置手动触发的提示词Command 就是一个 Markdown 文件文件名就是命令名。.claude/commands/review.md对应/review。# Review current changes Review the staged git diff for: - Logic errors and edge cases - Security issues (injection, auth bypass) - Performance problems - Style inconsistencies Focus only on changed lines. Cite line numbers. Suggest concrete fixes.触发方式是手动输入/review。它不会自动激活这是和 Skill 最大的区别。Command 适合固定流程的重复提示词比如每次 PR 前的检查清单。验证输入/commands列出所有可用命令看到review后直接输入/review观察输出是否按模板执行。3.3 Agents 配置任务分工的执行单元Sub-Agent 用 YAML 前置元数据定义角色、工具权限和模型。--- name: code-reviewer description: Review code for quality and security. Use after code changes. tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. Analyze the given code and report: 1. Bugs and logic errors with line numbers 2. Security risks with severity levels 3. Concrete fix suggestions Do not modify files. Only report findings.tools字段限制它只能用 Read、Glob、Grep不能写文件这是防止 Agent 越权的关键。model可以指定 sonnet、opus、haiku 或 inherit。验证输入/agents查看列表确认code-reviewer在列。然后显式调用比如用 code-reviewer 检查 src/auth.js观察它是否只读不写。3.4 Plugins 配置打包分发Plugin 不是新功能是把上面三类加 hooks、MCP 打包成一个可安装单元。目录结构my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── skills/ ├── commands/ ├── agents/ └── hooks/plugin.json清单{ name: team-workflow, description: Shared skills and agents for team, version: 1.0.0 }本地测试用claude --plugin-dir ./my-plugin加载命令会变成/team-workflow:review这种带命名空间的形式。安装第三方插件用/plugin marketplace add加仓库地址再/plugin install。验证加载后输入/plugin打开管理器确认插件状态为 enabled。4. 验证请求跑通一条完整调用链配置写完必须验证否则你不知道哪一层断了。按下面顺序逐项跑。第一步验证 API 通道。用 curl 直接打 TaoToken 端点curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: reply with ok}] }返回里有content字段且文本为 ok说明通道正常。如果返回 401检查ANTHROPIC_AUTH_TOKEN是否写对返回 404检查base_url是否漏了/api。第二步验证 Skill 触发。在 Claude Code 里说帮我提交这些改动观察它是否自动加载conventional-commit。如果没触发把description改得更贴近你的说法比如加上 when user says 提交。第三步验证 Command。输入/review看是否按模板输出。没反应就检查文件是否在.claude/commands/下、扩展名是否为.md。第四步验证 Agent。输入/agents确认列表然后显式调用。如果 Agent 试图写文件说明tools字段没生效检查 YAML 缩进——前置元数据对缩进敏感两个空格不能用 Tab。第五步验证 Plugin。用--plugin-dir加载本地插件输入/plugin看状态。命令带命名空间前缀是正常现象。一条完整链路跑通的表现是你说一句话Claude 自动匹配 Skill按需调用 AgentCommand 作为手动补充Plugin 把整套配置分发给团队。任何一环断了回到对应章节查配置。5. 本篇常见错排查Skill 不触发九成是description问题。Claude 靠语义匹配描述里要有触发场景的自然语言。另外检查settings.json里enableSkills是否为 true以及 Skill 目录层级是否为.claude/skills/name/SKILL.md多一层少一层都不行。Command 找不到文件名即命令名review.md对应/review。如果文件名带下划线或大写命令名会跟着变。放在.claude/commands/根目录不要嵌套子目录除非你想要/sub:cmd这种形式。Agent 越权写文件tools字段只写允许的工具没写的默认不可用。但如果你在settings.json里设了permissionMode: auto某些版本会覆盖 Agent 级别的限制。调试阶段用plan模式。Plugin 加载后命令不生效检查plugin.json的name字段命令前缀就是它。另外确认插件目录结构正确skills/、commands/、agents/必须在插件根目录下不能塞进.claude-plugin/。API 报连接错误先unset https_proxy和unset http_proxy代理变量会干扰请求。然后确认ANTHROPIC_BASE_URL指向 https://taotoken.net/api 末尾不要加斜杠。上下文溢出挂太多 Skill 会吃 token。每个 Skill 元数据约 30 到 50 token20 个就是 1000。定期用/skills审计移除不用的。config.toml里max_context_tokens别设满 200000留余量。同名 Skill 冲突优先级是企业 个人 项目 插件。如果你在~/.claude/skills/和.claude/skills/放了同名 Skill个人级会覆盖项目级。排查时先看~/.claude/skills/。6. 接入与验证的分流入口配置调通之后日常使用会分成两条线一条是排障和接入一条是模型验证和长期编码。排障和接入相关的去 API Keys 管理页和接入文档。API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。遇到 401、404、连接超时先查这两个页面。验证模型是否正常响应用模型对话页面快速测一条请求地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。它比 curl 更直观适合确认某个模型名是否可用。如果你要把 Claude Code 用于长期编码或 Agent 工作流走 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对持续调用场景做了通道优化比按次调用更稳。Claude Code 本身的接入配置参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的 ClaudeCodeAnthropic 章节里面有环境变量和config.toml的完整示例。最后说个实用技巧把.claude/目录纳入版本控制但把settings.json里的密钥字段抽到环境变量。团队共享 Skills、Commands、Agents 的配置密钥各自在本地 export。这样既统一了工作流又不会泄露凭证。配置稳定后你会发现 Claude Code 从每次都要手把手教变成了自带 SOP 的协作者而这一切的起点就是把四个扩展机制的骨架搭对。