跨 AI IDE 的协作痛点：用了五六个 AI 编辑器，提示词（Skills）该怎么统一管理？

赶时间直接看：【💎 终极玩法：带有 Frontmatter 的按需路由分配（强烈推荐！）】

当一个人/团队同时用着 Cursor、Claude Code、Codex、VSCode Copilot 甚至更多 AI 编辑器时，每个工具都有自己对 "Skills / Rules / Instructions" 的定义、路径约定和调用规则。没有人能强迫团队只用一种工具------这篇文章不打算做这件事，而是探讨：在多工具并存的现实里，如何让 Skills 的维护不变成噩梦。

大家好！最近有朋友问了我一个非常真实、而且很多人/团队正在经历的痛点：

"现在 AI 编码工具太多了！我习惯用 Cursor，同事 A 喜欢用 VSCode Copilot，同事 B 是 Claude Code (cc) 的重度用户，甚至还有人在用 Antigravity 和 Codex...

问题来了：每个工具存放 AI 规则（Skills/Rules）的地方和格式都不一样！这要是团队协作，怎么保证大家的 AI 都遵守同一套代码规范？"

这个问题太痛了！如果不管，最后的结果就是：每个人的 AI 写出来的代码风格各异，甚至互相打架。

背景：我们在解决什么问题

近两年，AI 编码工具的数量爆发式增长。一个活跃项目里，同时存在以下工具并不罕见：

🛠️ 主流 AI Agent / IDE 核心配置路径一览

• Cursor
  • 路径： .cursor/rules/ 目录
  • 说明： 目前主推使用该目录存放 .mdc (Markdown + Cursor) 文件作为模块化 Skills，替代了早期遗留的根目录单文件 .cursorrules。
• Claude Code (cc)
  • 路径： CLAUDE.md (项目根目录) 以及 .claude/ 目录
  • 说明： CLAUDE.md 作为项目级的全局"工作说明书"；.claude/ 路径通常用于工具内部状态、记忆存储或分层指令管理。
• Codex
  • 路径： .codex/ 目录（例如 .codex/rules/ 或 .codex/agents/）
  • 说明： Codex 采用自己专属的 .codex/ 隐藏文件夹来管理系统提示词、自定义规则和任务工作流，并不是使用 AGENTS.md。
• Antigravity (Google)
  • 路径： .agents/ 目录（包含 agents.md 和 skills/ 子目录）
  • 说明： 原生识别该工作区目录。依赖 .agents/agents.md 来明确划分 AI 团队角色，配合 .agents/skills/ 目录存放大量的独立 .md 技能文件来驱动迭代循环。
• Windsurf (Codeium 开发)
  • 路径： .windsurfrules (根目录单文件)
  • 说明： 依然偏向使用单一配置文件，语法和设计逻辑与早期的 Cursor 规则体系有一定兼容性。
• VSCode + Copilot
  • 路径： .github/copilot-instructions.md 或 .vscode/settings.json
  • 说明： 官方推荐通过 GitHub 目录体系进行项目级指令注入，或者直接在 VSCode 的 Workspace Settings 中进行配置。

每个工具背后，都有不同的团队在做不同的产品决策。这些差异是结构性的，短期内不会消失。

---

🛠️ AI 编码工具官方配置规范与文档地址

