skills-02.跨工具 Skills 配置管理调研

前文：《skills-00.学习路线与自建指南》 · 《skills-01.构建示例与Agent解析机制》

AI 编程助手我用得越来越多，手头却常同时开着 Cursor、Claude Code、Codex、WorkBuddy、OpenClaw。各家默认扫描的 Skills 目录不同，时间一长我反复撞上：

本地多份备份：同一套 Skill 被复制到多个 ~/.<agent>/skills/、.<agent>/skills/。
个性化优化漂移：在某个 IDE 里改顺了，其它工具仍是旧版，最后说不清哪份是真身。

前提：Skill 格式（目录 + SKILL.md）已基本形成行业共识（agentskills.io），本文不再当问题讨论。真正要解决的是：路径怎么统一、改动怎么不漂。

调研之后，我把市面解法按问题拆开；真正落地时，我采用 skills-manager-skills（本机 ~/.agents/skills/skills-manager-skills/，仓库 AI-skill-mcp/skills-manager-skills）作为 P1 + P2 的综合方案——它不是替代 npx skills 或 symlink 的新范式，而是把「真身 + 软链 + Git + 变动检测 + 远程推送」收成一套 Agent 可执行的流程。

多工具各自缓存 Skills，副本互相不同步

一、问题只有两块

问题	一句话	失败时我看到什么
P1. 路径分裂	各工具默认目录不同，我被迫复制	同一 Skill 在磁盘上出现多份拷贝
P2. 变更漂移	改了一处，别处不一致、收不回	各 Agent 目录里版本分叉

段末注释：Skill（智能体技能包）以 SKILL.md 为主入口，可附带脚本与参考材料。内容格式已大体互通；差异主要在「去哪找」。

常见目录（以官方文档为准，会随版本微调）：

宿主	用户级（示例）	项目级（示例）
Cursor	`~/.cursor/skills/`	`.cursor/skills/`（部分也认 `.agents/skills/`）
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex	`~/.codex/skills/` 或 `~/.agents/skills/`	`.agents/skills/` / `.codex/skills/`
WorkBuddy / CodeBuddy	`~/.workbuddy/skills/` 或 `~/.codebuddy/skills/`	`.codebuddy/skills/`
OpenClaw	`~/.openclaw/skills/`、`~/.agents/skills/`	`workspace/skills`、`workspace/.agents/skills`

预先说结论：P1 已有清晰、可规模采用的成熟解法；P2 的「成熟层」更薄——稳妥做法多半是「真身 + 软链 + Git 纪律」。我选的 skills-manager-skills 正是在此之上，把纪律和检测脚本化，并接上远程 Git Organization 备份。

二、速览：每个问题对应哪些成熟解法

问题	成熟解法（建议优先看）	演进中 / 补位
P1 路径分裂	① `.agents/skills/` 作跨工具约定目录 ② 真身目录 + 符号链接到各 Agent 路径 ③ `npx skills`（skills.sh）多 Agent 安装（默认 symlink） ④ 单产品内的多根加载（如 OpenClaw `extraDirs`）	Skilz、skillink、AgentSync 等更细分 CLI
P2 变更漂移	① 物理上只保留一份真身（symlink，忌 copy） ② Git 仓作权威源，只在真身仓改 ③ 跟社区上游用 `npx skills update`（管「上游→本地」）	Skilled（drift / upstream）、Adept（`sync-from`）等双向回流工具
P1 + P2 综合	`skills-manager-skills`：真身 + 软链 + 每 skill 独立 Git + 变动检测 + 远程推送 + 统一管理迁移	—

1 2	单问题 → 用第三节/第四节里的成熟块我日常 P1+P2 叠在一起 → 用 skills-manager-skills 把成熟块串成可执行流程

三、我的综合方案：skills-manager-skills

3.1 它解决什么

skills-manager-skills 是一个 Agent Skill（不是独立桌面 CLI），用自然语言触发后，由 Agent 按 SKILL.md 与 workflows/ 执行脚本，把调研里的成熟做法收成一条流水线：

