1. Claude Code skills 加载链路到底怎么跑从 SKILL.md 到渐进式披露的完整拆解Claude Code skills 是 Claude Code 里一种把「专业知识 工作流程 可执行脚本」打包成文件夹的扩展机制核心文件是 SKILL.md。它能做什么简单说你写一次 SKILL.mdClaude 就能在后续对话里按需识别、按需加载、按需执行而不是每次把全部指令塞进上下文。适合谁适合那些反复给 AI 解释同一套流程的人——团队代码规范、文档处理流程、内部 API 调用约定这些都能封装成 skill。我先把最容易混淆的一点讲清楚skills 不是提示词模板也不是 MCP 工具。它更像一本放在文件系统里的操作手册Claude 先看目录元数据需要时翻到对应章节核心指令再需要时才去查附录脚本和参考文档。这个「先目录、再章节、后附录」的加载策略就是渐进式披露progressive disclosure。为什么这个设计重要因为上下文窗口是有限的。如果你装了 30 个 skill每个 SKILL.md 主体 2000 tokens全量加载就是 6 万 tokens对话还没开始上下文就满了。渐进式披露把启动时的开销压到每个 skill 约 100 tokens 的元数据只有真正命中的 skill 才加载主体。这就是为什么你能装很多 skill 而不拖垮对话。加载链路分三层我按执行顺序拆第一层是元数据层。Claude Code 启动时会扫描 skills 目录读取每个 SKILL.md 顶部 YAML frontmatter 里的name和description形成一个「技能目录」常驻上下文。这一层决定 Claude 知不知道有这个 skill、大概什么时候该用。第二层是核心指令层。当 Claude 根据用户请求和元数据判断某个 skill 相关时才读取 SKILL.md 的 Markdown 主体拿到详细工作流程、规则、约束。这一层是按需触发的不命中就不加载。第三层是扩展资源层。只有当核心指令里明确写了「读取 scripts/xxx.py」或「参考 references/api.md」时Claude 才会去读这些文件。脚本可以被直接执行参考文档才进入上下文。理解这三层你就能明白为什么 description 字段是整个 skill 里最关键的字段——它是唯一常驻上下文的部分写不好skill 永远不会被触发。很多人 skill 写完没反应90% 是 description 没写清楚触发场景。再讲 MCP 在其中的协作边界。MCP 解决的是「连接」问题让 Claude 能安全访问外部工具和服务比如数据库、GitHub、内部系统。skills 解决的是「怎么做」的问题是一套操作手册。两者关系是skill 可以指挥 Claude 去调用 MCP 提供的工具但 skill 本身不负责建立连接。Function Calling 则是「执行单个动作」的机制。三者互补MCP 建连接Function Calling 执行动作skills 编排整个流程。举个具体例子。你有一个「发布版本」的 skillSKILL.md 里写第一步用 MCP 的 git 工具拉取最新代码第二步运行 scripts/build.sh第三步用 MCP 的 issue 工具更新发布单。这里 MCP 提供 git 和 issue 的连接能力skill 提供「先拉代码、再构建、后更新」的编排逻辑Function Calling 是底层真正触发每个工具调用的机制。边界很清楚skill 不碰连接细节MCP 不管流程顺序。实测下来最容易踩的坑是把 skill 写成万能手册。一个 skill 塞进代码审查、部署、文档生成三件事description 就会变得模糊Claude 判断不准触发率反而下降。正确做法是一个 skill 只解决一类明确问题description 里写清具体功能和触发关键词。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套怎么配在深入 skill 的配置和验证之前得先把运行环境准备好。Claude Code 要能正常调用模型需要三样东西Base URL、API Key、Model ID。这三件套缺一不可配错了就会出现 401 或者连接失败。TaoToken 在这里的角色是提供兼容 Anthropic 接口的调用入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个。先说 Base URL。Claude Code 默认走 Anthropic 官方接口要切到兼容入口需要设置环境变量ANTHROPIC_BASE_URL。这个值填https://taotoken.net/api。注意结尾不要多加斜杠也不要带/v1之类的路径Claude Code 会自己拼接。再说 API Key。你需要先在控制台创建一个 key。控制台入口是 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 。创建后复制那串以sk-开头的字符串设置到环境变量ANTHROPIC_API_KEY。最后是 Model ID。Claude Code 里模型通过ANTHROPIC_MODEL指定。常见的 Claude 模型 ID 形如claude-sonnet-4-5这类具体以你账号可用的模型列表为准。填错 Model ID 会报模型不存在或者 404。三件套配好后Claude Code 的请求链路就是Claude Code 读取环境变量 → 用 Base URL 拼接请求地址 → 带上 API Key 做鉴权 → 指定 Model ID 调用。任何一环出错都会失败。这里要提醒一点不要把 API Key 硬编码进 SKILL.md 或者提交到 git。正确做法是放在 shell 的环境变量里或者用.env文件并加入.gitignore。skill 里如果需要调用模型走的是 Claude Code 自身的调用链路不需要在 skill 里再写 key。如果你用的是 Claude Code 的 settings 配置文件可以这样写。路径通常是~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你更习惯用 shell 环境变量在~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_MODELclaude-sonnet-4-5改完记得source ~/.zshrc让配置生效。验证是否生效可以运行echo $ANTHROPIC_BASE_URL看输出对不对。关于 Coding Plan如果你打算长期用 Claude Code 做编码和 Agent 任务可以了解 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它面向的是持续编码场景和单次对话的计费方式不同。配好三件套后先别急着写 skill先确认基础调用能通。运行一个最简单的对话请求看能不能拿到模型回复。基础链路通了再往上叠 skill 才有意义。这一步很多人跳过结果 skill 不触发时搞不清是 skill 写错了还是环境没配好排查起来很痛苦。3. 可复制配置SKILL.md 目录结构与字段逐项说明这一节给你可以直接复制的配置。先看目录结构一个标准 skill 在文件系统里就是一个文件夹my-skill/ ├── SKILL.md # 必需核心指令文件 ├── scripts/ # 可选可执行脚本 │ └── helper.py ├── references/ # 可选参考文档 │ └── api.md └── assets/ # 可选模板、静态资源 └── template.txtSKILL.md 是唯一必需的文件。scripts、references、assets 都是可选的只有核心指令里明确引用时才会被读取。SKILL.md 本身采用 YAML frontmatter Markdown 主体的结构。下面是一个完整可复制的示例--- name: api-review description: 用于审查内部 API 接口定义。当用户提到 API 审查、接口规范检查、请求参数校验、返回结构核对时使用。 disable-model-invocation: false --- # API 审查技能 ## 工作流程 1. 读取用户提供的 API 定义文件确认是 OpenAPI 还是自定义格式。 2. 检查请求参数命名是否用 snake_case必填项是否标注类型是否明确。 3. 检查返回结构是否统一包裹在 data 字段错误码是否规范。 4. 如果用户要求运行 scripts/check.py 做自动化校验。 5. 输出审查报告按「必须修改」「建议修改」「通过」三档分类。 ## 规则 - 所有字段命名必须用 snake_case禁止驼峰。 - 分页参数统一用 page 和 page_size。 - 错误返回必须包含 code 和 message 两个字段。 ## 参考 详细规范见 references/api.md。逐项说明字段name是技能名称同时会作为斜杠命令名。比如 name 是api-review用户在 Claude Code 里输入/api-review就能手动触发。命名用短横线连接的小写字母别用空格和中文。description是最关键的字段。它常驻上下文决定 Claude 什么时候自动触发这个 skill。写法要点先说功能这个技能用于做什么再说触发场景当用户提到什么关键词时使用。把用户可能说的原话关键词都列进去比如「API 审查」「接口规范检查」「参数校验」。description 写得太泛比如只写「用于 API 相关工作」Claude 判断不准触发率会很低。disable-model-invocation控制是否允许 Claude 自动调用。设为false表示允许自动触发设为true表示只能用户手动用斜杠命令触发。如果你不希望某个 skill 被自动命中比如它比较重或者有副作用就设为true。Markdown 主体部分就是核心指令层写工作流程、规则、约束。这一层只在 skill 被触发后才加载所以可以写得详细不用担心占用启动上下文。但也不要无限膨胀保持聚焦。关于存放位置按使用范围分三种个人 skill 放在~/.claude/skills/只对当前用户生效适合个人习惯。项目 skill 放在项目根目录的.claude/skills/团队成员共享适合项目规范和流程。插件 skill 通过 Claude Code Plugin 安装分发适合通用能力。如果你用 Cline MCP 或者 Codex 的 auth.json 做配置管理三件套同样要写全。Codex 的auth.json里对应的是 Base URL、Key、Model ID 三个字段缺一个都会鉴权失败。Cline MCP 的配置里也是同样的三件套逻辑只是字段名不同。核心原则不变连接地址、鉴权凭证、模型标识一个都不能少。配置写完后建议先用斜杠命令手动触发一次确认 skill 能被加载。手动能触发再测自动触发。这样排查问题时能快速定位是加载问题还是匹配问题。4. 验证请求与成功结果用本地日志确认 skill 触发时机配置写完怎么确认 skill 真的被触发了靠猜不行得看日志。这一节给你具体的验证操作步骤。Claude Code 在运行时会输出调试日志。开启详细日志的方式是设置环境变量ANTHROPIC_LOG或者在启动时加--debug参数。日志里会记录 skill 的扫描、匹配、加载过程。第一步确认 skill 被扫描到。启动 Claude Code 后日志里应该出现类似扫描 skills 目录的记录列出每个 skill 的 name 和 description。如果某个 skill 没出现在扫描列表里说明目录位置不对或者 SKILL.md 格式有问题。常见原因是 frontmatter 的---没写对或者文件不在正确的 skills 目录下。第二步确认元数据被加载。扫描后所有 skill 的 name 和 description 会进入上下文。日志里能看到加载了多少个 skill 的元数据。这一步是常驻的每个 skill 约 100 tokens。第三步触发 skill 并观察加载。在对话里输入一句会命中 description 的话比如你的 skill description 里写了「API 审查」就输入「帮我审查一下这个 API 定义」。日志里应该出现该 skill 主体被加载的记录包括加载了 SKILL.md 的哪些内容。第四步确认扩展资源按需加载。如果核心指令里引用了 scripts 或 references日志里会显示这些文件被读取的时机。没被引用就不该出现读取记录这正好验证了渐进式披露——不需要的资源完全不占上下文。一个典型的成功日志片段长这样示意[skills] scanned 3 skills from ~/.claude/skills [skills] loaded metadata: api-review, doc-gen, deploy-check [skills] matched skill: api-review (score: high) [skills] loading SKILL.md body for api-review [skills] reading references/api.md as requested by skill看到matched skill和loading SKILL.md body这两行就说明触发链路走通了。如果只有 scanned 和 loaded metadata没有 matched说明 description 没匹配上需要调整关键词。验证自动触发时注意一个细节Claude 判断是否触发 skill 是基于语义匹配不是简单关键词包含。所以 description 里写的关键词要贴近用户真实表达。你可以多试几种说法看哪种能稳定触发。手动触发验证更直接。输入/api-review如果 skill 正常加载日志里会显示手动触发记录。手动能触发说明 skill 本身没问题自动不触发就是 description 匹配的问题。再验证一下 MCP 协作边界。如果你的 skill 里指挥 Claude 调用 MCP 工具日志里应该能看到工具调用记录但不会看到 skill 去建立连接。连接是 MCP 层的事skill 只负责编排。如果日志里出现 skill 试图直接连接外部服务的记录说明你把连接逻辑错误地写进了 skill应该移到 MCP 配置里。验证模型调用是否正常可以用模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条测试消息确认基础链路通。基础链路通了skill 触发验证才有意义。实测下来日志验证最大的价值是区分「skill 没被扫描到」「元数据加载了但没匹配」「匹配了但主体加载失败」这三种情况。不看日志这三种情况表现都是「skill 没反应」排查起来全靠猜。看日志一眼就能定位到哪一层断了。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 逐条对照这一节把最常见的报错和排查方法列出来对照你的实际报错定位问题。401 鉴权失败。这是最高频的错误。原因通常是 API Key 没配、配错、或者过期。排查步骤先echo $ANTHROPIC_API_KEY确认环境变量有值再确认 key 没有多余空格或换行然后去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 key 状态正常。如果用的是 settings.json确认 JSON 格式没写错逗号、引号都要对。401 基本就是 key 的问题跟 skill 无关。local proxy failed。这个报错说明 Claude Code 尝试走本地代理但失败了。排查确认ANTHROPIC_BASE_URL设置正确值是https://taotoken.net/api没有多余路径。检查网络是否能正常访问该地址可以用curl -I https://taotoken.net/api看返回。如果本地有残留的代理配置检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY之类的设置干扰。清掉这些变量再试。reading choices 相关报错。这类报错通常出现在响应解析阶段说明返回结构不符合预期。排查确认 Model ID 填对了模型不存在时返回结构会异常。确认 Base URL 没有拼错路径拼错会返回非预期内容。如果日志里显示请求发出去了但解析失败重点查 Model ID 和 Base URL 这两个。OAuth 相关报错。如果你用的是需要 OAuth 的接入方式报错通常和 token 刷新有关。排查确认 OAuth 流程走完了token 没过期。如果同时配了 API Key 和 OAuth确认没有冲突。Claude Code 优先用哪种鉴权方式取决于配置混用容易出问题。建议二选一用 API Key 就不要再配 OAuth。skill 不触发。这个不算报错但最常见。排查顺序先看日志确认 skill 被扫描到再看元数据是否加载然后检查 description 是否包含用户可能说的关键词最后手动用斜杠命令测试。手动能触发就是 description 匹配问题手动也不能触发就是 skill 加载问题。skill 触发了但行为不对。说明核心指令层写得不够明确。检查 SKILL.md 主体的工作流程是否步骤清晰规则是否有歧义。可以在 skill 里加正反示例明确告诉 Claude 什么该做什么不该做。MCP 工具调用失败。如果 skill 里指挥 Claude 调用 MCP 工具但失败先单独测 MCP 工具能不能用再测 skill 编排。MCP 连接问题和 skill 逻辑问题要分开排查。MCP 配置里同样要写全 Base URL、Key、Model ID 三件套。上下文占用异常高。如果发现对话很快就满了检查是不是某个 skill 的元数据过大。description 写得太长会推高常驻开销。description 控制在几句话内把关键词写全但别写成长文。主体内容再长也不影响启动开销因为它是按需加载的。排查通用原则先确认基础链路三件套通再确认 skill 加载最后确认触发匹配。从下往上排查别一上来就改 skill 内容。接入相关的详细文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题可以先对照文档核对字段。6. 语义一致收尾把 skill 编排和 MCP 连接各归其位写到这里核心逻辑其实就一句话skill 管编排MCP 管连接Function Calling 管执行。三者各归其位别越界。我见过太多人把连接逻辑写进 skill结果 skill 变得又重又难维护。正确的做法是需要访问外部服务先在 MCP 层配好连接skill 里只写「调用某某工具」这样的编排指令。这样 skill 保持轻量连接配置独立管理改一处不影响另一处。渐进式披露的价值也在于此。它让 skill 可以写得很详细因为详细内容不占启动上下文。你可以把完整的工作流程、规则、示例都写进 SKILL.md 主体只在被触发时才加载。这就是为什么一个设计良好的 skill 既能保持轻量启动又能提供丰富指令。如果你要长期用 Claude Code 做编码和 Agent 任务把常用流程封装成 skill 是值得的投入。一次写好后续反复调用比每次重新解释流程省事得多。Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合持续编码场景。最后给一个实用技巧写完 skill 后先手动触发验证再测自动触发最后看日志确认扩展资源按需加载。这三步走完skill 基本就稳了。别跳过日志验证它是你区分「没扫描到」「没匹配」「加载失败」的唯一手段。