1. 为什么 Claude Skills 在 Qoder、Cursor、Trae、Windsurf 里跑不起来

Claude Skills 是 Anthropic 在 Claude Code 里推出的一套「技能包」机制：每个 Skill 就是一个带 YAML 元数据的SKILL.md，加上可选的scripts/、references/、assets/目录。模型在遇到任务时会先扫描可用技能列表，命中后把对应SKILL.md的内容加载进上下文，再按里面的步骤执行。它解决的是「同一个能力反复写提示词」的问题，比如 PDF 转档、Excel 分析、PPT 生成这类固定流程，写一次就能被反复调用。

问题在于，这套机制目前是 Claude Code 原生内置的。Qoder、Cursor、Trae、Windsurf 这些 AI Coding 工具虽然都支持 Rules / AGENTS.md 之类的项目级指令文件，但它们并不认识<available_skills>这种 XML 结构，也不会主动去.claude/skills/目录里找技能。你直接把 Skill 文件夹丢进去，模型大概率当没看见，或者只把它当成普通文档读一遍，不会触发「加载技能 → 执行脚本」的完整链路。

我试过在 Cursor 里手动把SKILL.md内容贴进 Rules，结果模型确实会照着做，但每次都要复制粘贴，技能一多就完全失控。真正可用的做法是引入一层「翻译」：用 OpenSkills 把 Claude 的 Skill 目录同步成各工具都能读的AGENTS.md规则文件，让模型通过执行openskills read <skill-name>这条命令来按需加载技能。这样 Qoder、Cursor、Trae、Windsurf 就都能复用同一套 Skill 生态。

这篇要解决的就是这条完整链路：Skill 怎么装、AGENTS.md 怎么同步到四个工具各自的规则目录、TaoToken 怎么作为统一鉴权通道接进去、以及最后怎么逐项验证技能真的生效了。适合已经在用这些工具、想让 Skills 跨工具复用的开发者，也适合刚接触 Claude Skills 想先跑通一个 PDF 转档例子的小白。

2. 前置准备：OpenSkills 安装与 TaoToken 统一 Key 接入

先说清楚这一层的定位。OpenSkills 负责「技能的分发与同步」，TaoToken 负责「模型请求的鉴权与通道」。两者是正交的：前者决定模型能不能看到技能，后者决定模型能不能被调用。很多人卡在第二步，是因为四个工具的 API 配置入口各不相同，一个个填 Key 很容易乱。

OpenSkills 的安装要求很明确：Node.js 20.6+，以及本机有 Git（用于从 GitHub 克隆技能仓库）。装完之后它提供install、sync、list、read、manage、remove六个子命令，日常用得最多的是前四个。

# 确认 Node 版本，低于 20.6 会报错 node -v # 全局安装 openskills npm i -g openskills # 验证安装 openskills --version

技能安装支持四种来源：Anthropic 官方市场、其他 GitHub 仓库、本地路径、私有仓库。项目级安装会落到./.claude/skills，全局安装落到~/.claude/skills。

# 项目级安装（放到 ./.claude/skills） openskills install anthropics/skills # 全局安装（放到 ~/.claude/skills） openskills install anthropics/skills --global # 从其他 GitHub 仓库安装 openskills install your-org/custom-skills # 从本地目录安装 openskills install /path/to/my-skill

安装过程中如果检测到同名技能已存在，会交互式询问是否覆盖；在 CI 或脚本里可以用--yes跳过确认。

接下来是 TaoToken 这一层。它的作用是给你一个统一的 Base URL 和 Key，四个工具都填同一套，省得每个工具单独申请。先去控制台创建 Key：

• 控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

创建完 Key 之后，你会拿到两个关键值：Base URL 是https://taotoken.net/api，以及一串sk-开头的 Key。这两个值在下面四个工具的配置里反复出现，建议先记到便签里。

注意：Base URL 填https://taotoken.net/api即可，不要在后面手动加/v1，具体路径由各工具的 SDK 自己拼接。填错是 401 和 404 的高发原因。

如果你还没决定用哪个模型，可以先去模型对话页面试一下，确认通道通了再往工具里配：

