企业官网建设流程全解析

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 和 description，description 里放一个独特的关键词，比如“会议总结助手-测试版”。然后在 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.py，Claude 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 的名称描述发给模型，模型选中某个 skill，Claude Code 读取对应skill.md的指令层，再发给模型，模型生成响应。reference 和 script 是在这个过程中按需插入的。

这里有个容易踩的坑：如果你同时装了多个 skill，元数据层会带上所有 skill 的名称和描述。模型每次回答前都会看这份“目录”，所以 description 要写得精准，避免多个 skill 抢同一个请求。比如“会议总结助手”和“文档总结助手”如果 description 都写“总结内容”，模型就可能选错。

验证通过后，你可以把 endpoint 改到 TaoToken 的动作再确认一遍：在 settings 里把ANTHROPIC_BASE_URL设为https://taotoken.net/api，Key 用控制台生成的，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，让模型越来越懂你的活。