企业官网建设流程全解析

1. 三个 Skill 目录换机器后先哑一轮，Claude Code 卡在哪

TaoToken（https://taotoken.net/?utm_source=taotoken_aicg_blog_end）是给 Claude Code 配 Agent Skills 时拿 Key 的地方。把 adding-cli-command、reviewing-cli-command、generating-cli-tests 三个目录放进项目的 .claude/skills/ 之后，本机上的 Claude Code 会有很直观的变化：说一句“加一个 edit 命令”，它不再随手甩一段 Typer 代码，而是先去找 adding-cli-command/SKILL.md，照里面的模板和约定来；说“给 list 写测试”，它走 generating-cli-tests；让它审一遍刚写完的命令，它按 reviewing-cli-command 的检查项过质量、安全和项目约定。

这些行为全部依赖同一个前置条件：Claude Code 得能正常调到模型。Skill 是按需加载的文本资源，只有当请求真的发出去、模型读到 description 判断“这个任务该用哪个 Skill”，整套链路才转得起来。Base URL 不通、Key 没配、复制 Key 时多带了一个换行，Skill 目录再完整也只是躺在磁盘上不动。换机器、重装环境、把仓库 clone 到同事电脑上，第一件要重做的事恰好就是这一层，而不是重写 Skill。

原文里这一步的写法是配 ANTHROPIC_API_KEY。这篇把这一步换掉：Key 从 TaoToken 创建，Base URL 指向兼容通道，环境变量里只放这一枚 Key。改动很小，但换机器时的动作从“翻旧笔记找 Key”变成“去控制台重新建一枚”，可控得多。

1.1 adding-cli-command、reviewing-cli-command、generating-cli-tests 各管什么

三个 Skill 的分工落在同一个 Task CLI（基于 Typer 的 todo 应用）上，边界划得比较清楚。

adding-cli-command 管“怎么加”。它提供单命令、命令组、破坏性命令三类模板，规定参数用 Annotated 声明，输出统一走 display，退出码怎么设计，破坏性操作必须带 --force 并做二次确认。没有这个 Skill，AI 照样能写命令，但参数风格、输出方式、退出码会和项目里已有的命令对不上，后面审查时全是缝。

reviewing-cli-command 管“怎么审”。检查项覆盖代码质量、安全边界和项目约定三块。它不产出新代码，只负责挑毛病，比如某个破坏性命令漏了确认、某个参数没做类型校验、异常路径没返回约定退出码。

generating-cli-tests 管“怎么测”。为命令生成测试用例，覆盖正常路径、参数边界和破坏性操作的前置条件。生成的测试要在本地跑，跑出来的报错再贴回对话，让它按 Skill 里的约定改成下一版。

1.2 Skill 被“看见”的前提是这一层调用先通

把这条链路想成寄快递：Skill 是包裹里的说明书，Claude Code 是快递员，模型是收件人。说明书再详细，运单填错也送不到。ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 就是运单上的两项，缺一项或填错一项，模型根本读不到 Skill 的 description，“自动选用 Skill”这件事自然也无从发生。

所以排查顺序一直是自下而上的：先确认 Base URL 和 Key 能打通，再确认 Skill 目录位置对不对，最后才怀疑 description 写得够不够明确。很多人反着来，一发现 AI 没按规范写命令就去改 SKILL.md，改了三版也没用，因为请求压根没成功。

2. SKILL.md 里哪些字段决定它会不会被自动选中

Skill 能不能被 Claude Code 自动挑中，主要看两份东西：frontmatter 里的 name 和 description，以及正文里对流程、输入输出和边界情况的交代。这一点在 adding-cli-command 这类“有明确触发时机”的 Skill 上尤其明显——它不需要在每轮对话都加载，只有在“添加或修改 CLI 命令”这个动作出现时才该被读进来。

2.1 name 与 description：描述写偏了，AI 就不选它

frontmatter 必填两个字段。name 要求最多 64 个字符，小写字母、数字和连字符，且要和父目录名一致，建议用动名词形式。description 上限 1024 个字符，要同时说清“做什么”和“什么时候用”。

--- name: adding-cli-command description: 在 Task CLI 中添加或修改 Typer 命令时使用。提供单命令、命令组、破坏性命令三类模板，规定参数使用 Annotated、输出走 display、设计退出码，破坏性操作必须带 --force 与确认。 ---

description 是模型判断“要不要读这个 Skill”的主要依据，它不写清触发场景，后面正文再规范也没用。拿 adding-cli-command 举例，如果描述只写“提供 Typer 模板”，用户说“加一个 edit 命令”时，模型未必会把这句话和这个 Skill 关联起来；补上“添加或修改 CLI 命令时使用”这层场景，命中率才会稳定。

