1. 多平台 AI 技能管理为什么让人头疼如果你同时用 Claude Code 写后端、Cursor 调前端、Codex 跑脚本大概率遇到过这种场景在 Claude Code 里调教好的一套「生成 PR 描述」技能换到 Cursor 就得重新配一遍团队里有人用 Codex有人用 Cursor技能目录各写各的最后没人说得清哪份 SKILL.md 才是最新版。skills.sh 这个 CLI 就是来解决这件事的——它把 Agent Skill技能当成可安装、可更新、可跨 Agent 分发的包来管理一条npx skills add就能把同一份技能铺到 Claude Code、Cursor、Codex 等 35 个 Agent 的对应目录里。它适合谁适合手上同时开着两三个编码 Agent 的开发者也适合想把团队规范固化成技能、随项目一起提交的工程团队。核心能力有三块从 GitHub/GitLab/本地路径安装技能、按 Agent 自动映射目录、用 symlink 保持单一事实来源。本文会先讲清 skills.sh 的安装与初始化再给出 Claude/Cursor/Codex 三平台的目录映射骨架最后用 TaoToken 统一 Key 通道把三个工具的连通性验证跑通让你搭出一套能长期维护的跨平台技能流程。2. 前置准备TaoToken 统一 Key 与 skills.sh 环境skills.sh 本身只管技能文件的安装和分发不负责模型调用。但你在验证技能是否生效时总得让 Claude Code、Cursor、Codex 真正跑一次请求这时候如果每个工具各配一套 Key排查问题会非常痛苦。我的做法是用 TaoToken 做统一入口一个 Key 覆盖多个模型通道三个工具都指向同一个 API 地址出问题时只需要看一处日志。TaoToken 的定位是聚合式 API 通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先去控制台创建一个 API Key然后按各工具的配置格式填进去。注意这里说的是「统一 Key」不是让你把 Key 硬编码进技能文件——技能文件是随项目提交的Key 必须走环境变量或工具自己的配置文件。环境侧只需要 Node.js 18因为 skills.sh 通过npx分发不依赖全局安装。先确认版本node -v # 期望输出 v18.x 或更高 npx --version如果你在 CI 里跑建议固定 npx 缓存目录避免每次拉包。skills.sh 在 CI 环境会自动禁用遥测这点对流水线友好。3. 可复制配置skills.sh 安装、初始化与多平台目录映射3.1 安装与初始化skills.sh 不需要npm install -g直接用 npx 调用即可。先跑一次帮助确认命令可用npx skills --help初始化一个技能模板在当前目录生成 SKILL.mdnpx skills init my-skill生成的 SKILL.md 带 YAML frontmattername和description是必填字段。description 要写清「这个技能做什么、什么时候用」因为 Agent 是靠它来决定是否激活技能的。一个最小可用模板长这样--- name: pr-description description: 根据 git 提交历史生成符合团队规范的 PR 描述当用户要求创建 PR 或整理变更说明时使用 --- # PR 描述生成 ## 何时使用 当用户要求生成 PR 描述、整理 commit 变更、或准备合并请求说明时。 ## 步骤 1. 运行 git log 获取当前分支相对主分支的提交 2. 按「背景 / 变更 / 验证」三段式组织 3. 输出 Markdown不添加额外解释3.2 多平台目录映射骨架skills.sh 会自动检测你装了哪些 Agent然后按各自的约定路径写入。下面是 Claude Code、Cursor、Codex 三个平台的映射关系项目级和全局级路径不同选哪种取决于你要不要随项目提交Agent--agent 参数项目路径全局路径Claude Codeclaude-code.claude/skills/~/.claude/skills/Cursorcursor.cursor/skills/~/.cursor/skills/Codexcodex.codex/skills/~/.codex/skills/安装时用-a指定目标 Agent可以叠加多个。比如把一份技能同时装到三个平台的项目目录npx skills add vercel-labs/agent-skills \ --skill frontend-design \ -a claude-code -a cursor -a codex如果想让技能在所有项目里可用加-g装到全局目录npx skills add vercel-labs/agent-skills \ --skill frontend-design \ -g -a claude-code -a cursor -a codex -y-y跳过确认适合脚本化。安装方式上交互式会让你选 symlink 还是 copy推荐 symlink——它从每个 Agent 目录指向一份规范副本更新时只改一处。如果你的文件系统或 CI 环境不支持符号链接再退回 copy。3.3 用 TaoToken 统一三个工具的 API 通道技能装好后要让三个工具都走 TaoToken。Claude Code 通过环境变量指定 base URL 和 Keyexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken KeyCursor 在设置里找 Models 配置把 OpenAI 兼容的 base URL 填成https://taotoken.net/apiKey 填同一个。Codex 的配置文件通常在~/.codex/config.toml指定 provider 的 base URL 和 Key 环境变量名。三个工具指向同一端点后你在 TaoToken 控制台就能看到所有请求排查技能是否真的触发了模型调用会直观很多。4. 验证请求确认技能在三个平台都生效配置完别急着写业务先做连通性验证。第一步确认技能装到了正确位置npx skills list # 按 Agent 过滤 npx skills ls -a claude-code -a cursor -a codex期望输出会列出每个 Agent 下已安装的技能名和路径。如果某个 Agent 没出现说明安装时没指定它或者该 Agent 没被检测到。第二步在 Claude Code 里触发技能。打开一个项目输入一句会命中 description 的请求比如「帮我根据最近的提交生成 PR 描述」。如果技能生效Claude Code 会按 SKILL.md 里的步骤执行而不是自由发挥。同时去 TaoToken 控制台看请求记录确认这次调用确实经过了统一通道。第三步在 Cursor 里做同样的事。Cursor 的技能加载依赖.cursor/skills/目录如果技能没被识别先检查目录里有没有 SKILL.md再确认 frontmatter 是合法 YAML。Codex 同理检查.codex/skills/。一个快速判断 symlink 是否正常的方法ls -la .claude/skills/ # 期望看到 - 指向规范副本的箭头如果显示的是普通目录而非链接说明安装时选了 copy 模式更新技能时需要重新安装。5. 本篇常见错排查「未找到技能」最常见的原因是仓库里没有合法的 SKILL.md或者 frontmatter 缺了 name/description。skills.sh 会在根目录、skills/、.claude/skills/等多个位置递归搜索但前提是文件本身合规。用npx skills add repo --list先列出可用技能确认名字拼写。技能装了但 Agent 不加载先npx skills list -a agent确认路径再对照上表的目录约定。Kiro CLI 是个特例装完还要手动把skill://.kiro/skills/**/SKILL.md加进.kiro/agents/agent.json的 resources 里否则不生效。权限错误全局安装写~/下的目录如果之前用 sudo 装过东西导致属主不对会写不进去。检查目标目录的写权限必要时改属主而不是无脑 sudo。更新后行为没变如果你用的是 copy 模式npx skills update更新的是规范副本各 Agent 目录里的拷贝不会自动同步。改用 symlink 模式或者更新后重新安装一次。CI 里安装卡住交互式确认在无 TTY 环境会挂起。加-y跳过确认并用--all或明确指定--skill和--agent避免进入交互选择。6. 把技能流程固化下来技能管理这件事配一次不难难的是三个月后还能说清哪个版本在生效。我的建议是项目级技能随仓库提交用 symlink 保持单一副本全局技能只放跨项目通用的那几份所有模型调用统一走 TaoToken这样换模型或排查问题时不用挨个工具改配置。如果你还在选型阶段想先验证技能触发效果可以直接用模型对话页面手动测一遍 description 是否够清晰https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。确定要长期在 Claude Code、Cursor、Codex 之间共享技能后去控制台建 Key 并配好通道https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你主要用 Claude Code 做长期编码Coding Plan 会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后留一个我踩过的坑技能 description 写得太宽泛比如「帮助写代码」会导致 Agent 在无关场景也激活它反而干扰正常输出。description 要具体到「什么场景、解决什么问题」这比技能内容本身更影响触发准确率。