企业官网建设流程全解析

1. 为什么你的 Claude Code 里 Skills 总是“不触发”

很多人第一次接触 Claude Code 的 Agent Skills，都会经历同一个困惑：明明按文档建好了目录、写好了SKILL.md，可对话里输入/却看不到自己的 Skill，或者 Claude 压根不自动加载它。我试过在一个 monorepo 里放了三个 Skill，结果只有项目根目录那个生效，子目录里的两个像消失了一样。问题不在 Claude，而在于 Skills 的发现机制、存储位置和 frontmatter 字段三者必须同时对上。

先把概念理清。Agent Skills 是一套开放标准，用来给 AI Agent 注入新的能力和领域知识；Claude Skills 是这套标准在 Claude Code 里的具体实现。每个 Skill 的核心是一个SKILL.md文件，里面用 YAML frontmatter 声明元数据（name、description等），下面是给 Claude 看的执行指令。它最大的特点是渐进式披露：启动时只加载每个 Skill 的name和description，只有当任务匹配到描述时，才把完整的SKILL.md内容注入上下文，需要脚本时再按需读取scripts/或references/。这意味着你可以放几十个 Skill 而不炸上下文。

那为什么“不触发”？三个高频原因。第一，目录位置错了。个人级 Skill 必须放在~/.claude/skills/<skill-name>/SKILL.md，项目级放在.claude/skills/<skill-name>/SKILL.md，插件级则是<plugin>/skills/<skill-name>/SKILL.md。放错层级，Claude 根本扫不到。第二，description写得太抽象，比如只写“帮助处理代码”，Claude 无法判断何时该用。第三，name里混入了大写字母或下划线，而规范只允许小写字母、数字和连字符，最多 64 个字符。

还有一个容易被忽略的点：.claude/commands/deploy.md和.claude/skills/deploy/SKILL.md都会创建/deploy，工作方式相同，自定义命令其实已经合并进 Skills。如果你两边都写了，Skill 优先。搞清楚这些，后面的配置才不会白费功夫。

这篇会带你从零跑通一条完整链路：写一个可复用的SKILL.md，用 Subagent 做协作编排，再通过统一 Key/API 通道接入 TaoToken 完成端到端验证。全程可复制，跟着敲就行。

2. TaoToken 前置准备：统一 Key 与 API 通道

在动手写 Skill 之前，先把模型通道打通。Claude Code 默认走 Anthropic 官方端点，但很多人在本地或团队环境里需要一个统一的 Key/API 通道来管理调用。TaoToken 提供的就是这样一个入口：官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。

你需要准备三样东西，我把它叫做“三件套”：Base URL、API Key、Model ID。这三者在任何接入场景里都要写全，缺一个就会报错。

第一步，拿到 API Key。登录后进入控制台，在 API Keys 页面创建一个新 Key。建议按项目命名，比如claude-code-skills-demo，方便后续排查。创建后立刻复制保存，页面刷新后就看不到了。

第二步，确认 Base URL。TaoToken 的 API 根地址是https://taotoken.net/api，注意这里不加任何 UTM 参数，保持干净。在 Claude Code 里配置时，通常需要的是兼容 Anthropic 的端点路径，具体以接入文档为准。

第三步，选 Model ID。在模型对话页面可以试跑不同模型，确认哪个适合你的编码场景。把选定的 Model ID 记下来，比如claude-sonnet-4-5这类标识。

配置方式有两种。一种是环境变量，适合临时验证：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的Key" export ANTHROPIC_MODEL="你的ModelID"

另一种是写进 Claude Code 的 settings 文件，适合长期使用。项目级配置放在.claude/settings.json，个人级放在~/.claude/settings.json。下面是一个可复制的片段，路径和字段名保持原样：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }

如果你用的是 Codex 系工具，配置写在~/.codex/auth.json里，结构不同但三件套一样要齐：

{ "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-你的Key", "model": "claude-sonnet-4-5" }

这里要提醒一句：不要把 Key 硬编码进SKILL.md或提交到 Git。Skill 文件是给 Claude 读的指令，不是密钥仓库。Key 只放在 settings 或环境变量里，通过allowed-tools控制 Skill 能调用哪些工具，两者职责分开。

配置完成后，先别急着写 Skill，用一次最简单的请求验证通道是否通。这一步很关键，通道不通，后面所有 Skill 调试都是白费。

3. 可复制配置：SKILL.md 模板与 Subagent 编排

