多 IDE/Agent 环境下的 Skill 管理方案

背景

在同一个工程项目中，团队成员可能使用不同的 IDE/Agent(例如 Codex、Cursor、GitHub Copilot 等)。尤其是在 token 消耗较快的情况下，单个开发者也可能需要在多个 IDE 之间切换。如果每个工具都维护一份独立的 skills，会带来以下问题:

不同 IDE 的 skill 存储路径不同，导致 skill 内容重复且难以同步
如果将每个 IDE 的 skill 存储文件都同步到项目仓库，会污染版本管理，增加心智负担

设计目标

单一事实源：技能定义只维护一份
一键分发：可同步到多个 Agent/IDE
本地隔离：IDE 运行目录不污染仓库版本管理
可重复执行：多次执行结果稳定

实现方案

虽然可以设计一个独立的 skill Git 仓库单独维护，但 skill 本身是项目的有机组成部分，新建仓库会增加维护成本，必要性不大。

因此采用以下方案:

在项目中新增 agent-skills/ 目录作为共享 skill 的统一源
通过 npx skills add 完成安装分发
通过 .git/info/exclude 忽略本地产物，避免污染 .gitignore

配置脚本

1. 同步到所有已安装的 Agent（自动识别）

json 复制代码

"skills:sync": "npx skills add ./agent-skills --skill '*' -y"

./agent-skills:指定项目目录为 skills 源
--skill '*':一次性安装全部技能，避免逐个声明
-y:非交互执行，便于脚本化和自动化

2. 同步到指定 Agent

json 复制代码

"skills:sync:target": "node scripts/skills-sync-target.mjs"

ini 复制代码

#!/usr/bin/env node

import { spawnSync } from "child_process";

const TARGET_AGENTS = ["codex", "github-copilot", "antigravity", "cursor"];
const SKILLS_SOURCE = "./agent-skills";
const SKILL_SELECTOR = "*";

if (!TARGET_AGENTS.length) {
  console.error("[skills:sync:target] No target agent configured.");
  process.exit(1);
}

const successAgents = [];

for (const agent of TARGET_AGENTS) {
  const args = [
    "skills",
    "add",
    SKILLS_SOURCE,
    "--skill",
    SKILL_SELECTOR,
    "--agent",
    agent,
    "-y",
  ];
  const result = spawnSync("npx", args, {
    stdio: "ignore",
    shell: false,
  });

  if (!result.error && result.status === 0) {
    successAgents.push(agent);
  }
}

if (successAgents.length > 0) {
  console.log(`Installed agents: ${successAgents.join(", ")}`);
  process.exit(0);
}

console.error("Installed agents: none");
process.exit(1);

用于只向特定的 Agent 分发 skills。

3. 本地忽略 IDE 目录

json 复制代码

"skills:exclude": "node scripts/sync-exclude.mjs"

javascript 复制代码

#!/usr/bin/env node

import fs from "fs";
import path from "path";

const EXCLUDE_FILE = path.join(".git", "info", "exclude");

// 需要忽略的目录或文件
const PATTERNS = [
  ".agent/",
  ".agents/",
  "openspec/",
  ".trae/",
  ".windsurf/",
  ".claude/",
  ".cursor/",
  ".codex/",
  ".github/",
];

function addExclude(pattern) {
  const content = fs.existsSync(EXCLUDE_FILE)
    ? fs.readFileSync(EXCLUDE_FILE, "utf-8")
    : "";
  const lines = content.split("\n");
  if (lines.some((line) => line === pattern)) {
    console.log(`  skip (already exists): ${pattern}`);
  } else {
    fs.appendFileSync(EXCLUDE_FILE, `${pattern}\n`, "utf-8");
    console.log(`  added: ${pattern}`);
  }
}

console.log(`Syncing local exclude rules to ${EXCLUDE_FILE} ...`);
PATTERNS.forEach(addExclude);
console.log("Done.");

该脚本将 .agent/、.agents/、.cursor/、.codex/ 等目录写入 .git/info/exclude。

为什么不直接写入 .gitignore? 实测发现如果在 .gitignore 中忽略 skill 和 command 所在目录,会导致部分 Agent 无法快捷唤醒相关功能。

4. 忽略 skills-lock.json

将 skills-lock.json 添加到 .gitignore 中，避免版本管理冲突。

使用流程

在 agent-skills/ 中定义和维护 skills
执行 pnpm skills:sync 分发到所有 Agent
执行 pnpm skills:exclude 配置本地文件排除规则
私有的 skill 以及 command 等在对应的忽略目录中进行维护

该方案实现了单一事实源、一键分发和本地隔离的目标，有效解决了多 IDE/Agent 环境下的 skill 管理问题。