• 模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite

这一步做完，你手上应该有三样东西：装好的 openskills、一个可用的 Key、一个确认能通的 Base URL。下面进入各工具的具体配置。

3. 四个工具的可复制配置片段：Qoder、Cursor、Trae、Windsurf 的 Skills 目录与 Rules

这一节是全文的核心，逐个工具给出目录路径、配置片段和同步命令。四个工具的共性思路是一样的：先用openskills sync把技能表写成一个AGENTS.md，再把这个文件放到工具能识别的规则目录里。差异只在路径和触发方式。

3.1 Qoder 的 Skills 目录与 AGENTS.md 规则

Qoder 的技能目录是~/.agent/skills/，规则目录是项目下的.qoder/rules/。先把技能装到 Qoder 能读的位置，再同步规则。

# 安装到通用 agent 目录（Qoder 优先读这里） openskills install anthropics/skills --universal # 同步技能表到 Qoder 的规则目录 openskills sync --output .qoder/rules/AGENTS.md

执行sync时会列出已安装的技能，让你勾选要写进规则文件的条目。选完之后.qoder/rules/AGENTS.md里会出现一段<skills_system>结构，包含available_skills列表和调用说明。Qoder 读取这个规则文件后，遇到「把 README.md 转成 PDF」这类请求，就会去执行openskills read pdf加载技能内容。

3.2 Cursor 的 Rules 配置

Cursor 的规则入口是项目根目录的.cursor/rules/，或者单文件.cursorrules。推荐用目录形式，方便和 OpenSkills 的 sync 输出对齐。

openskills sync --output .cursor/rules/AGENTS.md

如果你更习惯单文件，也可以直接同步到根目录：

openskills sync -o .cursorrules

Cursor 对规则文件的读取是自动的，不需要额外开关。同步完成后，在 Cursor 的 Chat 里问「用 pdf skill 把 README 转成 PDF」，它会先读规则、再执行openskills read pdf。

3.3 Trae 的规则目录

Trae 的规则目录是.trae/rules/，同步命令：

openskills sync --output .trae/rules/AGENTS.md

Trae 的规则生效范围是当前项目，跨项目复用需要把技能装到全局目录~/.claude/skills，再在每个项目里 sync 一次。

3.4 Windsurf 的规则文件

Windsurf 用的是.windsurf/rules/目录，同样支持AGENTS.md：

openskills sync --output .windsurf/rules/AGENTS.md

Windsurf 的规则有字符数上限，技能特别多的时候建议只同步常用的几个，或者用openskills manage精简技能列表。

3.5 四个工具的 API 配置片段

技能配好之后，还要让工具能调到模型。四个工具的配置入口不同，但填的都是同一套 Base URL 和 Key。下面给出可复制的配置片段。

Qoder 在设置里的模型配置面板填写：

