★ FEATURED ARTICLE 1. 从一次“技能不生效”说起agent-skills 在 Claude Code 里到底怎么跑如果你最近在 Claude Code 里写过skill.md大概率遇到过这种场景文件明明放在~/.claude/skills/下面name和description也填了可模型就是不用它或者用了却读不到你写的 reference 文件。更迷惑的是有时候它还会绕开 skill 直接调 MCP 工具结果参数对不上、报错一堆。这不是你写错了而是 agent-skills 的加载链路本身分了三层每一层的触发条件都不一样。我把它拆成一句话元数据常驻、指令按需、资源按需中的按需。理解这三层你才能判断问题出在“模型没看见技能”还是“看见了但没选中”还是“选中了但读不到 reference”。先把概念对齐。agent-skills 是 Anthropic 在 2025 年 10 月推出的能力12 月 18 日升级为开放标准VSCode、Codex、Cursor 陆续跟进。它解决的核心痛点是把重复的、结构化的任务要求从对话里抽出来变成模型可以自己翻阅的说明文档。你不再需要每次对话都粘贴一大段“总结会议要按参会人员、议题、决定来写”而是写一次skill.md模型在需要时自己读。它和 MCP 的关系官方那句话说得最清楚MCP connects Claude to data; Skills teach Claude what to do with that data。MCP 负责“取数据”skill 负责“教模型怎么处理数据”。两者不是替代关系而是上下游。很多场景下你要把 skill 和 MCP 一起用skill 定义流程和格式MCP 提供实时数据源。那为什么要把 endpoint 改到 TaoToken因为 Claude Code 默认走的是 Anthropic 官方接口国内直连经常超时而 skill 的加载、reference 的读取、MCP 工具的调用全都依赖模型接口的稳定响应。接口一抖skill 的“按需加载”就会表现为“模型没反应”。把 Base URL 切到 TaoToken 后链路稳定了你才能安心调试 skill 本身。下面我从 skill.md 结构讲到 MCP 配置再演示改 endpoint 后的连通性验证。2. TaoToken 前置Base URL、Key 与 Model ID 三件套怎么备齐在动 skill.md 之前先把模型接入层理顺。Claude Code 走的是 Anthropic 兼容协议所以你需要准备三样东西Base URL、API Key、Model ID。这三件套缺一个skill 加载就会在第一步卡住。Base URL 用https://taotoken.net/api注意这里不加任何 UTM 参数保持干净。API Key 去控制台生成路径是https://taotoken.net/console/api-keys生成后复制保存它只显示一次。Model ID 根据你用的模型填比如claude-sonnet-4-5这类具体以文档页为准文档在https://taotoken.net/doc。为什么强调“三件套要写全”因为 Claude Code 的配置里Base URL 和 Key 决定请求能不能发出去Model ID 决定模型能不能正确解析 skill 的元数据。我试过只改 Base URL 不改 Model ID结果模型返回的 tool_use 结构对不上skill 的 description 匹配直接失效。所以配置时三个字段一起写别偷懒。如果你用的是 Claude Code 的 settings 文件路径通常是~/.claude/settings.json。这个文件里可以配env字段把ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY写进去。注意 JSON 格式要严格逗号、引号错一个Claude Code 启动时就会报local proxy failed或者直接读不到配置。还有一种情况是你用 CC Switch 这类工具切换配置。CC Switch 的原理是帮你管理多套 Base URL 和 Key切换时改写 settings 文件。用 CC Switch 的话同样要把 Base URL、Key、Model ID 三件套填全否则切换后 skill 加载会静默失败——模型不报错但就是不用你的 skill。备齐之后先别急着写复杂 skill。用一个最小化的skill.md做连通性验证只写 name 和 descriptiondescription 里放一个独特的关键词比如“会议总结助手-测试版”。然后在 Claude Code 里问“你有哪些 Agent Skill”看它能不能列出这个名字。能列出说明元数据层通了列不出说明 Base URL 或 Key 有问题先回去查配置。这一步的验证动作很关键因为后面 reference 和 script 的调试都建立在“元数据层可见”的基础上。元数据层不可见你写再多 reference 都是白费。所以我的习惯是每换一次 endpoint先跑一遍“列出技能”的测试确认链路通了再往下走。3. 可复制配置skill.md 模板与 MCP 配置片段现在进入实操。先给一个可以直接复制的skill.md模板路径放在~/.claude/skills/会议总结助手/skill.md。注意文件夹名必须和name字段一致这是 Claude Code 的硬性要求不一致会导致技能加载失败。--- name: 会议总结助手 description: 用于总结会议内容输出参会人员、议题、决定三部分。当用户提到会议记录、会议纪要、总结会议时使用。 --- # 会议总结助手 ## 指令 你必须按照以下格式输出会议总结 1. 参会人员列出所有参会者姓名 2. 议题列出讨论的主要议题 3. 决定列出达成的决定 ## 示例 输入老陈让小李订酒店预算1200一晚。 输出 - 参会人员老陈、小李 - 议题酒店预订 - 决定小李负责预订预算1200一晚 ## 财务提醒规则 仅在提到钱、预算、采购费用时触发。触发时读取 集团财务手册.md根据内容指出金额是否超标并明确审批人。这个模板里---包起来的是元数据层下面的正文是指令层。集团财务手册.md是 reference放在同一个文件夹下。reference 的特点是条件触发只有模型读完指令层、判断出需要查财务时才会去读这个文件。如果会议内容跟钱无关这个文件就躺在硬盘里不占 token。接下来是 MCP 配置片段。MCP 工具调用需要单独配置通常写在~/.claude/mcp.json或者 settings 的mcpServers字段里。下面是一个标准的 MCP server 配置以文件系统工具为例{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents ] } } }如果你要把 MCP 的请求也走 TaoToken需要在 MCP server 的环境变量里注入 Base URL 和 Key。有些 MCP server 支持env字段{ mcpServers: { custom-tool: { command: node, args: [/path/to/server.js], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } } } }注意这里的三件套又出现了Base URL、Key、Model ID。MCP server 如果自己调模型就必须带全这三个否则会报 401 或者reading choices错误。reading choices这个报错通常出现在响应结构不符合预期时根源往往是 Model ID 填错或者 Base URL 指向了不兼容的接口。配置写完后Claude Code 启动时会读取这些文件。如果 JSON 格式有误启动日志里会有local proxy failed或者OAuth相关提示。OAuth 报错一般是因为 Key 失效或权限不足去控制台重新生成一个即可。还有一个细节skill 的 script 部分。如果你在 skill 里写了upload.pyClaude Code 只会执行它不会读取它的内容。这意味着脚本写一万行也不占上下文。但前提是你在skill.md里把执行方法说清楚比如“运行 upload.py 并传入总结内容作为参数”。说不清楚Claude Code 可能会去读代码那就占 token 了。4. 验证请求从“列出技能”到“触发 reference”的完整动作配置写好了现在验证。第一步打开 Claude Code输入“你有哪些 Agent Skill”。如果返回列表里有“会议总结助手”说明元数据层加载成功。这一步失败的话检查文件夹名和name是否一致以及 settings 里的 Base URL 是否生效。第二步触发指令层。输入“总结以下会议内容老陈让小李订酒店预算1200一晚。”观察 Claude Code 的反应。正常情况下它会先请求使用“会议总结助手”这个 skill你同意后它读取skill.md的指令层然后按格式输出。如果它直接开始瞎编说明指令层没加载可能是 description 写得不够明确模型没匹配上。第三步触发 reference。把会议内容改成涉及钱的场景比如“老陈让小李订1200一晚的酒店走采购流程”。这时 Claude Code 应该先读指令层发现财务提醒规则被触发然后请求读取集团财务手册.md。你同意后它会把手册内容和会议内容结合输出带财务提醒的总结。如果它没读 reference检查skill.md里的触发条件是否写清楚比如“仅在提到钱、预算、采购费用时触发”。第四步触发 script。在会议内容里加上“并上传到服务器”。Claude Code 应该请求执行upload.py。注意它不会读脚本内容只关心执行结果。如果它去读脚本了说明你在skill.md里没写清楚执行方法。整个验证链路走通后你会看到三个角色在协作用户、Claude Code、背后的模型。用户发请求Claude Code 把请求和所有 skill 的名称描述发给模型模型选中某个 skillClaude Code 读取对应skill.md的指令层再发给模型模型生成响应。reference 和 script 是在这个过程中按需插入的。这里有个容易踩的坑如果你同时装了多个 skill元数据层会带上所有 skill 的名称和描述。模型每次回答前都会看这份“目录”所以 description 要写得精准避免多个 skill 抢同一个请求。比如“会议总结助手”和“文档总结助手”如果 description 都写“总结内容”模型就可能选错。验证通过后你可以把 endpoint 改到 TaoToken 的动作再确认一遍在 settings 里把ANTHROPIC_BASE_URL设为https://taotoken.net/apiKey 用控制台生成的Model ID 填对。然后重启 Claude Code重新跑一遍“列出技能”的测试。如果列表正常返回说明整条链路在 TaoToken 上跑通了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth调试 agent-skills 时报错基本集中在四类。下面逐个对照真实场景给出排查路径。401 错误通常出现在请求发出但鉴权失败时。原因有三个Key 没填、Key 填错、Key 过期。去https://taotoken.net/console/api-keys重新生成一个复制时注意不要带空格。如果用的是 CC Switch检查切换后 settings 文件里的 Key 是否被覆盖。local proxy failed这个报错说明 Claude Code 的本地代理层没起来。常见原因是 settings.json 格式错误比如多了一个逗号、少了一个引号。用 JSON 校验工具过一遍。另一个原因是 Base URL 写成了https://taotoken.net/api/带了尾部斜杠有些版本会因此拼接出错误路径。去掉尾部斜杠即可。reading choices这个报错出现在响应解析阶段模型返回的结构不符合预期。根源通常是 Model ID 填错或者 Base URL 指向了不兼容的接口。检查三件套是否写全Model ID 是否和文档一致。如果用的是 MCP server 自己调模型检查env里的ANTHROPIC_MODEL是否填对。OAuth 相关报错一般提示 token 无效或权限不足。先确认 Key 是否有效再确认 Base URL 是否指向https://taotoken.net/api。如果都没问题可能是网络层的问题换个时间重试。注意不要用任何代理工具直连即可。除了这四类还有一个隐蔽问题skill 文件夹名和name不一致。Claude Code 不会报错但技能就是加载不出来。检查~/.claude/skills/下的文件夹名确保和skill.md里的name完全一致包括大小写。另一个隐蔽问题是 reference 文件路径写错。skill.md里写“读取集团财务手册.md”但文件实际叫财务手册.md模型读不到就会跳过表现为“财务提醒没出现”。检查文件名和路径确保在同一个 skill 文件夹下。如果你用 Cline MCP 或 Codex 的auth.json同样要保证三件套齐全。Cline MCP 的配置里Base URL、Key、Model ID 缺一个都会导致工具调用失败。Codex 的auth.json里字段名可能不同但逻辑一样指向 TaoToken 的 Base URL带上有效 Key指定 Model ID。排查顺序建议先看元数据层是否可见再看指令层是否触发最后看 reference 和 script 是否按需加载。一层一层往下查比一上来就改代码高效得多。6. 语义一致 CTA把 skill 和 MCP 的链路跑顺之后链路跑顺之后你会发现 agent-skills 的真正价值不在“写文档”而在“按需加载”带来的 token 节省和流程标准化。元数据层常驻指令层按需reference 和 script 再按需三层结构让模型在需要时才读该读的内容。MCP 负责取数据skill 负责教模型怎么处理数据两者配合才能把自动化做扎实。如果你还在调试接入层先去https://taotoken.net/console/api-keys把 Key 备好再对照https://taotoken.net/doc确认 Model ID 和 Base URL 的写法。接入文档里有完整的配置示例照着填不会错。想先验证模型对话是否正常可以用https://taotoken.net/api配合模型对话功能跑一轮确认响应结构没问题再回到 Claude Code 里调 skill。模型对话的入口在https://taotoken.net/api对应的对话页具体路径看文档。如果你打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 更划算入口在https://taotoken.net/coding-plan。它适合高频调用、多 skill 并行的场景比按次计费省心。最后提醒一句skill 的 script 只执行不读取reference 读取才占 token。写 skill 时把执行方法说清楚能省下不少上下文。链路通了之后剩下的就是不断迭代你的skill.md让模型越来越懂你的活。
阅读完成 · 觉得有帮助？