工具名称	核心配置路径	官方文档 / 参考地址
Cursor	.cursor/rules/*.mdc	docs.cursor.com/context/rules
Claude Code	CLAUDE.md .claude/	code.claude.com/docs/memory
Antigravity (Google)	.agents/agents.md .agents/skills/	ai.google.dev/gemini-api/docs/antigravity-agent
GitHub Copilot	.github/copilot-instructions.md	docs.github.com/en/copilot/.../add-custom-instructions
Windsurf (Codeium)	.windsurfrules	docs.codeium.com
Codex CLI	.codex/	github.com/guanyang/open-agent-hub (开源 CLI 实现标准)

---

痛点在哪？为什么会乱？

大家回想一下，现在的 AI 工具是怎么读取项目规则的：

• Cursor ：喜欢读 .cursor/rules/ 目录下的文件。
• Claude Code ：默认读根目录的 CLAUDE.md。
• Codex ：依赖 .codex/ 目录存放规则。
• VSCode Copilot ：又有自己的 .github/copilot-instructions.md 路径。

如果你团队有一条新规："项目中必须使用 TypeScript，禁止使用 any"。

在过去，你得在 5 个不同的地方写 5 遍。一旦哪天规则要改，很容易漏掉某个文件。时间一长，这就成了一笔烂账。

今天，我就来教大家几招，用最简单易懂的方式，把散落在各地的 AI Skills 统一管起来！

核心解法：建立"规则大本营"（单一真相源）

不要去每个工具里单独写规则！我们需要建立一个"大本营"。

第一步：建一个统一的文件夹

在你的项目根目录下，建一个 .ai-skills（或者你喜欢的任何名字）文件夹。

以后所有的团队规范、API 约定、代码风格，全都在这里用 Markdown 写好。比如：

📦 你的项目
┣ 📂 .ai-skills
┃ ┣ 📜 coding-style.md  (代码规范)
┃ ┣ 📜 api-rules.md     (接口规范)
┃ ┗ 📜 git-commit.md    (提交规范)

第二步：让不同工具"抄作业"

有了 .ai-skills 这个统一的大本营，接下来怎么让 Cursor、Claude Code 等各个工具读取里面的规则，这里提供三个不同段位的玩法，按需自取：

🥉 青铜玩法：人工搬运（适合单人或刚起步的小团队）

最简单粗暴的方法。团队定下规矩：.ai-skills 是唯一的"真理之源"。

每次在里面新增或修改了 .md 文件后，开发者需要手动复制一份，或者复制里面的文本，贴到自己所用工具的配置里。

• 具体操作 ：你在 .ai-skills/vue-rules.md 里加了一条规则，然后手动把这个文件复制到 .cursor/rules/vue-rules.mdc 中。
• 优点：门槛极低，建个文件夹马上就能落地。
• 缺点：极其依赖自觉性。改了源头忘了复制，或者复制时漏了一半，会导致两边规则脱节。

🥈 白银玩法：文件软链接与原生引用（推荐中小型项目）

利用操作系统的特性或 AI 工具自带的语法，让工具的配置文件直接"映射"到大本营，省去复制粘贴的麻烦。

• 绝招 1：原生指令引用 (Import)

  有些聪明的工具允许"引用"。比如使用 Claude Code 时，你不需要把几百行规则写死在 CLAUDE.md 里，只需写一行路径导入：

  请严格遵守以下核心代码规范：
  @import "./.ai-skills/coding-style.md"

• 绝招 2：操作系统软链接 (Symlink)

  如果工具不支持 @import，我们可以用命令行的"快捷方式"。在终端里建立软链接，让工具以为文件在它的目录里，其实读的还是大本营的内容。

  例如，把大本营的技能同步给 Cursor（Mac / Linux）：

  # 在终端执行，给大本营的规则在 Cursor 目录下建个快捷方式
  ln -s ./.ai-skills/coding-style.md ./.cursor/rules/coding-style.mdc

  Windows 用户使用以下命令（需以管理员身份运行 PowerShell）：

  mklink .cursor\rules\coding-style.mdc .ai-skills\coding-style.md

• 优点 ：修改 .ai-skills 里的文件，所有链接或引用的地方会自动生效，不需要再手动搬运。

• 缺点：团队里如果有人用 Windows，有人用 Mac，软链接的命令和兼容性偶尔会出小状况。

👑 王者玩法：Node.js 自动化构建脚本

既然大家都在写代码，为什么不用代码来解决问题？我们可以写一个简单的 Node.js 脚本，根据各个工具的"脾气"，自动抓取 .ai-skills 里的内容并转换格式分发。

• 具体操作 ：在项目根目录新建一个 scripts/sync-ai-rules.js 文件，脚本逻辑如下：

  const fs = require('fs');
  const path = require('path');
  
  // 1. 读取大本营所有的规则文件
  const rulesDir = path.join(__dirname, '../.ai-skills');
  
  // 确保大本营目录存在
  if (!fs.existsSync(rulesDir)) {
    console.error('❌ .ai-skills 目录不存在，请先创建！');
    process.exit(1);
  }
  
  const files = fs.readdirSync(rulesDir).filter(f => f.endsWith('.md'));
  
  let allRulesText = '/* ⚠️ 本文件由脚本自动生成，请勿手动修改！*/\n\n';
  
  files.forEach(file => {
      const content = fs.readFileSync(path.join(rulesDir, file), 'utf-8');
      allRulesText += `\n### 规则: ${file} ###\n${content}\n`;
  
      // 2. 给 Cursor 自动生成对应的 .mdc 文件（确保目标目录存在）
      const cursorRulePath = path.join(__dirname, '../.cursor/rules', file.replace('.md', '.mdc'));
      fs.mkdirSync(path.dirname(cursorRulePath), { recursive: true });
      fs.writeFileSync(cursorRulePath, `/* 自动生成 */\n${content}`);
  });
  
  // 3. 把所有规则拼接在一起，塞给 Windsurf 或 Antigravity
  fs.mkdirSync(path.join(__dirname, '../.agents'), { recursive: true });
  fs.writeFileSync(path.join(__dirname, '../.windsurfrules'), allRulesText);
  fs.writeFileSync(path.join(__dirname, '../.agents/agents.md'), allRulesText);
  
  console.log('✅ 所有 AI 工具的规则已同步更新！');