reviewing-cli-command 和 generating-cli-tests 同理。前者要写清触发时机是“对 CLI 实现做代码审查”，后者要写清是“为 CLI 命令生成测试”。三个 description 之间最好避免重叠，否则模型会在两个 Skill 之间摇摆。

2.2 Body、references 与 scripts：模板和规则分别放哪

正文没有强制格式，但课程提倡的写法是分步骤说明，写清输入、输出格式和示例，再补常见边界情况。SKILL.md 本身建议控制在 500 行以内，超出部分拆到 references/ 和 scripts/ 里。

adding-cli-command 里，三类 Typer 模板适合直接放正文，因为模型每次都要照抄；参数命名规则、退出码对照表这类内容偏长，适合放 references/；如果有脚手架脚本，就放 scripts/ 并写清依赖和错误处理，同时在 SKILL.md 里说明这个脚本是“执行”还是“仅作参考”。

引用只做一层，不要出现 SKILL.md 引 references 里某个文件、那个文件再引第三个文件的情况。路径统一用正斜杠，跨平台时不至于找不到。

3. 在 ~/.claude/settings.json 里把 Claude Code 接到 TaoToken

Skill 目录摆好之后，接下来的动作就是把 Claude Code 这层接到 https://taotoken.net/api。这一步和写 Skill 是两件事，改的是工具配置，不碰 .claude/skills/ 下的任何文件。

3.1 先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建 Key

打开 TaoToken，注册登录后进控制台创建 API Key，复制出来的那串就是后面要填的 YOUR_API_KEY。模型 ID 不要凭记忆写，去模型广场看当时列表里有什么，挑一个适合日常写代码的填进去；这篇的配置里统一用 YOUR_MODEL_ID 占位，实际值以模型广场当时列表为准。

Key 的保存习惯值得花半分钟想清楚。如果只在某台机器上用，可以放在 shell 的启动文件里；如果要在多台机器、多个项目之间切换，就把它当成环境变量管理，别硬编码进仓库里的任何文件。settings.json 里放 Base URL 和模型 ID，Key 从系统环境变量读，是相对省心的组合。

3.2 settings.json 的 env 写法

Claude Code 读 ~/.claude/settings.json 里的 env 段。三个变量分别是 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "YOUR_MODEL_ID" } }

两个容易写错的地方。第一，Base URL 末尾不要再接 /v1，写满就是 https://taotoken.net/api；多加了 /v1，请求路径会变成 /api/v1/...，报错信息通常不会直接告诉你“多了个后缀”，只会返回路径不存在。第二，ANTHROPIC_AUTH_TOKEN 填的是刚才创建的那枚 Key 本身，不要加 Bearer 前缀，也不要在前后留空格或换行。

如果更习惯用环境变量而不是 settings.json，等价写法如下，写在 shell 的启动文件里即可：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY" export ANTHROPIC_MODEL="YOUR_MODEL_ID"

两处同时配置时，生效优先级以 Claude Code 当时的读取顺序为准，为避免自己绕晕，建议只保留一处。

3.3 多机器切换与 taotoken cc 这条快捷路径

换机器时重复改 env 段挺烦。如果原文工作流里本来就用了命令行，可以用 CLI 直接带参数起 Claude Code：

npm install -g @taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID

这里 -u 后面填的是接口地址，末尾同样不带 /v1，也不要把官网的 UTM 参数拼上去；-m 后面跟模型广场里真实存在的模型 ID。这条命令适合临时切环境，长期使用还是写进 settings.json 或环境变量更省事。

还有一种折中是分项目配置。把通用部分放全局 settings.json，项目里如果要用不同模型，就在项目的 .claude/settings.json 里覆盖 ANTHROPIC_MODEL，Key 和 Base URL 保持全局一份，避免每个仓库都塞一遍敏感信息。

4. 一次“加 edit 命令”从提示词到 Skill 命中

配置通不通，用一次真实任务就能验出来，最快的方式是让它加一个 edit 命令，然后看它有没有读到 adding-cli-command。

4.1 提示词要写到什么程度

提示词不需要把 Typer 的用法复述一遍，那正是 Skill 要替你做的事。一句“给 Task CLI 加一个 edit 命令，按项目现有约定来”就够了。剩下的模板选择、参数声明、输出方式、退出码，由 adding-cli-command 在加载后补齐。

