1. 为什么你的 Agent Skills 总是跑不通Skills CLI 是 Agent Skills 的命令行管理器用来发现、安装、临时使用、更新和移除可复用的 agent 能力包。它解决的核心问题是你手头有 Codex、Claude Code、Cursor 好几个 AI 工具每个工具都要单独配 Key、单独装 skill、单独维护目录时间全花在环境上而不是写代码上。适合谁适合已经在用 Codex 或 Claude Code 做日常开发、想用一套统一 Key 把 skill 调用链路一次跑通的开发者。我试过最典型的翻车场景是这样的npx skills add vercel-labs/agent-skills --skill frontend-design -a codex装完了skill 文件确实躺在.agents/skills/里但一启动 Codex 就报 401或者干脆提示找不到模型。排查半天发现不是 skill 的问题是 Codex 的config.toml里 API 通道没配对Key 和 base_url 对不上。Claude Code 那边同理settings.json里ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY只要有一个写错skill 加载了也调不动。所以这篇手册的思路是先把 Skills CLI 的安装动作跑通再把 TaoToken 统一 Key 接进 Codex 和 Claude Code 的配置文件最后用一条 CLI 验证动作确认整条链路是活的。顺序不能反先配 Key 再装 skill或者先装 skill 再配 Key 都行但验证必须在两者都完成之后做。2. TaoToken 前置统一 Key 与 API 通道TaoToken 在这里扮演的角色是统一入口。你不需要为 Codex 和 Claude Code 分别申请不同的 Key也不需要记两套 base_url。一个 Key 走同一个 API 通道两个工具共用。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api你需要提前拿到两样东西API Key 和确认 base_url。Key 在控制台的 API Keys 页面生成生成后复制保存页面关掉就看不到了。base_url 统一用https://taotoken.net/api注意后面不要多加/v1Codex 和 Claude Code 的配置项会自己拼接路径。注意Key 只显示一次建议生成后立刻写进配置文件不要先复制到聊天窗口再转存容易丢字符。如果你还没生成 Key先去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content生成 Key 的具体入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后先别急着装 skill。先用模型对话页面确认 Key 本身是有效的https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content这一步能排除掉「Key 本身有问题」这个变量。如果模型对话都调不通后面配 Codex 和 Claude Code 就是白费功夫。3. 可复制配置settings.json 与 config.toml 骨架3.1 Claude Code 的 settings.jsonClaude Code 读取的配置文件在~/.claude/settings.json。如果目录不存在就手动建。骨架如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }把sk-你的TaoToken密钥替换成你实际生成的 Key。注意ANTHROPIC_BASE_URL结尾不要带斜杠也不要带/v1。Claude Code 内部会自己拼/v1/messages。如果你之前已经配过别的通道把这两个字段覆盖掉就行其他字段保留。改完保存不需要重启终端但需要重新启动 Claude Code 进程。3.2 Codex 的 config.tomlCodex 的配置文件在~/.codex/config.toml。骨架如下model gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [model_providers.taotoken.headers] Authorization Bearer sk-你的TaoToken密钥这里有两种写法。一种是用env_key指向环境变量另一种是直接在 headers 里写死 Key。推荐用环境变量方式更干净export TAOTOKEN_API_KEYsk-你的TaoToken密钥然后config.toml里只保留env_key TAOTOKEN_API_KEY把 headers 那段删掉。这样 Key 不会出现在配置文件里也不容易误提交到 git。注意model字段填你实际要用的模型名。如果你不确定用哪个先去模型对话页面确认可用模型列表。3.3 两个配置的对照项目Claude CodeCodex配置文件~/.claude/settings.json~/.codex/config.tomlbase_url 字段ANTHROPIC_BASE_URLbase_urlKey 字段ANTHROPIC_API_KEYenv_key或 headers路径拼接自动加/v1/messages自动加/v1/chat/completions生效方式重启进程重启进程两个配置都改完之后先别装 skill直接启动一次 Codex 和 Claude Code确认能正常对话。这一步过了再进下一步装 skill。4. 验证请求Skills CLI 安装与调用链路确认4.1 安装 skill 到 Codex先列出仓库里有哪些 skill 可用npx skills add vercel-labs/agent-skills --list确认列表里有你需要的 skill 之后安装到 Codexnpx skills add vercel-labs/agent-skills --skill frontend-design -a codex安装完成后检查是否落盘npx skills ls -a codex你应该能看到frontend-design出现在列表里。对应的文件位置在.agents/skills/frontend-design/SKILL.md。4.2 安装 skill 到 Claude Codenpx skills add vercel-labs/agent-skills --skill frontend-design -a claude-code检查npx skills ls -a claude-code文件位置在.claude/skills/frontend-design/SKILL.md。4.3 临时使用不落盘如果你只是想试一下某个 skill不想装到项目里npx skills use vercel-labs/agent-skillsweb-design-guidelines --agent codex这条命令会把 skill 下载到临时目录输出一段可喂给 agent 的 prompt。你可以直接管道给 Claudenpx skills use vercel-labs/agent-skillsweb-design-guidelines | claude或者存成文件再手动喂npx skills use vercel-labs/agent-skillsweb-design-guidelines /tmp/skill-prompt.txt注意skills use --agent目前只支持claude-code和codex。其他 agent 需要用 stdout prompt 自行接入。4.4 验证整条链路装完 skill 之后启动 Codexcodex在对话里输入一个会触发 skill 的请求比如「用 frontend-design 帮我设计一个登录页」。如果 Codex 能正常返回结果说明 Key、base_url、skill 加载三件事都通了。Claude Code 同理claude输入同样的请求确认能返回结果。如果这一步报错先看错误码。401 是 Key 问题404 是 base_url 问题skill 找不到是安装路径问题。下一节逐个排查。5. 本篇常见错排查5.1 401 Unauthorized最常见的原因是 Key 写错了或者过期了。检查settings.json和config.toml里的 Key 是否和 TaoToken 控制台生成的一致。注意 Key 只显示一次如果你复制的时候漏了字符只能重新生成一个。另一个原因是环境变量没生效。如果你用的是env_key方式确认export TAOTOKEN_API_KEY...在当前终端会话里执行过。可以echo $TAOTOKEN_API_KEY确认。5.2 404 Not Foundbase_url 写错了。确认是https://taotoken.net/api结尾没有斜杠没有/v1。如果你写成了https://taotoken.net/api/v1路径会变成/api/v1/v1/messages直接 404。5.3 skill 装了但 agent 找不到先确认安装位置对不对。Codex 的项目级路径是.agents/skills/全局路径是~/.codex/skills/。Claude Code 的项目级路径是.claude/skills/全局路径是~/.claude/skills/。如果你装的时候没加-g默认是项目级。确认你启动 agent 的目录和安装 skill 的目录是同一个。如果 SKILL.md 藏得很深CLI 默认扫不到加--full-depthnpx skills add owner/repo --full-depth5.4 skills use 报错说不支持该 agentskills use --agent只支持claude-code和codex。如果你用的是 Cursor 或 Gemini CLI不要加--agent直接用 stdout promptnpx skills use owner/reposkill-name /tmp/prompt.txt然后手动把 prompt 内容喂给你用的 agent。5.5 多 skill 仓库必须指定 skill如果仓库里有多个 skillnpx skills use owner/repo会报错必须指定具体 skillnpx skills use vercel-labs/agent-skills --skill web-design-guidelines或者用简写npx skills use vercel-labs/agent-skillsweb-design-guidelines5.6 更新和删除更新单个 skillnpx skills update my-skill更新全局npx skills update -g删除npx skills rm my-skill删除全局npx skills remove --global my-skill批量删除npx skills remove --all6. 把 Key 和 skill 管理固定成日常动作配好之后日常动作其实就三条新项目初始化时跑一次npx skills add把需要的 skill 装进去Key 轮换时改settings.json和config.toml两个文件skill 有更新时跑npx skills update。如果你长期用 Codex 或 Claude Code 做编码建议把 Key 管理也固定下来。TaoToken 的 Coding Plan 适合这种长期场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档在这里遇到配置字段不确定的时候直接查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentClaude Code 的专项接入说明https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后提醒一个容易忽略的点skills-lock.json和.skill-lock.json这两个文件建议提交到 git。前者记录项目级安装的 skill 版本后者记录全局安装。团队协作时别人 clone 下来跑一次npx skills update就能对齐版本不用手动一个个装。
