1. 先搞清楚 Claude Code 工具系统到底在解决什么问题Claude Code 的工具系统说白了就是一套让模型从“只会聊天”变成“能动手干活”的机制。你给它一个任务它需要读文件、搜代码、跑命令、改配置这些动作背后都是一个个具体的工具在支撑。官方内置了 30 多个工具覆盖文件操作、搜索、执行、任务管理、信息获取、辅助交互六大类。但真正让这套系统有意思的地方在于除了内置工具它还支持 MCP 和 Skills 两种扩展方式三者都出现在同一个 tools[] 数组里从 API 角度看长得一模一样但运行机制完全不同。如果你正在用 Claude Code 做日常开发或者想把它接入自己的项目流程理解这套工具系统的分类和协作方式能帮你少走很多弯路。比如你知道什么时候该写一个 Skill 而不是配一个 MCP Server知道为什么有些工具默认不在 tools[] 里出现知道怎么在本地验证工具调用链路是否正常。这篇文章会从工具分类地图讲起然后给出 MCP 配置片段和 Skills 目录结构示例最后用可复现的步骤带你在本地跑通一次完整的工具调用。我试过在几个不同规模的项目里配置 Claude Code 的工具链踩过的坑主要集中在 MCP 连接超时和 Skill 目录扫描不到这两个问题上。下面把整理出来的工具清单和配置方法分享给你照着做基本能跑通。2. 30 内置工具的分类地图与核心设计思路Claude Code 的内置工具不是随便堆在一起的它们按职责分成六个族每个族有清晰的设计边界。下面这张表是我根据实际使用和源码结构整理的分类清单你可以对照着看自己常用哪些。工具族代表工具核心职责典型使用场景文件操作族Read、Edit、Write、NotebookEdit读写和修改文件内容读取配置、修改代码、创建新文件搜索族Glob、Grep、LSP按文件名、内容、语义定位代码找测试文件、搜 TODO、查引用执行族Bash、PowerShell执行系统命令跑测试、构建镜像、启动服务Agent 控制族TodoWrite、TaskCreate、AgentTool任务编排与子 Agent 管理规划步骤、并行执行、递归拆分信息获取族WebFetch、WebSearch获取外部实时信息读 API 文档、搜最新方案辅助工具族AskUserQuestion、BriefTool、EnterPlanMode交互体验与流程控制主动提问、会话总结、规划模式文件操作族里最需要留意的是 Write 和 Edit 的区别。Write 是完整覆盖文件旧内容直接丢失权限检查最严格Edit 是精确字符串替换需要提供 old_string 和 new_string模型“看到什么改什么”不需要理解 diff 语法。这个设计选择很聪明因为 LLM 生成 diff 格式容易出错但复述文本很擅长。搜索族的三件套 Glob、Grep、LSP 是互补关系。Glob 按文件名模式匹配Grep 搜文件内容LSP 做语义级引用查找。举个例子你要理解 UserService 这个类先用 Glob 找到**/UserService.ts再用 Grep 搜哪些文件 import 了它最后用 LSP 找所有语义引用。三步下来这个类的使用情况就清楚了。执行族的 Bash 工具是权限系统的重点保护对象它有专门的 AST 权限检查也是唯一使用沙盒隔离的工具。在 Windows 上会注册 PowerShell 工具其他平台用 Bash。这个跨平台适配是自动的你不需要手动切换。Agent 控制族里 TodoWrite 和 Task 系列定位完全不同。TodoWrite 是同步的任务清单你在终端里看到 Agent 输出的有序步骤列表就是它生成的Task 系列是异步任务管理用来并行执行独立任务。AgentTool 则允许 fork 子 Agent子 Agent 有自己的上下文和工具池执行完结果回流。这个递归机制让 Agent 能按需分层主 Agent 规划、子 Agent 执行、子子 Agent 验证。信息获取族的 WebFetch 和 WebSearch 受权限和网络策略控制WebFetch 只能访问允许的域名列表。辅助工具族里 AskUserQuestion 比较特殊它是唯一一个 bypass 模式也拦不住的工具因为设计意图就是必须用户参与。3. MCP 配置片段与 Skills 目录结构实操理解了内置工具的分类接下来看 MCP 和 Skills 怎么接入。这两者的配置方式完全不同MCP 走协议连接Skills 走文件扫描。先看 MCP 的配置。Claude Code 通过.mcp.json文件声明 MCP Server支持 stdio 和 SSE 两种传输方式。下面是一个标准的 MCP 配置片段你可以直接复制到项目根目录的.mcp.json里{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /path/to/your/project ], env: {} }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: your_token_here } } } }这个配置声明了两个 MCP Serverfilesystem 提供文件系统操作工具github 提供 GitHub 相关工具。启动 Claude Code 时它会读取这个文件通过connectToServer()建立连接然后调用tools/list协议获取工具列表。每个 MCP 工具会被buildTool({ isMcp: true })包装成标准 Tool 接口和内置工具合并进 tools[] 数组。如果你用的是 TaoToken 的 API 接入Base URL 填https://taotoken.net/apiKey 在控制台创建Model ID 根据你用的模型填。这三件套在 MCP 配置里也需要对应设置确保 MCP Server 能正常调用模型。再看 Skills 的目录结构。一个 Skill 就是一个 Markdown 文件放在特定目录下Claude Code 启动时会扫描这些目录。标准的 Skills 目录结构是这样的.claude/ └── skills/ ├── deploy.md ├── test.md └── format.md每个.md文件用 frontmatter 定义元信息正文定义 Prompt。比如deploy.md的内容--- name: deploy description: 部署当前分支到 staging 环境 --- ## 部署流程 1. 先用 Bash 跑 git status 确认当前分支 2. 跑 npm test 确保测试通过 3. 跑 docker build -t app:staging . 构建镜像 4. 跑 kubectl apply -f deploy.yaml 部署到 staging 5. 输出部署结果和版本号当模型调用SkillTool(command: deploy)时SkillTool 会找到这个文件fork 一个子 Agent把 Markdown 内容作为 Prompt 注入子 Agent 独立执行这些步骤。注意 Skill 不新增能力它只是编排已有工具的使用方式。MCP 和 Skills 的 Token 效率都很高。MCP 工具默认不在 tools[] 里只有 ToolSearchTool 的 description 里有一行摘要Skills 永远只占 SkillTool 一个条目正文不传。只有真正调用时才展开完整内容。这是渐进式披露思想在工具层面的体现。4. 本地验证工具调用链路的可复现步骤配置写好了怎么确认工具调用链路是通的下面是一套可复现的验证步骤从启动到看到结果每一步都有明确的预期输出。第一步确认 MCP Server 能正常启动。在终端里直接跑配置里的命令npx -y modelcontextprotocol/server-filesystem /path/to/your/project如果这个命令能正常启动并保持运行说明 MCP Server 本身没问题。如果报错先解决依赖安装或路径问题。第二步启动 Claude Code 并检查 MCP 连接状态。在项目目录下运行claude --mcp-debug这个参数会输出 MCP 连接的详细日志。你应该能看到类似Connected to MCP server: filesystem和Fetched N tools from filesystem的输出。如果看到MCP server connection failed检查.mcp.json的路径和命令是否正确。第三步验证内置工具调用。在 Claude Code 对话里输入帮我读取 package.json 文件的前 20 行预期结果是模型调用 Read 工具返回文件内容。如果模型说“我无法读取文件”说明工具注册有问题检查是否有 Feature Gate 把 Read 工具裁掉了。第四步验证 MCP 工具调用。输入列出当前项目根目录下的所有文件如果 filesystem MCP Server 配置正确模型会先通过 ToolSearchTool 搜索 filesystem 相关工具然后调用mcp__filesystem__list_directory返回文件列表。你可以在输出里看到工具调用的完整链路。第五步验证 Skill 调用。确保.claude/skills/deploy.md存在然后输入执行 deploy 技能预期结果是模型调用 SkillToolfork 子 Agent子 Agent 按 Markdown 里的步骤依次执行。你会在输出里看到子 Agent 的独立执行过程最后结果回流到主 Agent。第六步检查 Token 消耗。在对话里输入/cost查看当前会话的 Token 使用情况。正常情况下MCP 工具和 Skills 的 Token 开销应该远低于把所有工具 Schema 都传进去的情况。如果发现 Token 异常高检查是否有 MCP Server 返回了过多工具。这套步骤跑下来基本能确认工具调用链路是通的。如果某一步卡住下一节的排查清单能帮你定位问题。5. 常见报错与排查清单工具调用链路出问题时报错信息往往比较隐晦。下面是我实际遇到过的几类典型报错和对应的排查方法。401 Unauthorized这个报错通常出现在 MCP Server 需要认证但 Token 无效或过期时。检查.mcp.json里对应 Server 的env字段确认 Token 是否正确。如果是 TaoToken 的 API Key去控制台确认 Key 状态和额度。另外注意 Base URL 是否填对API 地址是https://taotoken.net/api不要多加路径。local proxy failed这个报错说明 MCP Server 的本地连接建立失败。常见原因是命令路径不对或者 npx 包没有正确安装。先在终端里手动跑一遍 MCP Server 的启动命令确认能正常启动。如果手动能跑但 Claude Code 里报错检查.mcp.json的 JSON 格式是否有语法错误。reading choices 相关报错这个通常出现在模型返回格式不符合预期时。检查你用的 Model ID 是否和 API 端点匹配。如果用的是 TaoToken 的 Coding Plan确认 Model ID 填的是套餐支持的模型。另外检查 MCP Server 返回的工具 Schema 是否合法有些第三方 Server 的 Schema 可能不符合规范。OAuth 相关报错如果 MCP Server 需要 OAuth 认证检查回调地址和 Client ID 配置。这类问题通常需要看 MCP Server 的文档确认认证流程是否正确。Skill 目录扫描不到确认.claude/skills/目录存在且.md文件有正确的 frontmatter。frontmatter 必须包含name和description字段缺一个都可能导致扫描失败。另外检查文件编码确保是 UTF-8。工具调用超时MCP Server 响应太慢会导致超时。检查 Server 的网络连接和性能如果是远程 Server确认网络延迟在可接受范围内。可以在.mcp.json里调整超时参数但根本解决还是要优化 Server 响应速度。排查时建议按链路顺序来先确认 MCP Server 能独立启动再确认 Claude Code 能连上最后确认工具能被调用。每一步都有对应的日志输出--mcp-debug参数能帮你看到详细的连接过程。6. 把工具系统用起来的几个实用建议工具系统配置好之后怎么用得更顺手分享几个实际经验。MCP Server 不要配太多。每多一个 Server启动时就多一次连接和工具发现Token 开销也会增加。只配当前项目真正需要的比如文件系统、GitHub、数据库这几类高频的。不常用的按需临时加用完删掉。Skills 适合封装重复性流程。如果你发现自己反复让 Claude Code 做同一套操作比如“跑测试、构建、部署”这个三步流程就把它写成一个 Skill。Markdown 文件维护成本低改起来也方便。内置工具的权限设置要留意。Write 工具权限最严格Bash 工具有沙盒隔离这些默认设置不要轻易改。如果确实需要放宽权限先确认操作范围可控。验证工具调用链路时从简单到复杂。先验证 Read 这种只读工具再验证 Write 这种写操作最后验证 MCP 和 Skills。这样出问题时容易定位是哪一层的问题。如果你想把 Claude Code 接入自己的开发流程建议先从 API Keys 和接入文档开始把基础连接跑通再逐步加 MCP 和 Skills。TaoToken 的模型对话功能可以用来快速验证模型响应Coding Plan 适合长期编码场景。工具系统的配置和验证本质上是一个逐步迭代的过程不用一次配到完美。