值得留意的是“按项目现有约定来”这类措辞并不总是必要，但它能帮模型把当前任务和 description 里的“添加或修改 CLI 命令”对齐。如果三次里有一次没命中，先检查 description 是否覆盖了“修改”这个动作，再看是否需要手动调用一次 /adding-cli-command 做验证。

4.2 子代理绑定 reviewing-cli-command 的方式

如果项目里配了 code-reviewer 这类子代理，要记得子代理不会继承主对话的 Skill，必须在定义里显式列出。:

--- name: code-reviewer description: 对 CLI 命令实现做代码审查，检查质量、安全与项目约定。 skills: - reviewing-cli-command ---

字段具体写法以 Claude Code 当时的文档为准。加完这个字段，让它审查刚生成的 edit 命令，输出才会按 reviewing-cli-command 的检查项走；不写这一行，子代理只能靠通用编码经验挑毛病，项目里的约定它看不到。

4.3 list 写测试交给 generating-cli-tests

测试这一环最容易看出 Skill 的价值。同样是“给 list 写测试”，没有 Skill 时产出的是通用 pytest 用例，边界条件靠模型临场发挥；有 generating-cli-tests 时，它按既定覆盖面生成正常路径、参数边界和破坏性操作前置条件的用例。

生成的测试要在本地跑，把报错原样贴回对话，让下一轮修改仍然在 Skill 的规则内进行。不要指望 Claude Code 直接连上什么环境去执行测试，它负责生成和解释，执行这一步留在本地更稳。

新增或修改 Skill 之后，记得重启一次 Claude Code，否则新目录可能不会被加载。这条在原文里也提过，是新手最容易忽略的一步。

5. 调用失败与 Skill 不命中的排查顺序

出错时别急着改 Skill，先把调用层的问题排干净，再往上找。下面三类是这套配置里最常见的。

5.1 401 与模型 ID 写错分别长什么样

401 基本只对应一件事：ANTHROPIC_AUTH_TOKEN 不对。可能是 Key 复制时带了空格、换行，可能是环境变量没生效，也可能是 settings.json 和环境变量同时存在、实际读的不是你以为的那一份。检查方式很直接——把 Key 拿到模型对话里发一条消息，看能不能通，能通说明 Key 本身没问题，问题出在 Claude Code 的读取环节。

模型未找到这类报错，通常是把模型 ID 写成了记忆里的名字。以模型广场当时列表为准，复制粘贴最稳。还有一个隐蔽情况是 Base URL 末尾被习惯性加了 /v1，请求路径整体偏移，日志里看到的是路径不存在而不是模型问题，回头检查第一行配置就能发现。

排障时建议一次只改一个变量：先确认 Base URL 和 Key，再确认模型 ID，最后才回到 Skill 目录和 description。把三个变量同时改，改对了也不知道是哪个起的作用。

5.2 Skill 明明在目录里却没被选中

先确认 .claude/skills/ 的层级对不对，每个 Skill 一个子目录，子目录里是 SKILL.md，不要多套一层。再确认新增之后重启过 Claude Code。

如果这两条都满足，问题多半在 description 的触发场景写得不够具体，或者三个 Skill 的描述互相重叠。可以手动调用一次 /adding-cli-command，看 Skill 本身能否正常工作——能正常工作说明文件没问题，只是自动匹配没做好；手工调用也报错，那就要回到 frontmatter 的格式检查。

还有一种情况是任务表述太模糊，比如只说“改一下命令”，没提是新增还是修改，模型可能既没选 adding-cli-command 也没选 reviewing-cli-command。提示词里带上动作词，命中率会明显提升。

6. 跑通之后，在控制台对一下这次 Claude Code 的调用

配置保存并重启之后，先去 TaoToken 模型对话 用同一枚 Key 发一条测试消息，确认模型 ID 和 Base URL 都没填错。这一步能通，再回到项目里跑“加一个 edit 命令”，看 Claude Code 是否真的读到了 adding-cli-command。

接着让它审一遍刚生成的命令、再给 list 写一组测试，三个 Skill 各走一遍，链路基本就算验完了。要长期在项目里用，可以打开 Coding Plan 看套餐是不是够用；Key 后续要新建或轮换，在 控制台 API Keys 里操作；环境变量和 settings.json 的字段对照，见 Claude Code 接入文档。

回控制台看一眼这次调用有没有记上账，心里对 Token 消耗就有了具体数量，比凭感觉估要靠谱。换机器时照着这套走一遍，Skill 目录从仓库里 clone 下来，Key 重新建一枚，剩下的就不用再动了。