1. 先弄清楚 Skill 的加载目录再谈「跑得起来」把 SKILL.md 放进~/.cursor/skills/之后你以为 Skill 就算装好了。实际在 Cursor 里显式引用 Skill 名称时模型才开始读那份 SKILL.md 并决定怎么回答——也就是说Skill 装得再规矩真正触发还得靠模型接口正常返回。这时候模型请求怎么走、Key 放哪就成了新的问题。我常用的做法是给 Cursor 接一把 TaoToken 的 Key从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建再把 Base URL 指向 https://taotoken.net/apiSkill 触发和日常对话就都走同一个通道。在 Cursor 里Skill 本质上不是插件也不是一段脚本而是「一个目录 一份 SKILL.md」的配置单元。Cursor 启动时会扫描特定目录把 SKILL.md 里的指令、约束、示例都读进上下文当你在对话里主动提 Skill 名或者模型判断应该用它时Cursor 就把这份指令当作「系统任务」的一部分连同你的问题一起发给模型。所以你可以把 Skill 想成一张任务话术单话术单写得再清楚递不到模型手里就等于白写。1.1 个人全局 Skill~/.cursor/skills/skill-name/SKILL.md如果你的 Skill 希望所有项目都能调用就把目录放到用户主目录下。Windows 上对应C:\Users\你的用户名\.cursor\skills\macOS 和 Linux 就是~/.cursor/skills/。这个目录不存在时自己新建一个即可Cursor 不会自动帮你生成。典型的目录结构长这样~/.cursor/skills/ └── eladmin-fullstack-dev/ └── SKILL.md注意Skill 目录内必须直接包含 SKILL.md不能再多包一层同名目录比如~/.cursor/skills/eladmin-fullstack-dev/eladmin-fullstack-dev/SKILL.md这种嵌套结构Cursor 是认不出来的。另外~/.cursor/skills-cursor/这个目录是 Cursor 内置系统占用的不要把自己的 Skill 放进去否则可能被系统配置干扰。1.2 项目级 Skill.cursor/skills/只对当前仓库生效团队项目通常会用到领域专属的 Skill比如前端规范、接口风格、数据库表约定。这种 Skill 放进仓库根目录下的.cursor/skills/更合适——它只在当前仓库打开时生效不会污染其他项目。your-repo/ └── .cursor/ └── skills/ └── eladmin-fullstack-dev/ └── SKILL.mdSKILL.md 的内容开头通常是 YAML frontmatter至少要有name字段。它不直接决定路径但会影响 Cursor 在对话里识别 Skill 的方式--- name: eladmin-fullstack-dev description: 当涉及 eladmin 前后端功能开发时使用本 Skill disable-model-invocation: false ---这里的disable-model-invocation是触发开关后面第 6 节会专门讲。先把目录路径放对再纠结开关。2. 团队共享和迁移 Skill交给 Git别靠人肉拷贝很多人第一次在团队里推广 Skill用的是「把文件夹压缩包发到群里」的方式。结果很快出现两个问题有人解压到了错误路径有人改了一版但别人拿到的还是旧版。与其这样不如把 Skill 放进项目仓库用 Git 统一管。2.1 把.cursor/skills/提交进 Git 仓库把 Skill 目录放到your-repo/.cursor/skills/下然后正常提交。团队成员 clone 或 pull 之后.cursor/skills/里的 Skill 自动进入 Cursor 的扫描范围不用每个人手动复制粘贴。这样有两个直接好处版本统一Skill 的更新跟着代码分支走Pull Request 评审时能看到 SKILL.md 的变更记录。环境一致不管新同事用的是 macOS 还是 Windows只要 IDE 指向同一个仓库拿到的 Skill 目录和文件内容就是一致的。团队里如果同时维护多个 Skill建议在.cursor/skills/目录下按「技能名 用途」命名避免出现一堆skill1、skill2这种没法认的目录名。2.2 从旧项目迁移 Skill 时的三条检查迁移别人的 Skill 或者复用旧项目的 Skill本质就是复制目录。但复制完别急着收工至少检查三件事name和description是否符合当前项目语义。frontmatter 是否完整YAML 缩进有没有坏掉。是否同时存在全局和项目两份同名 Skill——如果两个路径都有同一个名字Cursor 的匹配行为会变得很难判断。把旧 Skill 复制到~/.cursor/skills/或repo/.cursor/skills/后最稳妥的验证方式是重启 Cursor 再确认一遍列表而不是直接开新对话看运气。3. 触发 Skill 的模型请求走哪条通道Cursor 接 TaoTokenSkill 安装路径没问题、frontmatter 也没问题之后你会在对话里写「用 eladmin-fullstack-dev 看一下这段接口代码」。这条消息发出去时Cursor 会做两件事把 SKILL.md 的内容拼进上下文把整个请求发到配置好的模型 API。也就是说——Skill 能不能给出预期的输出最终由模型接口决定。这就是很多人容易卡住的地方官方 Key 分散在不同账号里团队里 5 个人就有 5 把 Key某一把限额用完了大家还都不知道该找谁。Cursor 本身只需要一个能访问模型的 API 通道所以我把 Key 统一收到 TaoToken让 Cursor 的模型请求都走 https://taotoken.net/api 这个兼容通道。3.1 先去官网创建 YOUR_API_KEY打开 TaoToken注册完成后进入控制台在 API Key 页面创建一把新 Key。创建后它只显示一次复制出来存好后面填入 Cursor 的就是这把。注意 Key 的占位符写法统一是YOUR_API_KEY真正配置时记得替换成你自己的字符别原样填进去。3.2 在 Cursor 模型设置里填 Base URL 和 Key打开 Cursor 的 Settings进入 Models 相关的 API 配置区域。重点是两个输入Base URL 填https://taotoken.net/api末尾不要加/v1。API Key 填上一步创建的YOUR_API_KEY。模型 ID 以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场当时列表为准不要凭印象写一个不存在的模型名。填好后保存回到对话界面。此时你引用的任何 Skill在触发时都会把这个请求发到 TaoToken 的通道上由对应模型返回结果。以后换模型也只需要回到模型广场看当前可用列表改一下模型 ID 就行不需要重新折腾 Key。3.3 团队共用一把 Key各自装自己的 SkillTeam 场景下每个人机器的 Cursor 设置是独立的Skill 目录可以跟着仓库走而 Key 不需要人手一把。让新同学去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册后把团队那把 Key 填进他自己的 Cursor 设置或者按需创建他自己的子 Key。这样 Skill 的版本由 Git 管Key 的归属由个人管两者互不纠缠。统一走 TaoToken 兼容通道还有一个好处Skill 里写的模型推理逻辑比如「先分析表结构再生成 SQL」不会被某个模型的输出差异打乱只要模型 ID 固定团队拿到的行为基本一致。这里的「一致」指配置同一模型 ID 时的表现具体效果还是以模型广场列表为准。4. 验证 Skill 是否生效先看列表再显式调用Skill 装没装上不能靠「我感觉它生效了」。Cursor 提供了两层验证方式两层都过一遍再开始用。4.1 UI 检查Skill 列表里能不能看到它打开 Cursor 的 Skill 管理界面入口在不同版本里位置略有变化看列表里是否出现刚才安装的 Skill 名称。个人全局 Skill 和项目级 Skill 会出现在同一个列表里只是来源路径不同。如果列表里没有优先检查路径——最常见的问题就是放到了~/.cursor/skills-cursor/或者目录里缺少 SKILL.md。4.2 对话验证显式引用 Skill 名称触发列表存在只代表 Cursor 识别到了目录结构不代表模型真的能用好它。在对话里直接写类似「使用 eladmin-fullstack-dev 技能」并附带一个真实任务观察模型是否按照 SKILL.md 里的说明来回答。如果模型表现和普通对话没有区别说明 Skill 的指令没有进入上下文这时回去查 frontmatter 的name是否和引用名称一致。这一条同样适合用来验证 TaoToken 通道是否接通如果请求确实发出去了但模型返回的报错提示认证失败就回去看 Cursor 设置里的 Key 是不是少了字符或多了空格如果返回模型不存在就去模型广场核对模型 ID。5. 排查顺序Skill 不生效先查目录请求报错再查接口结合我自己的使用经验Skill 出问题基本分成两层一层是 Skill 本身没被 Cursor 加载另一层是 Skill 加载了但模型请求失败。分开排查会快很多。5.1 Skill 文件层面的检查目录有没有包含SKILL.md文件名大小写是否完全一致。路径是~/.cursor/skills/name/SKILL.md还是被放在了~/.cursor/skills-cursor/。SKILL.md 开头是否有合法的 frontmatter---两行和name:字段都没有被多余空格破坏。项目中同时存在同名 Skill 时全局和仓库级是否冲突。这里的重点是先确认是「没有加载」还是「没有按预期触发」两者处理方向完全不同。加载问题看路径和 frontmatter触发问题要看第 6 节的disable-model-invocation。5.2 模型请求层面的检查如果 Skill 出现在列表里但一问就报错问题往往出在 API 配置上。常见情况是 Base URL 填成了https://taotoken.net/api/v1或者 Key 里混进了换行符。另一个容易忽略的是模型 ID模型广场下线的 ID 填进去会直接提示找不到模型这时回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的模型广场重新确认在线列表即可。排查时不要同时改多个变量。先确认 Base URL 精确等于https://taotoken.net/api再确认 Key 完整粘贴最后确认模型 ID 存在。三个变量一次改一个问题也就跟着定位了。6. 多个 Skill 的行为机制自动触发还是手动调用团队里 Skill 多起来之后对话中可能出现「我明明没叫某个 Skill它却插话了」的情况。这不是 Cursor 乱来而是 Skill 的触发开关没关。6.1 disable-model-invocation 到底控制什么SKILL.md 的 frontmatter 里有一项disable-model-invocation: true设置为true时Cursor 不会让模型自动调起这个 Skill只能靠你在对话里显式指名。设置为false或省略不写时模型可能根据描述自动匹配并参与当前对话。多个 Skill 同时存在时只要它们都没关自动触发模型理论上可能同时参考多个 Skill指令相互叠加输出质量就很难控制。所以我的习惯是默认给每个 Skill 都加上disable-model-invocation: false只有真正希望它随时能帮忙时才开着其他一概手动调用。6.2 只想用一个 Skill 时的配置组合如果你希望当前项目只使用某个特定 Skill其他都靠边站可以分两步配置。第一步把不希望自动触发的 Skill 全部改成disable-model-invocation: true第二步在对话里显式写出目标 Skill 名称例如「用 eladmin-fullstack-dev 分析这段接口」。这样自动匹配被关掉显式调用仍然可用等于给 Skill 加了一道人工闸门。多个 Skill 本身可以共存但共存和有序触发是两回事。文件名、name字段、目录层级都清晰后续调整触发行为时才不会翻车。7. 跑通之后去对照调用记录确认它真的在干活Skill 能在对话里被触发TaoToken 通道也通了接下来建议做一次完整闭环在 Cursor 里用 SKILL.md 定义的任务发一条请求然后到 TaoToken 控制台 API Keys 页面里看一眼刚才的请求是否产生了对应的调用记录。这一步能同时确认两件事——Key 有效性以及 Cursor 是否真的把请求发到了你填的 Base URL。如果想要先绕过 Cursor 单独验证模型 ID可以直接打开 TaoToken 模型对话用同一把 Key 发一条测试消息确认当前模型 ID 可用后再回 Cursor 继续调 Skill。长期跑代码相关任务的话也可以对照 Coding Plan 看一下套餐包含的模型范围是否覆盖你常用的那几个需要给团队成员开新 Key 时回到 创建 Key 页面 操作就行。Skill 目录结构、触发开关、模型通道这三件事理顺后Cursror 跑 SKILL.md 定义的 Skill 就不再玄学了文件放在对的位置对话里叫它的名字模型接口把答案送回来。整个链路里最容易忽略的反而是不起眼的 Base URL 末尾那个/v1——它值不值得你花半小时排查取决于你第一次填的时候有没有手滑。
