1. Cursor 2.4 的 Subagents 与 Skills 到底解决了什么问题Cursor 2.4 这次更新里最值得开发者花时间研究的不是图像生成而是 Subagents子智能体和 Skills技能系统这两块。它们解决的是同一个核心矛盾当 AI 在代码库里处理的任务越来越复杂、持续时间越来越长时单一 Agent 的上下文会被撑爆任务边界也会变得模糊。Subagents 的思路是把一个父级 Agent 的任务拆成若干离散部分每个子智能体拥有独立的上下文、Prompt 配置、工具访问权限和模型选择可以并行运行。主对话只保留调度和结果汇总上下文更聚焦执行速度也更快。Cursor 内置了代码库调研、运行终端命令、执行并行工作流这几类默认子智能体开箱即用也支持自定义。Skills 则是动态加载的领域技能。它和 Rules 的区别在于Rules 是始终开启的声明式规则而 Skills 是按需发现的程序化指令。当任务涉及特定领域知识或工作流时Agent 可以自动发现并应用相关技能也可以通过斜杠命令手动调用。开发者通过创建 SKILL.md 文件来定义技能里面可以包含自定义命令、脚本和 how-to 指令。这两套机制要真正跑起来前提是模型通道稳定、Key 统一、CLI 和编辑器共用一套配置。如果你在用 TaoToken 作为统一 Key/API 通道那么 Cursor 2.4 的 settings.json 骨架就需要把 Subagents 和 Skills 的配置项一起纳入。下面我会给出可复制的配置骨架以及用 CLI 验证 Subagents 与 Skills 是否生效的具体动作。2. 接入前的 TaoToken 准备Key、通道与 CLI 环境在动 settings.json 之前先把通道侧的事情理清楚。TaoToken 在这里扮演的是统一 Key/API 通道的角色Cursor 编辑器、Cursor CLI、以及你本地的其他 Agent 工具可以共用同一个 Key不用每个工具单独配一套凭证。你需要先拿到 API Key。进入控制台后创建 Key建议按用途分 Key比如给 Cursor 编辑器一个、给 CLI 一个方便后续排查问题时定位来源。创建入口在控制台的 API Keys 页面。拿到 Key 之后确认两件事一是 API 基础地址TaoToken 的 API 入口是https://taotoken.net/api二是你要用的模型标识Cursor 2.4 的 Subagents 允许每个子智能体指定不同模型所以最好提前确认哪些模型在你的通道里可用。CLI 侧的环境变量建议统一命名避免和系统里已有的变量冲突。我习惯用TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL两个变量后面 settings.json 里也会引用同样的语义。这样编辑器配置和 CLI 配置指向同一套通道Subagents 在编辑器里跑和在 CLI 里跑行为一致。有一点要注意Cursor 的 settings.json 里不要硬编码 Key 明文尤其是团队协作场景。用环境变量引用或者用 Cursor 自己的密钥管理机制。硬编码的 Key 一旦提交到仓库后面轮换会很麻烦。3. settings.json 骨架Subagents 与 Skills 的可复制配置下面这份骨架是我实测下来比较稳的结构。它把通道配置、Subagents 定义、Skills 发现路径三块分开方便你按需增删。注意 JSON 不支持注释实际使用时把说明性字段去掉或改成合法键名。{ taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: claude-sonnet-4-20250514 }, agents: { subagents: { enabled: true, maxParallel: 3, definitions: [ { name: codebase-research, description: 调研代码库结构、依赖关系与调用链, model: claude-sonnet-4-20250514, tools: [read_file, list_dir, grep], promptFile: .cursor/subagents/codebase-research.md }, { name: terminal-runner, description: 执行终端命令并回收输出, model: claude-sonnet-4-20250514, tools: [run_terminal], promptFile: .cursor/subagents/terminal-runner.md }, { name: parallel-workflow, description: 并行拆分工作流并汇总结果, model: claude-sonnet-4-20250514, tools: [read_file, run_terminal], promptFile: .cursor/subagents/parallel-workflow.md } ] }, skills: { enabled: true, discoveryPaths: [.cursor/skills, ~/.cursor/skills], autoDiscover: true, slashCommands: true } }, context: { maxTokens: 120000, subagentContextIsolation: true } }几个关键字段说明。maxParallel控制同时运行的子智能体数量设太高会挤占通道并发设太低并行优势出不来3 到 5 之间比较平衡。subagentContextIsolation打开后每个子智能体有独立上下文主对话不会被中间过程污染这是 Subagents 的核心价值所在。discoveryPaths里同时放了项目级和用户级路径项目级技能随仓库走用户级技能跨项目复用。Skills 的 SKILL.md 放在.cursor/skills/skill-name/SKILL.md。一个最小可用的 SKILL.md 长这样--- name: db-migration description: 数据库迁移脚本的生成与校验流程 --- # 数据库迁移技能 当任务涉及 schema 变更时按以下步骤执行 1. 读取 migrations/ 目录下最新版本号 2. 生成新的迁移文件命名格式 V版本__描述.sql 3. 运行 npm run migrate:check 校验语法 4. 输出变更摘要等待确认后再执行name和description是 Agent 自动发现技能的依据写清楚触发场景自动发现才准。正文部分就是 how-to 指令Agent 加载后会按这个流程走。4. CLI 验证确认 Subagents 与 Skills 真的生效配置写完不代表生效必须用 CLI 验证。Cursor CLI 提供了几个诊断命令我一般按这个顺序走。第一步确认通道连通和 Key 有效export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api curl -s $TAOTOKEN_BASE_URL/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | head -c 500返回模型列表说明通道和 Key 都没问题。如果返回 401检查 Key 是否复制完整返回 404检查 baseUrl 是否多了或少了路径段。第二步确认 Cursor 读到了 settings.jsoncursor --diagnose agents这个命令会输出当前生效的 Subagents 定义和 Skills 发现路径。重点看subagents.definitions里三个内置子智能体是否都在以及skills.discoveryPaths是否指向你配置的目录。第三步实际触发一次子智能体。在 CLI 里发起一个需要调研代码库的任务cursor agent run 调研 src/ 目录的模块依赖关系输出调用链摘要观察输出里是否出现子智能体被调度的日志。正常情况下你会看到codebase-research子智能体被激活独立读取文件、grep 调用关系最后把摘要回传给主对话。如果日志里只有主 Agent 在逐个读文件说明 Subagents 没生效回到 settings.json 检查enabled和definitions路径。第四步验证 Skills 自动发现。在项目里放一个 SKILL.md然后发起一个匹配 description 的任务cursor agent run 帮我生成一个数据库迁移脚本如果 Skills 生效日志里会出现技能加载记录Agent 会按 SKILL.md 里的步骤执行而不是自由发挥。也可以用斜杠命令手动调用确认slashCommands配置生效。5. 本篇常见错排查配置不生效的六个原因settings.json 位置放错。Cursor 读取的是项目根目录下的.cursor/settings.json不是用户目录。放错位置时 CLI 诊断命令会显示默认配置你改的字段一个都不生效。JSON 语法错误导致整份配置被忽略。多一个逗号、少一个引号Cursor 会静默回退到默认配置不报错。用python -m json.tool .cursor/settings.json先校验一遍。环境变量没导出到 Cursor 进程。在 shell 里export了但 Cursor 是从桌面图标启动的读不到 shell 的环境变量。解决办法是在 Cursor 的启动配置里注入或者用 Cursor 自己的密钥管理。CLI 场景下在同一个 shell 会话里 export 即可。SKILL.md 的 frontmatter 格式不对。name和description必须在---之间且 description 要包含触发关键词。description 写得太泛自动发现匹配不上写得太窄稍微换个说法就触发不了。maxParallel 设得过高触发通道限流。子智能体并行请求会同时打到通道上如果通道侧有并发限制会出现部分子智能体超时。先把 maxParallel 降到 2 试稳定后再往上加。模型标识写错。Subagents 允许每个子智能体指定模型但模型标识必须和通道侧支持的完全一致。写错时子智能体启动失败主对话会收到一个空结果日志里不一定有明显报错。用第二步的cursor --diagnose agents确认模型标识。排查顺序建议从通道连通性开始再到 settings.json 语法再到环境变量最后到 Skills 文件格式。这个顺序能覆盖九成以上的配置问题。6. 把 Subagents 和 Skills 用顺手的几个实操建议Subagents 的价值在并行但不是什么任务都值得拆。我试过把一个小重构拆成三个子智能体结果调度开销比任务本身还大。判断标准很简单任务能不能被清晰切成互不依赖的几块且每块都需要独立上下文。能就拆不能就让主 Agent 顺序做。Skills 的 description 值得反复打磨。它决定了自动发现的准确率。我的做法是先写一版跑几个典型任务看触发情况误触发就收窄关键词漏触发就补充同义表述。SKILL.md 正文里的步骤要具体到命令和文件路径Agent 执行时才不会跑偏。通道侧建议给 Cursor 单独一个 Key。Subagents 并行时会放大请求量单独 Key 方便在控制台看用量和排查异常。如果同时用 Coding Plan 做长期编码任务把编辑器、CLI、Coding Plan 的 Key 分开管理出问题时能快速定位是哪条链路。配置骨架和验证动作都跑通之后你可以把这份 settings.json 提交到仓库团队其他人拉下来配上自己的 Key 就能用同一套 Subagents 和 Skills 定义。项目级技能随仓库走用户级技能放本地这个分层能让团队协作和个性化配置互不干扰。