1. 为什么 Cursor 里的 Skill 总是“加载不上”如果你在 Cursor 里写过.cursor/skills/xxx/SKILL.md大概率遇到过这种场景文件明明建好了Agent 却像没看见一样问它“有哪些技能可用”答不上来让它执行某个工作流也只会临场发挥。问题通常不在模型而在“声明”和“加载”这两步没打通。Cursor 的 Skill 机制本质上是两段式第一段是能力声明把可用技能的名字和描述写进AGENTS.md让 Agent 启动时就知道自己“会什么”第二段是按需读取Agent 判断需要某个技能时再通过 CLI 把完整的SKILL.md内容读进上下文。只写文件不做声明Agent 就没有索引只做声明但 CLI 读不到内容Agent 拿到的是空壳。这套链路里还有两个容易忽略的点。一是双层目录项目级.cursor/skills/优先级高于全局~/.cursor/skills/同名技能项目级会覆盖全局很多人把技能放错层导致“改了没生效”。二是 Token 成本如果把所有技能的完整内容都塞进AGENTS.md上下文会被迅速吃满所以正确做法是AGENTS.md只存摘要正文靠read命令按需拉取。这篇就按“声明 → 加载 → 验证”的顺序把AGENTS.md的标记结构、cursor-skills的 CLI 触发链路、以及用 TaoToken 统一 Key 接入的配置骨架串起来最后给一套能直接跑的验证动作确认自动加载真的生效了。2. TaoToken 前置统一 Key 与接入地址在配 Skill 之前先把模型调用这条链路固定下来。Cursor 里的 Agent 要真正跑起来背后得有稳定的模型入口。TaoToken 在这里的角色是提供一个统一的 API Key 和兼容的接入地址这样你在config.toml、settings.json里填一次后续换模型、加技能都不用反复改鉴权。需要记住两个地址用途不同官网入口注册、看文档、进控制台https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址写进配置文件的那个https://taotoken.net/api注意 API 基址不要带 UTM 参数配置文件里多一个查询串有些客户端会解析异常。Key 的获取在控制台的 API Keys 页面生成后只显示一次建议直接存进环境变量而不是硬编码进仓库。按你的使用场景入口可以这样分流只是想让 Agent 能对话、验证模型通不通走模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content要长期在 Cursor 里做编码、跑 Agent 工作流走 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content管理 Key、看用量走控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content生成或轮换 Key走 API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content先把 Key 拿到手后面所有配置都围绕它展开。3. 可复制配置AGENTS.md 骨架 config.toml settings.json这一节是全文的核心三份文件配好Skill 自动加载的骨架就立起来了。3.1 AGENTS.md 的标记结构AGENTS.md放在项目根目录关键是那对 HTML 注释标记。cursor-skills sync只会替换标记之间的内容标记外的项目说明、自定义指令都会被保留所以这个文件可以反复 sync 而不会覆盖你手写的东西。# 项目 Agent 说明 本项目使用 cursor-skills 管理技能技能列表由 CLI 自动维护请勿手动编辑标记区域。 !-- SKILLS_TABLE_START -- available_skills skill namefigma2code/name descriptionConvert Figma designs to React components/description locationproject/location /skill skill namecode-review/name descriptionAutomated code review workflow/description locationglobal/location /skill /available_skills !-- SKILLS_TABLE_END -- usage 当需要使用某个技能时执行 Bash(cursor-skills read skill-name) 获取完整技能内容 再按照其中的工作流执行任务。不要凭记忆猜测技能内容。 /usage这里usage段是给 Agent 的行为指令明确告诉它“先 read 再执行”否则模型可能直接跳过读取步骤自己编流程。location字段区分 project 和 global方便排查同名覆盖问题。3.2 技能文件本身每个技能是一个目录核心是SKILL.md开头用 YAML Front Matter 声明元数据CLI 扫描时就是解析这段--- name: figma2code description: Convert Figma designs to React components --- ## 工作流程 1. 获取 Figma 设计稿 JSON 2. 解析设计结构 3. 生成 React 组件代码 ## 使用方式 调用 scripts/generate.js 并传入 Figma URL。目录结构建议这样组织脚本和模板分开放read命令输出时会带上基础目录路径Agent 才能正确解析相对引用.cursor/skills/ ├── figma2code/ │ ├── SKILL.md │ ├── scripts/ │ └── templates/ └── code-review/ └── SKILL.md3.3 config.toml 接入 TaoTokenCursor 的 CLI 侧配置用config.toml把模型入口指向 TaoTokenKey 从环境变量读# ~/.cursor/config.toml [model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-5 [agent] skills_dir .cursor/skills global_skills_dir ~/.cursor/skills agents_file AGENTS.mdapi_key_env指向环境变量名而不是明文这样配置文件可以进 Git。环境变量在 shell 里设置export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key想持久化就写进系统环境变量。3.4 settings.json 补充编辑器侧行为Cursor 的settings.json负责编辑器层面的开关和config.toml分工不同{ cursor.agent.skills.enabled: true, cursor.agent.skills.autoSync: true, cursor.agent.skills.agentsFile: AGENTS.md, cursor.agent.skills.projectDir: .cursor/skills, cursor.agent.skills.globalDir: ~/.cursor/skills, cursor.agent.skills.readCommand: cursor-skills read }autoSync打开后新增技能目录时编辑器会提示同步到AGENTS.md省去手动跑命令。readCommand要和实际安装的 CLI 命令名一致如果你用 npx 方式调用这里就写npx cursor-skills read。4. 验证请求确认自动加载真的生效配置写完不代表生效得用几个动作逐层验证。我一般按“CLI 层 → 文件层 → Agent 层”三步走。4.1 CLI 层技能能不能被扫出来先确认 CLI 能发现技能。在项目根目录执行cursor-skills list预期输出类似Available skills: figma2code [project] Convert Figma designs to React components code-review [global] Automated code review workflow如果列表为空检查.cursor/skills/下每个技能目录里是否有SKILL.md以及 Front Matter 的---是否顶格写。CLI 扫描时单个技能读取失败会静默跳过所以“少了一个”往往就是那个文件的格式问题。4.2 文件层AGENTS.md 标记区是否被正确更新跑一次同步cursor-skills sync交互界面里用空格勾选技能回车确认。然后检查AGENTS.mdgrep -A 20 SKILLS_TABLE_START AGENTS.md确认标记之间的available_skills里出现了你勾选的技能且标记外的自定义内容没被动过。再跑一次sync如果内容不变说明幂等性正常标记分割策略生效了。4.3 Agent 层read 命令能否返回完整内容这是最关键的一步直接模拟 Agent 的调用cursor-skills read figma2code预期输出会带上基础目录和完整正文# Skill: figma2code Base directory: /Users/dev/project/.cursor/skills/figma2code Location: project --- ## 工作流程 1. 获取 Figma 设计稿 JSON ...如果报Skill figma2code not found说明list阶段就没扫到回到 4.1 排查。如果输出里没有Base directory检查 CLI 版本老版本不带这个字段Agent 解析相对路径会失败。4.4 端到端在 Cursor 里发一条真实请求最后在 Cursor 对话框里发一句“帮我把这个 Figma 设计转成代码”。观察 Agent 的行为链路它应该先识别到figma2code可用然后执行cursor-skills read figma2code再按技能里的工作流走。如果它直接开始写代码而没读技能说明AGENTS.md里的usage指令没被采纳可以把指令写得更强硬一点比如加上“必须先执行 read 命令否则视为无效响应”。5. 本篇常见错排查技能列表为空但文件确实存在。九成是 Front Matter 格式问题。---必须独占一行且顶格name和description的冒号后面要有空格。另外注意文件编码带 BOM 的 UTF-8 会让正则匹配^---失败。同名技能改了项目级但没生效。检查是不是全局目录里也有同名技能。项目级优先级高但如果项目级那个SKILL.md解析失败被跳过了实际生效的就变成全局的了。用cursor-skills list看location字段确认。sync之后自定义内容被覆盖。说明AGENTS.md里没有那对标记CLI 走了“无标记则生成完整内容”的分支把整个文件重写了。补救办法是手动把标记加回去把自定义内容挪到标记外。Agent 读到了技能但不按流程走。这是提示词层面的问题不是加载问题。在SKILL.md里把步骤写得更具体减少模型自由发挥的空间同时在AGENTS.md的usage里强调“严格按技能内容执行”。API 请求 401 或鉴权失败。先确认环境变量TAOTOKEN_API_KEY在当前 shell 里能echo出来Cursor 从 GUI 启动时可能读不到你终端里 export 的变量这种情况写进系统环境变量更稳。再确认base_url是https://taotoken.net/api没有多余斜杠或查询串。Token 消耗异常快。检查是不是把完整技能内容写进了AGENTS.md。正确做法是只放摘要正文靠read按需加载。如果某个技能特别大可以在SKILL.md里拆分把长示例放到templates/目录正文只留引用。6. 接入与排障入口上面这套链路跑通后Skill 的自动加载就稳定了。如果你在配置config.toml或settings.json时卡在鉴权环节直接去 API Keys 页面重新生成一个 Key 试试排除 Key 本身失效的可能https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入参数、兼容格式、报错码这些细节接入文档里列得比较全遇到 4xx 先查文档再改配置https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你只是想先确认模型通不通不想动 Cursor 配置可以在模型对话页发一条测试请求验证 Key 和基址没问题后再回到编辑器里配https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content长期在 Cursor 里跑编码和 Agent 工作流的Coding Plan 的额度模型更适合这种高频调用场景不用每次按量计费https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后提一个实操细节cursor-skills sync建议在提交代码前跑一次把AGENTS.md的变更一起提交这样团队里其他人拉下来就能直接用不用各自再同步一遍。技能目录本身也进 GitSKILL.md的版本历史就是团队工作流的演进记录。