1. 为什么你的 Claude Code 总是“差点意思”从一次真实踩坑说起很多人第一次打开 Claude Code CLI输入一句“帮我整理这周的 Git 提交记录生成周报”结果它要么答得泛泛要么每次都要重新解释一遍格式。问题不在模型而在于你只给了它一张嘴没给它一本岗位手册也没给它一双手。Claude Code Skills 和 MCP 工具正是补上这两块短板的关键。Skills 是一套用 Markdown YAML 写成的标准作业程序SOP它告诉 Claude“这类任务该按什么流程做、参考哪些资料、输出什么格式”MCPModel Context Protocol则像给 AI 装上的万能转接头让它能读本地文件、连数据库、调外部 API。前者管“怎么做”后者管“用什么做”。这篇教程面向刚接触 Claude Code CLI 的新手也适合已经会写 Prompt 但想让工作流稳定复用的开发者。我会从零开始带你写第一个 Skill 的 Markdown/YAML 骨架配置 settings.json 与 config.toml 接入统一 Key/API 通道再逐条验证 Skill 与 MCP 工具调用是否真的跑通。全程可复制、可跟做不玩虚的。先明确一个认知Skill 不是插件不需要编译MCP 也不是魔法它本质是一个遵循 JSON-RPC 的本地或远程服务进程。理解这两点后面的配置就不会慌。2. 前置准备TaoToken 统一 Key 与 Claude Code CLI 环境搭建在写 Skill 之前得先让 Claude Code CLI 能稳定调用模型。这里我用 TaoToken 作为统一 API 通道原因是它同时兼容 Anthropic 风格的接口Key 和 Base URL 一套配置就能覆盖 Claude Code、Cline、Codex 等多种客户端省去到处找 Key 的麻烦。第一步获取 API Key。打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_skills_mcputm_campaignrewrite 登录后在控制台创建一枚新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。第二步确认 Claude Code CLI 已安装。终端执行claude --version如果提示 command not found说明还没装。Claude Code CLI 通常随 Node 环境分发确保 Node 版本在 18 以上node -v npm -v第三步理解配置文件的位置。Claude Code 读取配置有两个层级全局配置在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json。而 MCP 服务器注册信息Claude Code 会写入~/.claude.json或通过claude mcp add命令管理。另外如果你用 Codex 或 Cline它们各自读~/.codex/auth.json和 Cline 的 MCP 配置但 Base URL 和 Key 是同一套。第四步设置环境变量。最稳妥的方式是在 shell 配置文件里导出避免明文写进 JSONexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Windows PowerShell$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的TaoToken密钥这里有个坑要提醒Base URL 末尾不要多加/v1TaoToken 的 Anthropic 兼容端点已经处理好路径多写反而会 404。配置完成后先别急着写 Skill用一条最简单的请求验证通道是否通。下一节我会给出完整的 settings.json 片段和验证命令。3. 可复制配置settings.json 与 config.toml 接入统一通道这一节是全文的核心操作区我会给出可直接复制的 JSON 和 TOML 片段。请对照你的实际路径修改不要照抄 Key。先看 Claude Code 的~/.claude/settings.json。这个文件控制模型通道、权限和默认行为{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Bash(git:*), Bash(npm:*) ] }, mcpServers: {} }注意ANTHROPIC_MODEL这一项它决定默认调用的模型 ID。TaoToken 支持多个 Claude 模型你可以按需替换。如果模型 ID 写错请求会返回model not found这是新手最常见的报错之一。再看 Codex 的~/.codex/auth.json。如果你同时用 Codex需要保证三件套一致——Base URL、Key、Model ID{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }Cline 的 MCP 配置则写在 VS Code 的 settings 里格式是 TOML 风格。假设你用 Cline 的config.toml[api] provider anthropic base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 [mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/你的用户名/projects]这里mcp_servers段落就是注册 MCP 工具的地方。command和args告诉 Claude Code 怎么启动这个 MCP 服务进程。文件系统 MCP 是最安全的入门选择它只暴露你指定的目录。配置写完后用claude mcp list查看已注册的 MCP 服务器claude mcp list如果输出里能看到 filesystem说明注册成功。如果报local proxy failed多半是 npx 没装或网络拉包失败先手动跑一遍npx -y modelcontextprotocol/server-filesystem /tmp看能否启动。关于 CTA 分流如果你只是排障和接入建议先看 API Keys 和接入文档如果你要长期跑编码 Agent直接上 Coding Plan 更划算。模型对话入口可以用来快速验证模型是否响应正常。4. 写第一个 SkillMarkdown YAML 骨架与逐条验证Skill 的本质是一个文件夹里面至少有一个SKILL.md。这个文件用 YAML front matter 声明元数据用 Markdown 写工作流程。Claude Code 启动时会扫描~/.claude/skills/目录按需加载。先建目录mkdir -p ~/.claude/skills/weekly-report然后创建~/.claude/skills/weekly-report/SKILL.md--- name: 周报生成助手 description: 根据零散工作内容生成结构化周报适用于 Git 提交、任务清单整理 version: 1.0.0 author: 你的名字 tags: [办公, 效率, 周报] --- # 周报生成技能 本技能帮助用户将零散的工作内容整理成专业周报。 ## 工作流程 1. 收集用户本周的工作内容可以是零散描述或 Git 提交记录 2. 按“完成事项 / 遇到问题 / 下周计划 / 需要支持”四类归档 3. 使用简洁专业的语言润色突出成果和价值 4. 输出标准 Markdown 格式周报 ## 输出格式 markdown ## 本周工作总结 ### 1. 完成事项 - [项目名称]完成[具体内容]进度[百分比] ### 2. 遇到的问题 - [问题描述]采用[解决方案]处理 ### 3. 下周计划 - [计划内容] ### 4. 需要的支持 - [支持事项]注意事项语言简洁专业避免口语化问题部分要体现解决思路计划要具体可衡量注意 YAML 里的 description 字段非常关键Claude Code 靠它判断当前任务是否匹配这个 Skill。描述太模糊Skill 就不会被触发。我试过把 description 写成“一个技能”结果它从来不调用改成“根据 Git 提交生成周报”后命中率明显提升。 写完后重启 Claude Code bash claude restart然后在对话里输入请使用周报生成助手技能帮我整理以下内容本周完成了登录模块重构修复了 3 个 bug下周计划接入支付。如果 Skill 生效你会看到它按四段式输出。如果没反应检查两点一是SKILL.md的 YAML 是否合法冒号后要有空格二是文件是否放在~/.claude/skills/下且目录名与技能无关但文件必须叫SKILL.md。验证 Skill 是否被加载可以用claude skills list这个命令会列出所有已识别的 Skill。如果列表为空说明路径不对或 YAML 解析失败。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错逐条给排查动作。这些坑我基本都踩过按顺序查能省不少时间。401 Unauthorized最常见。原因通常是 Key 写错、Key 过期或者 Base URL 和 Key 不匹配。排查动作先确认ANTHROPIC_API_KEY环境变量是否生效执行echo $ANTHROPIC_API_KEY看输出。如果为空说明 shell 配置没 source。再确认 Base URL 是https://taotoken.net/api不要带多余路径。最后去控制台确认 Key 状态是否正常。local proxy failed这个报错通常出现在 MCP 服务器启动阶段。原因是 Claude Code 尝试通过本地代理启动 MCP 进程但 npx 拉包失败或命令路径不对。排查动作手动执行 MCP 的启动命令比如npx -y modelcontextprotocol/server-filesystem /tmp看是否报错。如果报网络超时检查 npm registry 配置如果报 command not found确认 Node 和 npx 在 PATH 里。reading choices这个报错多出现在模型返回格式异常时Claude Code 解析响应失败。常见原因是模型 ID 写错或者 Base URL 指向了一个不兼容 Anthropic 格式的端点。排查动作确认ANTHROPIC_MODEL是 TaoToken 支持的模型 ID确认 Base URL 是/api而不是/v1。如果还不行用模型对话入口单独发一条消息看原始返回是什么。OAuth 相关报错如果你在 Claude Code 里看到 OAuth token 失效的提示说明它尝试走官方登录流程而不是 API Key。排查动作确保ANTHROPIC_API_KEY已设置且 settings.json 里没有残留的 OAuth 配置。必要时删除~/.claude/下的 token 缓存文件重启 CLI。再补充一个 MCP 工具调用失败的场景如果 Skill 里写了依赖某个 MCP 工具但该 MCP 没注册Claude 会提示工具不可用。排查动作claude mcp list确认服务器在列然后claude mcp get 名称查看详情。如果状态是 failed看它的启动日志。关于三件套的完整性无论你用 CC Switch、Cline MCP 还是 Codex auth.json只要涉及接入就必须同时确认 Base URL、Key、Model ID 三项一致。缺一项就会出现上面某类报错。这也是为什么我在第 3 节反复强调三件套。6. 把 Skill 和 MCP 串起来一个可运行的销售分析示例单有 Skill 只能规范流程单有 MCP 只能提供数据。真正好用的时候是两者协同。举个可跟做的例子用 Skill 定义报告结构用 MCP 读数据库。先注册一个数据库 MCP。假设你用 SQLite 做演示避免生产库风险claude mcp add sqlite -s user -- npx -y modelcontextprotocol/server-sqlite /tmp/sales.db然后写一个 Skill~/.claude/skills/sales-report/SKILL.md--- name: 销售分析报告 description: 连接 SQLite 数据库生成销售趋势与热销商品分析报告 version: 1.0.0 tags: [数据分析, 销售, 报告] --- # 销售分析技能 本技能通过 sqlite MCP 读取销售数据生成结构化分析报告。 ## 工作流程 1. 使用 sqlite MCP 查询指定时间范围的订单数据 2. 按以下维度分析销售额趋势、热销商品排行、用户转化率 3. 生成 Markdown 报告包含数据表格和结论 ## MCP 依赖 - sqlite读取 /tmp/sales.db ## 注意事项 - 只读查询禁止写入或删除 - 数据为空时明确提示不要编造重启后在对话里说请使用销售分析报告技能分析最近 30 天的数据。如果一切正常Claude 会先调用 sqlite MCP 执行查询再按 Skill 定义的格式输出。你可以在终端看到 MCP 的调用日志。这里有个实用技巧Skill 的description里最好带上触发关键词比如“销售”“报告”“数据库”这样 Claude 在匹配任务时更容易命中。另外MCP 的权限要最小化只暴露需要的目录或数据库文件不要图省事把整个 home 目录挂上去。最后一步验证检查输出里是否包含真实查询结果而不是模型编造的数字。如果数字对不上说明 MCP 没被调用回到第 5 节查local proxy failed或工具未注册的问题。整套流程跑通后你就有了一套可复用的“Skill 定义流程 MCP 提供数据”的组合。后续想扩展只需新增 Skill 文件或注册新的 MCP 服务器不用改模型通道。需要长期跑编码 Agent 的话Coding Plan 会比按量调用更省心临时验证模型响应用模型对话入口最快。接入和排障的细节随时回看接入文档和 API Keys 页面。