能力	对应问题	做法
真身目录 `workspace.skills_root`（默认 `.agents/skills/`）	P1	所有 skill 实体只存中心目录
`migrate_skill.py` 迁移 + `--link-back` 软链	P1	各工具目录只保留链接，禁止 copy
与 `npx skills add` 集成（禁止 `--copy`）	P1	社区 skill 先落真身再软链
每 skill 独立 `git init` + `init_skill_git.py`	P2	真身即 Git 仓，改动可版本化
`watch.check_on_invoke` + `skills_config.py check-changes`	P2	调用时扫描 dirty 状态
`git.auto_commit`（ask / always / never）	P2	变动后自动或交互式提交
`skills-registry.yaml` 索引	P2	记录 remote、push 状态、本地变动
`remote_config.py` + GitHub Organization	P2	skill 更新后推送到远程备份
`workflows/unify.md` 统一管理	P1+P2	把散落各工具的实体 skill 迁入真身并软链回去
`remote_skills.py` 初始化拉取	P1+P2	从远程 org 检索并本地化已有 skills

配置与索引固定在本 skill 包内（skills-config.yaml、skills-registry.yaml），与用户可改的 skills_root 解耦——换中心目录后仍能找到配置入口。

3.2 架构（一张图记牢）

各宿主 .cursor/skills/、.claude/skills/ …
        │  symlink（仅链接，无实体副本）
        ▼
workspace.skills_root（默认 .agents/skills/）  ← 物理真身
        │  每 skill 独立 Git
        ▼
远程 GitHub Organization（可选）  ← 备份与跨机同步

skills-manager-skills/（本 skill 包）
  ├── skills-config.yaml    # 中心目录、org、auto_commit 等
  ├── skills-registry.yaml  # 索引：路径、dirty、push 状态
  └── scripts/              # 检测、迁移、推送

3.3 典型触发与流程

我说什么	Agent 读什么	做什么
首次安装 / 未初始化	`workflows/init.md`	AskQuestion 确认中心目录、远程 org、auto_commit → 扫描 → 每 skill `git init`
安装 skill	`SKILL.md` 安装节	真身有则软链；无则 `npx skills add`（无 copy）→ 软链到当前宿主
管理 skills / 统一管理	`workflows/unify.md`	默认仅当前宿主；明确「全部应用」才 `--scope all`
推送 skills / skill 已更新	`SKILL.md` 远程推送节	`remote_config.py push` + 更新 registry
检测到本地变动	`check-changes` + `auto-commit`	按策略提交并更新索引

默认范围：除非我说「管理全部应用的 skills」，否则只处理当前宿主（如 Cursor 的 .cursor/skills/），避免误动其它工具目录。

3.4 与市面成熟块的关系

skills-manager-skills 不重新发明 P1/P2 的底层机制，而是编排它们：

成熟块	在 skills-manager 中的位置
`.agents/skills/` 约定目录	`workspace.skills_root` 默认值
symlink	`migrate_skill.py --link-only` / `--link-back`
`npx skills`	安装社区 skill 的来源之一
Git 真身 + 只改真身	每 skill 独立仓 + `auto_commit`
远程备份	`remote.organization` + `push`

相对 Skilled / Adept：skills-manager 更偏「我自己的 Agent 工作流 + 脚本」，深度绑定 GitHub org 与 AskQuestion 交互；没有它们那种跨格式渲染（Skill → .mdc），但对我「多工具、同格式 SKILL.md」的场景足够。

3.5 局限（我仍要接受的）

Agent 驱动：依赖宿主能读 skill、能跑 Python 脚本；不是一条 skills-manager sync 就完事的独立二进制。
默认单宿主：跨全部工具要显式说「管理全部应用」。
远程侧偏 GitHub：gh / GITHUB_TOKEN；其它 Git 托管要自行扩展。
Windows / 云端：与 symlink 方案相同的平台限制；reference 里已写明。
行为一致：文件同步了，各宿主触发率仍可能不同。

3.6 安装与入口

# 本机（用户级真身示例）
git clone git@github.com:AI-skill-mcp/skills-manager-skills.git \
  ~/.agents/skills/skills-manager-skills

# 软链到当前宿主（例：Cursor）
python ~/.agents/skills/skills-manager-skills/scripts/migrate_skill.py --link-only \
  --canonical ~/.agents/skills/skills-manager-skills \
  --link-back ~/.cursor/skills/skills-manager-skills

之后在 Cursor 中说「管理 skills」或「安装 skill」，由 Agent 加载本 skill 并按路由执行。首次会走 workflows/init.md 初始化 skills-config.yaml。

四、P1：路径分裂——其它成熟解法（skills-manager 的底层块）

问题本质：格式通了，各宿主仍各扫各的目录，复制就成了默认动作。第三节的综合方案已覆盖 P1；若不用 skills-manager，仍可单独采用下列成熟块。

成熟方案 1：`.agents/skills/` 作跨工具约定目录