通道通了，现在写第一个真正可用的 Skill。我选一个实用场景：代码解释器。它能把一段代码用类比和 ASCII 图讲清楚，适合新人 review 或快速理解陌生模块。

先建目录。个人级 Skill 对所有项目生效：

mkdir -p ~/.claude/skills/explain-code

然后创建~/.claude/skills/explain-code/SKILL.md。注意 frontmatter 用---包裹，name全小写加连字符，description要写清楚“何时使用”，最好包含用户可能说的自然语言关键词：

--- name: explain-code description: 使用可视化图表和类比来解释代码。当解释代码工作原理、讲解代码库，或者用户问“这是如何工作的？”时使用。 allowed-tools: Read Grep Glob --- 在解释代码时，请始终包含以下内容： 1. **先打个比方**：把这段代码比作日常生活中的某个事物 2. **画个示意图**：用 ASCII 字符画展示流程、结构或关系 3. **逐行讲解代码**：一步步说明发生了什么 4. **指出易错点**：常见的错误或误解是什么？ 解释要保持对话式的自然风格。对于复杂的概念，可以使用多个类比。

这里allowed-tools: Read Grep Glob表示这个 Skill 活动时，Claude 只能用这三个只读工具，无需每次批准，既安全又省事。如果你希望这个 Skill 只能手动触发、不让 Claude 自动加载，加上disable-model-invocation: true。

接下来是 Subagent 编排。Subagent 的价值在于把任务丢进一个隔离的上下文里执行，不污染主对话。在 Skill 里启用它，只需在 frontmatter 加context: fork，再用agent字段指定用哪个 subagent：

--- name: deep-research description: 彻底研究一个主题。当需要深入调查代码库、追踪调用链或理解复杂模块时使用。 context: fork agent: Explore allowed-tools: Read Grep Glob --- 彻底研究 $ARGUMENTS： 1. 使用 Glob 和 Grep 找到相关文件 2. 阅读并分析代码 3. 用具体的文件引用总结发现

agent: Explore表示用内置的 Explore 类型 subagent 执行，它擅长探索代码库。如果不写agent，默认用general-purpose。你也可以在.claude/agents/下定义自己的 subagent，然后在 Skill 里引用。

这里有个关键区别要讲清楚。context: fork的 Skill，系统提示来自 agent 类型，任务是SKILL.md的内容；而带 skills 的 subagent，系统提示是 subagent 的 markdown 正文，任务是 Claude 委派的消息。两者方向相反，别搞混。context: fork只对包含明确指令的 Skill 有意义，如果你的 Skill 只是 API 约定这类参考资料，fork 出去后 subagent 只收到指令没有可操作任务，会返回无意义输出。

参数传递用$ARGUMENTS。比如/deep-research 用户认证模块，$ARGUMENTS就被替换成“用户认证模块”。也支持按索引访问：$ARGUMENTS[0]、$ARGUMENTS[1]，或者简写$0、$1。如果 Skill 里没写$ARGUMENTS，Claude Code 会把ARGUMENTS: <你的输入>追加到内容末尾，保证参数不丢。

还有一个进阶玩法：动态注入上下文。用!反引号语法，在 Skill 内容送给 Claude 之前先执行 shell 命令，把输出替换进去。比如：

--- name: pr-summary description: 总结一个 pull request 的变更 context: fork agent: Explore allowed-tools: Bash(gh *) --- ## Pull request 上下文 - PR diff: !`gh pr diff` - PR 评论: !`gh pr view --comments` - 变更文件: !`gh pr diff --name-only` ## 你的任务 总结这个 pull request……

Claude 看到的是命令执行后的真实数据，而不是命令本身。这个预处理在托管环境里可以用disableSkillShellExecution关掉，替换成[shell command execution disabled by policy]。

4. 验证请求：从 / 菜单到成功结果

配置写完，必须验证。很多人跳过这步，结果 Skill 不生效还找不到原因。验证分三层：菜单可见性、手动调用、自动触发。

第一层，看/菜单。在 Claude Code 里输入/，如果explain-code出现在列表里，说明目录位置和 frontmatter 解析都对了。看不到的话，先检查路径是不是~/.claude/skills/explain-code/SKILL.md，再检查name有没有大写字母。

第二层，手动调用。直接输入：

/explain-code react-agent-example

预期结果是 Claude 加载完整的SKILL.md，按四步结构输出：类比、ASCII 图、逐行讲解、易错点。如果只返回一句“我不确定”，多半是description没匹配上，或者 Skill 内容为空。