{ "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "model": "claude-sonnet-4-5" }

Cursor 在 Settings → Models 里添加自定义模型，或者直接改~/.cursor/config.json：

{ "models": [ { "name": "claude-sonnet-4-5", "provider": "openai", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key" } ] }

Trae 的模型配置在设置面板，选择「自定义 OpenAI 兼容」后填：

[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-你的Key" model_id = "claude-sonnet-4-5"

Windsurf 的配置在~/.codeium/windsurf/config.json：

{ "customProviders": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "models": ["claude-sonnet-4-5"] } } }

三件套对照表，方便你核对：

提示：Model ID 要和你账号下可用的模型一致，写错会返回model not found。不确定的话先去模型对话页面确认可用列表。

4. 验证请求：确认 Skills 真的被加载并执行

配置写完不代表生效，必须逐项验证。验证分两层：先确认模型通道通，再确认技能被加载。

第一层，通道验证。在任意一个工具里发一句最简单的请求，比如「回复 ok」。如果返回正常，说明 Base URL 和 Key 没问题。如果报 401，说明 Key 错了或没生效；如果报连接失败，说明 Base URL 写错了。

第二层，技能验证。用一个具体的、可观察结果的任务，比如把 README.md 转成 PDF。在 Qoder 里输入：

把当前项目的 README.md 使用 pdf skill 转为 PDF 并放到项目中

预期行为是：模型先读.qoder/rules/AGENTS.md，发现pdf技能，执行openskills read pdf，加载SKILL.md里的步骤，然后调用脚本生成 PDF。你可以在项目目录下看到新生成的 PDF 文件。

如果模型没有触发技能，可以手动验证技能是否可读：

# 列出已安装技能 openskills list # 手动加载某个技能，看内容是否正确 openskills read pdf

openskills read pdf应该输出完整的SKILL.md内容，包括 YAML 头和正文步骤。如果这一步报错，说明技能没装好，回到第 2 节重新安装。

再验证一下规则文件是否被工具读取。以 Cursor 为例，在 Chat 里问「你当前有哪些可用技能」，如果模型能列出pdf、xlsx等名字，说明规则文件生效了。如果模型说「没有可用技能」，说明规则文件路径不对或没被加载。

四个工具都建议跑一遍这个验证流程，因为它们的规则加载时机不同：Qoder 和 Trae 是项目打开时加载，Cursor 和 Windsurf 是对话时动态读取。跑通一个之后，其余三个照搬即可。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错逐条排查。这些错误我在配置过程中基本都踩过，按顺序对照能省不少时间。

401 Unauthorized。最常见的原因是 Key 没填对或没生效。检查三件事：Key 是否以sk-开头、是否有多余空格、是否填在了正确的字段里。如果 Key 确认没问题，检查 Base URL 是否写成了https://taotoken.net/api/v1，多写的/v1会导致鉴权路径错位。改回https://taotoken.net/api即可。

local proxy failed。这个报错通常出现在工具尝试走本地代理但代理没启动时。检查工具的网络设置里是否开了「使用本地代理」，关掉它，让请求直连 Base URL。如果公司网络有出口限制，确认taotoken.net在允许列表里。

reading choices 相关报错。典型信息是cannot read properties of undefined (reading 'choices')，说明返回体结构不符合预期。原因一般是 Model ID 写错了，或者 Base URL 指向了一个不返回 OpenAI 兼容格式的端点。核对 Model ID 是否和账号可用列表一致，Base URL 是否为https://taotoken.net/api。

OAuth 相关报错。如果工具提示 OAuth 登录失败或 token 过期，说明它还在走官方的 OAuth 流程，没有切到自定义 Key 模式。去设置里把认证方式从「OAuth」改成「API Key」，填入 TaoToken 的 Key。Cursor 和 Windsurf 都支持这个切换。

技能不触发。模型能正常对话，但提到技能时没反应。检查规则文件路径是否正确、AGENTS.md里是否有<available_skills>段、技能是否真的装在openskills list里。三者缺一不可。

openskills sync 报错。常见于 Node 版本低于 20.6，或者当前目录没有写权限。升级 Node 后重试，或者用--output指定一个有写权限的路径。

排查顺序建议：先确认通道（401 / proxy），再确认模型（choices），最后确认技能（不触发）。这样能快速定位问题在哪一层。

6. 长期使用建议与统一通道入口

跑通之后，日常使用有几个习惯能省事。技能尽量装到全局目录~/.claude/skills，这样每个新项目只需要 sync 一次规则文件，不用重复安装。规则文件建议纳入版本控制，团队里其他人拉下来就能用同一套技能。技能数量控制在 10 个以内，太多会稀释模型的注意力，反而不容易命中。

如果你打算长期用这套组合做编码和 Agent 任务，Coding Plan 比按量付费更划算，适合高频调用场景：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

接入文档里有各工具的详细配置说明和最新参数，配置过程中遇到路径或字段疑问可以直接查：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

如果你用的是 Claude Code 本身，Anthropic 兼容接入的配置方式略有不同，可以参考这份说明：

• Claude Code Anthropic 接入：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite

最后回到验证这件事。技能生效的判断标准很简单：模型能说出技能名、能执行openskills read、能产出可观察的结果文件。三者都满足，说明整条链路通了。四个工具里任意一个跑通，其余三个照搬路径和配置即可，差异只在规则目录名。