1. 三个 Skill 目录换机器后先哑一轮Claude Code 卡在哪TaoTokenhttps://taotoken.net/?utm_sourcetaotoken_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 并做二次确认。没有这个 SkillAI 照样能写命令但参数风格、输出方式、退出码会和项目里已有的命令对不上后面审查时全是缝。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 接到 TaoTokenSkill 目录摆好之后接下来的动作就是把 Claude Code 这层接到 https://taotoken.net/api。这一步和写 Skill 是两件事改的是工具配置不碰 .claude/skills/ 下的任何文件。3.1 先去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建 Key打开 TaoToken注册登录后进控制台创建 API Key复制出来的那串就是后面要填的 YOUR_API_KEY。模型 ID 不要凭记忆写去模型广场看当时列表里有什么挑一个适合日常写代码的填进去这篇的配置里统一用 YOUR_MODEL_ID 占位实际值以模型广场当时列表为准。Key 的保存习惯值得花半分钟想清楚。如果只在某台机器上用可以放在 shell 的启动文件里如果要在多台机器、多个项目之间切换就把它当成环境变量管理别硬编码进仓库里的任何文件。settings.json 里放 Base URL 和模型 IDKey 从系统环境变量读是相对省心的组合。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_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_ID两处同时配置时生效优先级以 Claude Code 当时的读取顺序为准为避免自己绕晕建议只保留一处。3.3 多机器切换与 taotoken cc 这条快捷路径换机器时重复改 env 段挺烦。如果原文工作流里本来就用了命令行可以用 CLI 直接带参数起 Claude Codenpm 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_MODELKey 和 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 重新建一枚剩下的就不用再动了。