第三层，自动触发。不提 Skill 名字，直接问：

这个 react-agent-example 是如何工作的？

如果description写得够具体，Claude 会自动匹配到explain-code并加载。这一步最能检验描述质量。

现在验证 Subagent 编排。用deep-research试：

/deep-research 用户认证模块

预期行为：Claude 创建一个隔离的 subagent 上下文，Explore agent 用 Glob 和 Grep 扫描代码，读取分析后把总结返回主对话。你会在输出里看到具体的文件引用，而不是泛泛而谈。

最后验证通道。在 Skill 执行过程中，所有模型请求都走你配置的 Base URL。如果通道有问题，这一步会直接暴露。可以开 debug 日志观察：

claude --debug api

这会显示 Claude 实际收到的系统提示和对话内容，方便你确认请求确实发到了 TaoToken 端点。看到正常的请求响应，说明三件套配置正确。

一个完整的成功链路应该是：输入/deep-research 用户认证模块→ Skill 被识别 → subagent 隔离上下文启动 → 模型请求经 TaoToken 通道发出 → 返回带文件引用的总结。任何一环断了，对照下一节的报错排查。

5. 本篇常见错排查：401、local proxy failed 与 OAuth

调试 Skill 时，报错信息往往指向配置而非代码。下面是我踩过的几个坑，对照着查。

401 Unauthorized。最常见，几乎都是 Key 问题。检查三件套里的 API Key 是否复制完整、有没有多余空格、是否已过期。如果你把 Key 写进了settings.json，确认 JSON 格式没写错，比如漏了引号或逗号。环境变量和 settings 同时存在时，注意优先级，别让旧的空 Key 覆盖了新的。

local proxy failed。这个报错通常出现在 Base URL 配置错误时。确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api，不要多加路径后缀，也不要带 UTM 参数。如果你在本地跑过其他代理工具，先确认没有残留的环境变量干扰。检查方法：

echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY

输出为空或指向旧地址，就是问题所在。

reading choices 相关报错。这类错误说明请求发出去了，但响应格式不符合预期。常见原因是 Model ID 写错，或者端点路径不对。回到模型对话页面确认 Model ID 拼写，再核对接入文档里的端点路径。三件套里 Model ID 最容易写错，因为它不像 Key 那样有固定前缀。

OAuth 报错。如果你之前用官方账号登录过 Claude Code，本地可能残留 OAuth 凭证，和新的 API Key 配置冲突。清理方式是在 settings 里显式指定 API Key 模式，或者删除旧的凭证缓存。具体路径以你的系统为准，通常在用户目录的配置文件夹下。

Skill 触发了但结果不对。这不是通道问题，是 Skill 内容问题。检查description是否太宽泛导致误触发，必要时加disable-model-invocation: true改成纯手动。如果 Skill 描述被截断，注意每个条目上限 250 字符，整体预算默认是上下文窗口的 1%，回退值 8000 字符，可以用SLASH_COMMAND_TOOL_CHAR_BUDGET调整。

Subagent 返回空结果。多半是context: fork用在了纯参考资料型 Skill 上。fork 出去的 subagent 只收到指令没有可操作任务，自然没输出。解决办法是给 Skill 加上明确的任务步骤，或者去掉context: fork让它留在主对话。

排查顺序建议：先确认通道（401、proxy、choices），再确认 Skill 发现（菜单、路径、name），最后确认触发逻辑（description、fork）。按这个顺序走，大部分问题十分钟内能定位。

6. 把 Skills 用起来：接入文档与长期编码

跑通一个 Skill 只是开始。真正提升效率的是把常用工作流都沉淀成 Skill，再用 Subagent 编排成流水线。比如代码审查、部署、PR 总结、数据可视化，每个都可以是一个独立 Skill，通过allowed-tools控制权限，通过context: fork隔离上下文。

如果你在验证模型阶段，想先试跑不同模型再决定用哪个写 Skill，可以去模型对话页面直接对比输出质量。确定长期编码或 Agent 编排方案后，Coding Plan 更适合持续使用，能覆盖多轮对话和复杂任务。接入过程中遇到配置问题，API Keys 页面管理密钥，接入文档里有完整的端点说明和示例。

把三件套写全、把 Skill 目录放对、把 description 写具体，这三件事做到，Claude Code 的 Agent Skills 就能稳定为你工作。剩下的就是不断往~/.claude/skills/里加你自己的 Skill，让 Claude 越来越懂你的项目。