企业官网建设流程全解析

1. Claude Code skills 加载链路到底怎么跑：从 SKILL.md 到渐进式披露的完整拆解

Claude Code skills 是 Claude Code 里一种把「专业知识 + 工作流程 + 可执行脚本」打包成文件夹的扩展机制，核心文件是 SKILL.md。它能做什么？简单说，你写一次 SKILL.md，Claude 就能在后续对话里按需识别、按需加载、按需执行，而不是每次把全部指令塞进上下文。适合谁？适合那些反复给 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 编排整个流程。

举个具体例子。你有一个「发布版本」的 skill，SKILL.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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Keys 管理页是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建后复制那串以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_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key" export ANTHROPIC_MODEL="claude-sonnet-4-5"

改完记得source ~/.zshrc让配置生效。验证是否生效，可以运行echo $ANTHROPIC_BASE_URL看输出对不对。

关于 Coding Plan，如果你打算长期用 Claude Code 做编码和 Agent 任务，可以了解 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它面向的是持续编码场景，和单次对话的计费方式不同。

配好三件套后，先别急着写 skill，先确认基础调用能通。运行一个最简单的对话请求，看能不能拿到模型回复。基础链路通了，再往上叠 skill 才有意义。这一步很多人跳过，结果 skill 不触发时搞不清是 skill 写错了还是环境没配好，排查起来很痛苦。

3. 可复制配置：SKILL.md 目录结构与字段逐项说明

这一节给你可以直接复制的配置。先看目录结构，一个标准 skill 在文件系统里就是一个文件夹：

my-skill/ ├── SKILL.md # 必需：核心指令文件 ├── scripts/ # 可选：可执行脚本 │ └── helper.py ├── references/ # 可选：参考文档 │ └── api.md └── assets/ # 可选：模板、静态资源 └── template.txt

SKILL.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_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条测试消息，确认基础链路通。基础链路通了，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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到配置问题可以先对照文档核对字段。

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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合持续编码场景。

最后给一个实用技巧：写完 skill 后，先手动触发验证，再测自动触发，最后看日志确认扩展资源按需加载。这三步走完，skill 基本就稳了。别跳过日志验证，它是你区分「没扫描到」「没匹配」「加载失败」的唯一手段。