Agent Skills 客户端实现指南建议扫描 client 私有目录 + .agents/skills/；Codex、部分 Cursor 已直接认该目录。skills-manager 的 skills_root 默认即此路径。

成熟方案 2：单一真身 + 符号链接

1	ln -s ../../.agents/skills/my-skill .claude/skills/my-skill

skills-manager 的 migrate_skill.py 把这一步脚本化，并带备份与冲突处理。

成熟方案 3：`npx skills`（vercel-labs/skills + skills.sh）

跨 Agent 安装面最广的主流 CLI；默认 symlink 到 .agents/skills/ 再链到各宿主。skills-manager 安装社区 skill 时复用此命令，但强制不用 --copy。

1	npx skills add <owner/repo> -a claude-code -a cursor -a codex

以权威技能库为中心，经 CLI 同步到各 Agent

成熟方案 4：产品原生多根加载（单产品内）

OpenClaw skills.load.extraDirs 等；与 skills-manager 可并存（真身仍放 skills_root，OpenClaw 额外扫描）。

P1 补位

工具	角色
Skilz	多 Agent 安装，接近 `npx skills`
skillink	`.agents/skills/` → 各 Agent 软链
AgentSync	迁移 + apply/symlink

五、P2：变更漂移——其它成熟解法（skills-manager 的底层块）

问题本质：在某个入口改了 Skill，其它入口仍是旧内容，或改在了拷贝上。

成熟方案 1：禁止第二份实体拷贝

一律 symlink；skills-manager 在自检清单里明确「未使用 --copy」。

成熟方案 2：Git 真身 + 只改真身

每 skill 独立 Git 仓；skills-manager 用 auto_commit 与 check_on_invoke 把纪律半自动化。

成熟方案 3：`npx skills update`

管 上游 → 本地；skills-manager 安装社区包后，本地改动走自己的 Git + push，二者分工不同。

演进中：Skilled / Adept

工具	能力
Skilled	drift、upstream PR
Adept	`sync-from`、跨格式渲染

我若未来需要 Skill ↔ Rule 渲染，可再叠 Adept；当前同格式 SKILL.md 场景，skills-manager 已覆盖我的 P2 主路径。

六、问题叠在一起：怎么选

我的情况	推荐
只要搞懂市面有哪些块	读第四、五节成熟解法即可
多工具日用 + 要管路径 + 常改 skill + 要远程备份	`skills-manager-skills`（第三节）
很少改、不想装 skill 包	`.agents/skills/` + `npx skills` symlink
以 OpenClaw 为中枢	真身 + `extraDirs`；其它 IDE 仍走 skills-manager 或 `npx skills`

我的实际组合：

skills-manager-skills（编排层）
  → workspace.skills_root = .agents/skills/（P1 真身）
  → migrate / link-only（P1 软链）
  → npx skills add，禁止 --copy（P1 社区安装）
  → 每 skill Git + check-changes + auto_commit（P2）
  → remote.organization push（P2 远程）
  → unify 迁移散落 skill（P1+P2 一次性收敛）

仍难消掉的：宿主行为差异、云端读不到本机真身、供应链风险、新品路径未进 detect_tools.py 时要手补。

七、按问题选型（可直接用）

我的问题	优先采用	先别做什么
只有多备份（P1）	`.agents/skills/` + symlink 或 `npx skills`	用 `--copy`
只有漂移（P2）	真身 Git + 只改真身；上游用 `update`	再复制「最新版」
P1+P2（我的主诉）	skills-manager-skills	只装不管入口、不初始化 config
不想用 Agent 流程	第四节 + 第五节成熟块手工组合	指望单一社区 CLI 通吃 P2 回流

两句自检：物理上是否只有一份真身？→ 否，先 unify 或 migrate。是否要在非真身处改？→ 会，开 check_on_invoke 并约定只改 skills_root。

八、延伸阅读

格式共识（前提）：agentskills.io
我的综合方案：skills-manager-skills（本机 ~/.agents/skills/skills-manager-skills/）
P1 主流安装：vercel-labs/skills · skills.sh
P1 补位：Skilz · skillink
P2 演进：Skilled · Adept
单产品多根：OpenClaw Skills config

收束：P1 的成熟路是「约定目录 + symlink」；P2 的成熟路是「真身 Git + 别制造第二份」。skills-manager-skills 把这两块和我需要的远程推送、变动检测、统一管理收成 Agent 可执行流程——这是我调研之后的落地选择，而不是对市面方案的替代叙述。