• 进阶操作（真正的解放双手）：

  把你写好的脚本挂在 package.json 的命令里，配合 husky 或 lint-staged。只要有团队成员修改了 .ai-skills 里的规则并执行 git commit，系统就会在提交前自动运行上面的脚本，帮你把 Cursor、Windsurf、Claude 的配置全部刷新一遍。

• 注意⚠️ ：一定要把那些被脚本自动生成 的文件（比如 .windsurfrules）加入到 .gitignore 中。Git 仓库里只保留 .ai-skills 这个干净的大本营，避免代码冲突！

💎 终极玩法：带有 Frontmatter 的按需路由分配（强烈推荐！）

把所有的规则"一股脑拼接进去"，在实际工程中确实是个非常糟糕的做法。

这就好比在写前端项目时，把所有的路由组件和依赖全部打包进一个庞大的 app.js 里，不仅加载慢，还会严重拖垮性能。

为了实现按需加载，我们需要在 .ai-skills 里的每一个 Markdown 文件头部，加上一段类似 YAML 的元数据（Frontmatter），用来声明触发条件 和作用域。

给技能加上"触发器"

以一个前端组件规则为例，我们在 .ai-skills/vue-components.md 的最上面写上这些：

---
description: 仅在处理 Vue 3 和 Element UI 相关组件时触发
globs: "**/*.vue,**/components/**/*.ts"
---

# Vue 3 组件规范
1. 必须使用 `<script setup>` 语法糖。
2. ...

注意：globs 这里统一使用逗号分隔的字符串格式，方便脚本直接解析。

升级自动化脚本（实现按需分发）

我们需要修改 Node.js 脚本，让它能够识别这些头部信息，并针对不同的工具生成不同的"按需"策略。

• 对于 Cursor ：它原生支持按文件后缀匹配，我们提取 globs 字段写入 .mdc。
• 对于 Agentic 工具（如 Claude Code / Antigravity）：它们更像人类，我们需要给它们生成一个"技能目录（Index）"，告诉它遇到什么情况去读哪个文件，而不是把内容全塞给它。

const fs = require('fs');
const path = require('path');

const rulesDir = path.join(__dirname, '../.ai-skills');

if (!fs.existsSync(rulesDir)) {
  console.error('❌ .ai-skills 目录不存在，请先创建！');
  process.exit(1);
}

const files = fs.readdirSync(rulesDir).filter(f => f.endsWith('.md'));

// 用于生成给 Agent 看的"技能目录"
let agentIndexContent = '# AI Agent 技能索引\n请根据当前任务，按需使用工具读取以下技能文件：\n\n';

