1. 为什么要在 Cursor 里接入 Claude Skill你可能已经在 Cursor 里写过不少代码补全、重构、解释报错都挺顺手但遇到“把这份 PDF 拆成单页”“批量给 Excel 加一列统计”“按规范审查整个模块”这类任务时还是得切到别的工具或者手写脚本。Claude Skill 就是来解决这个断层的它把一组可复用的能力读文件、跑脚本、调工具打包成技能让 Cursor 里的对话直接触发执行而不是只给你一段“你可以这样写”的建议。这篇面向不熟悉 Node.js、也没碰过 openskills 的开发者目标很明确在 Cursor 内跑通第一个 Claude Skill 工作流。全程只需要复制粘贴命令和配置不需要你懂 npm 的依赖树也不需要理解 Skill 的运行时原理。我会给出 AGENTS.md 与 settings.json 的可复制骨架再演示一次真实的 Skill 调用验证动作最后把新手最容易卡住的几个报错逐条拆开。适合谁用 Cursor 做日常开发、想减少重复劳动、但没时间研究 Agent 框架的人。前置条件只有两个——Cursor 更新到较新版本电脑装了 Node.js 16 以上。Node.js 版本可以用node -v确认低于 16 就先升级否则 openskills 安装会直接报引擎不兼容。2. 前置准备TaoToken 与运行环境Claude Skill 本身是能力封装真正执行推理时仍然需要一个稳定的模型入口。我这边习惯用 TaoToken 来做统一接入它的 API 地址是 https://taotoken.net/api 对话、编码计划、密钥管理都在同一个控制台里省得在多个平台之间来回切。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后到控制台生成密钥即可。需要提前拿到的两样东西第一是 API Key。进入控制台的 API Keys 页面创建一个新密钥复制出来先存到本地临时文件里后面写进 settings.json 会用到。地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。第二是确认模型可用。如果你不确定当前账号能调哪些模型可以先去模型对话页面发一条测试消息确认返回正常再继续。地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。环境侧要做的只有三件事确认 Node.js 版本、全局安装 openskills、确认 Cursor 的 Agent Skills 开关已打开。这三步在下一节会给出完整命令。这里先提醒一个容易忽略的点openskills 是全局命令行工具装一次就行不需要在每个项目里重复安装但技能同步sync是项目级的换项目要重新同步一次。3. 可复制配置AGENTS.md 与 settings.json 骨架这一节是全文的核心配置写对了后面调用基本不会出问题。先装工具再写配置顺序不要反。3.1 安装 openskills 并拉取官方技能打开终端Windows 用 PowerShellMac 用 Terminal执行全局安装npm i -g openskills如果 Windows 提示权限不足用管理员身份重开终端Mac 或 Linux 在命令前加sudo。装完后验证一下openskills --version能打印版本号就说明工具就绪。接着安装 Claude 官方技能集推荐全局安装所有项目都能复用openskills install anthropics/skills --global执行后会弹出多选列表用空格勾选你需要的技能比如pdf、xlsx、code-review、frontend-design勾完回车等待下载完成。安装成功后项目里会出现.claude/skills目录这是正常现象不用手动改里面的文件。3.2 AGENTS.md 骨架在项目根目录新建AGENTS.md这是 Cursor 识别技能的入口文件。最小可用骨架如下# AGENTS ## Skills - pdf: 处理 PDF 合并、拆分、加水印、加密 - xlsx: 生成与解析 Excel 表格 - code-review: 代码质量检查与风险扫描 ## Usage 调用技能时使用项目相对路径例如 ./docs/report.pdf写完保存然后在终端执行同步命令把已安装技能写入这个文件openskills sync再次勾选要同步的技能确认后 AGENTS.md 会被自动补全技能描述。这一步别漏漏了 Cursor 就看不到技能列表。3.3 settings.json 骨架在项目根目录的.cursor文件夹下新建settings.json没有.cursor目录就手动建一个。这个文件负责把模型入口指向 TaoToken并声明技能目录{ ai.model.baseUrl: https://taotoken.net/api, ai.model.apiKey: sk-你的密钥, ai.model.name: claude-sonnet, agent.skillsDir: .claude/skills, agent.agentsFile: AGENTS.md }把sk-你的密钥替换成你在控制台创建的真实密钥。注意 baseUrl 只写到/api不要在后面拼具体路径否则会出现 404。保存后重启 Cursor让配置生效。4. 验证请求跑通第一个 Skill 调用配置写完必须验证否则你不知道是配置错了还是技能没同步。验证分两步先确认技能列表能被读到再发一次真实调用。4.1 确认技能已注册在终端执行openskills list正常输出会列出你已安装的技能名和版本。如果列表为空说明安装或同步没成功回到 3.1 重装一次。接着在 Cursor 聊天框输入一个斜杠/如果能看到技能候选弹出说明 Cursor 侧也识别到了。4.2 发起一次真实调用准备一个测试文件比如在项目里放一个./docs/demo.pdf。然后在 Cursor 聊天框输入调用 pdf 技能读取 ./docs/demo.pdf输出它的页数并在同目录生成一份带页码的副本 demo_numbered.pdf回车后 Cursor 会匹配到 pdf 技能并执行。成功时你会看到类似下面的返回已读取 ./docs/demo.pdf共 12 页 已生成 ./docs/demo_numbered.pdf页码添加完成去目录里确认demo_numbered.pdf存在且页码正确第一个工作流就算跑通了。如果这一步成功说明 AGENTS.md、settings.json、openskills 三者已经串起来后面换任何技能都是同样的调用方式。5. 本篇常见错排查新手卡住的地方高度集中下面这几条基本能覆盖九成问题。报错openskills: command not found全局安装没成功或者 npm 的全局 bin 目录不在 PATH 里。先重跑npm i -g openskillsWindows 用管理员终端Mac 加 sudo。装完还找不到执行npm config get prefix看全局路径把它加进环境变量。报错Cannot find module或技能列表为空技能没同步到 AGENTS.md。在项目根目录执行openskills sync重新勾选技能。如果之前同步过但改了技能用openskills sync --force强制覆盖。Cursor 聊天框里技能不触发检查.cursor/settings.json里的agent.skillsDir是否指向.claude/skills以及agent.agentsFile是否指向AGENTS.md。改完必须重启 Cursor热更新不生效。调用时报 401 或鉴权失败settings.json 里的 apiKey 写错或过期。去控制台重新生成一个注意不要带多余空格。baseUrl 必须是https://taotoken.net/api多写路径会 404。文件找不到技能处理文件时用项目相对路径比如./docs/a.pdf不要用桌面绝对路径。路径里有空格要用引号包起来。技能执行到一半失败先用openskills read pdf核对这个技能支持的参数很多时候是参数名写错了。确认参数没问题再重试必要时openskills update升级技能到最新版。6. 继续深入按场景选对入口跑通第一个技能之后接下来怎么走取决于你的使用场景。如果你主要是排障和接入配置重点看 API Keys 和接入文档把密钥管理和 baseUrl 规则吃透地址分别是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你还在挑模型、想先对比不同模型在 Skill 调用里的表现直接去模型对话页面手动试几轮地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期在 Cursor 里做编码、跑 Agent 工作流的建议直接上 Coding Plan额度和调用方式更适合高频场景地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后补一个我自己的习惯每装一个新技能先拿一个最小文件跑一次确认返回路径和结果都对再放到正式项目里用。技能多了之后定期openskills update避免版本落后导致的兼容问题。配置这东西一次写对后面就是纯收益。