files.forEach(file => {
    const rawContent = fs.readFileSync(path.join(rulesDir, file), 'utf-8');

    // 简单解析 frontmatter (--- 之间的内容) 和正文
    const match = rawContent.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);

    if (match) {
        const frontmatter = match[1];
        const body = match[2];

        // 解析描述和匹配路径
        const descMatch = frontmatter.match(/description:\s*(.+)/);
        const description = descMatch ? descMatch[1].trim() : '通用规则';

        const globsMatch = frontmatter.match(/globs:\s*"?(.+?)"?\s*$/m);
        const globs = globsMatch ? globsMatch[1].trim() : '*';

        // 1. 为 Cursor 生成支持按需触发的 .mdc（确保目录存在）
        const cursorRulePath = path.join(__dirname, '../.cursor/rules', file.replace('.md', '.mdc'));
        fs.mkdirSync(path.dirname(cursorRulePath), { recursive: true });
        fs.writeFileSync(cursorRulePath,
`---
description: ${description}
globs: ${globs}
---
${body}`);

        // 2. 为 Agent 补充目录索引（类似微前端的基座路由）
        agentIndexContent += `- **${description}**: 请读取 \`.agents/skills/${file}\`\n`;

        // 3. 将单体文件拷贝到 Agent 的 skills 目录下备查（确保目录存在）
        const agentSkillPath = path.join(__dirname, '../.agents/skills', file);
        fs.mkdirSync(path.dirname(agentSkillPath), { recursive: true });
        fs.writeFileSync(agentSkillPath, body);
    }
});

// 最后，只把精简的"目录"写进主入口，而不是全量拼接！
fs.writeFileSync(path.join(__dirname, '../CLAUDE.md'), agentIndexContent);
fs.writeFileSync(path.join(__dirname, '../.agents/agents.md'), agentIndexContent);

console.log('✅ 按需加载规则已生成完毕！');

这种设计的精妙之处在哪？

1. Cursor 的精准打击 ：当你打开一个 .vue 文件时，Cursor 只会激活带有对应 globs 的 .mdc 规则，背景极其干净。
2. Agent 的自主决策 ：当 Claude 或 Antigravity 启动时，它首先读取的是只有几十行文本的索引文件。如果它发现你在要求修改页面样式，它会自己看到索引里写着"处理 CSS/UI 请读取 skills/ui-rules.md"，然后它会主动去查阅那个文件。

落地小贴士（避坑指南）

光有方案还不够，日常维护中这几个坑千万别踩：

1. 颗粒度要细，严格控制"作用域"（Scope）！

   既然我们做到了按需加载，那就不怕规则多，就怕单条规则变成臃肿的"上帝文件"。

   把 AI 的 Skills 当成组件来写，保持原子化！利用 Frontmatter 里的 globs 严格限定触发边界（比如只在 .vue 生效）。如果一条规则又管 CSS 又管数据库，AI 的注意力还是会涣散。

   另外，个人极其偏好的快捷键或极小众的工作流，千万别塞进公共的规则池里污染上下文。

2. 像 Review 代码一样 Review Prompt（确权负责）

   建议给 .ai-skills 文件夹加上代码所有权（如 GitHub 的 CODEOWNERS）。

   增加或修改 AI 规则必须经过 Tech Lead 或资深开发的审核。一句有歧义的 Prompt，可能导致整个团队的 AI 都在帮倒忙，甚至引起大面积代码返工。

3. 定期大扫除（Deprecation 机制）

   把 Skills 当作真正的业务代码一样对待！随着框架升级（比如 React 18 升 19，或 Vue 2 升 3），很多旧的防坑提示词可能已经失效。

   每个季度检查一遍，定期删掉那些已经"过时"的 AI 规则。如果你都说不清某条规则到底是为了防什么坑，那就果断删掉，保持大本营的纯粹与轻量。

总结

面对目前 AI 工具的大爆炸，最聪明的做法不是去死磕、强行要求团队所有人必须统一使用某一款 IDE 或 Agent。

包容多样的工具生态，把团队最核心的开发规范、业务逻辑抽离出来，建立一个纯粹的"规则大本营"，再通过自动化的脚本进行按需分发------这才是应对未来 AI 迭代洪流、长久且健康的团队协作之道！

快去你的项目里建个 .ai-skills 文件夹试试吧！如果你在落地过程中遇到什么有趣的坑或者更好的方案，欢迎在评论区交流~