@bebenzhu/skill-manager

AI CLI skills 多来源聚合 + 多工具分发管理器

聚合多个 skill 来源，分发到多个 CLI 工具，一处修改，多个工具同步。

解决的痛点

• Claude Code、Codex、Cursor、skills.sh 等工具各自管理自己的 skill，修改一处不能全局生效
• 在多台设备间同步 skill 缺乏统一方案
• 私人 skill 与公共 skill（从网络下载）混杂，权限不清

架构

              ┌─────────────────────────────────────┐
              │         skill-manager               │
              │   (聚合 + 分发 + git 同步)            │
              └─────────────────────────────────────┘
                          │
            ┌─────────────┴─────────────┐
            ▼                           ▼
   sources（来源）              merged（合并视图）
   ├─ repo/（git 私人）          ├─ format-sql → repo/format-sql
   ├─ skills.sh/（公共下载）     ├─ db-sync    → repo/db-sync
   └─ ...（可配置扩展）           └─ ...
                                        │
                              cli targets（CLI 工具）
                              ├─ ~/.claude/skills  → merged
                              ├─ ~/.codex/rules    → merged
                              └─ ...

核心设计：

• repo 是私人 skill 的唯一本地源（git 管理）
• external_sources 是外部 skill 来源（不参与 git）
• merged 是逐 skill 链接的合并视图
• cli.targets 通过 junction 指向 merged

修改 merged 下任意 skill（即修改源），所有 CLI 工具即时可见。

安装

npm i -g @bebenzhu/skill-manager

快速开始

# 1. 初始化
skill-manager init
# 跟随提示：填写 git 仓库、merged 目录、CLI 路径

# 2. 建立链接（含自动入 repo）
skill-manager link

# 3. 推送到远程
skill-manager push

命令

全名 skill-manager 可缩写为 skm，两者完全等价（如 skill-manager link ≡ skm link）。

核心命令

| 命令 | 说明 | |------|------| | init | 初始化配置（首次使用） | | link [skill] | 建立/修复所有链接（含自动入 repo） | | unlink <skill> | 断开某 skill 的链接（源目录保留） | | add <skill> | 在 repo 中创建新 skill（带 SKILL.md 模板） | | remove <skill> | 彻底删除 skill |

可观测性

| 命令 | 说明 | |------|------| | list | 列出所有 skill（默认显示 merged 可见视图） | | info <skill> [--verbose] | 查看 skill 详情（来源/路径/链接/git/同名冲突预警） | | doctor [--fix] | 健康检查（error/warn/info 分级，可自动修复） | | status | 架构状态 | | scan | 扫描所有来源 |

同步

| 命令 | 说明 | |------|------| | push [<skill>...] [-m msg] | 增量或全量推送 | | pull [--force] | 拉取并自动 link（默认拒绝未提交修改） |

配置

| 命令 | 说明 | |------|------| | config | 查看/修改配置 | | destroy | 清理所有本地数据 |

子命令别名：ls = list，rm = remove，st = status

list 命令选项

skm list                  # 默认输出
skm list --verbose        # 表格格式，含 NAME/SOURCE/STATUS
skm list --source repo    # 只显示 repo 来源
skm list --broken         # 只显示有问题的（断链/孤儿）
skm list --no-color       # 禁用颜色

info 命令示例

skm info format-sql
# format-sql
# ────────────────────────────────────────
# 来源:    repo
# 路径:    C:\Users\chenhao\.skill-manager\repo\format-sql
# merged:  ✓ format-sql → C:\Users\chenhao\.skill-manager\repo\format-sql
# 可见于:  claude-code ✓, codex ⚠
# git:     tracked, last commit 4 hours ago
# 文件: 1 个, 1 个子目录, 21.8KB

skm info format-sql --verbose   # 追加 SKILL.md frontmatter

doctor 命令示例

$ skm doctor
! cli        1 issue
   ! codex → C:\Users\chenhao\.codex\rules (不是 junction)

→ 0 error, 1 warn, 0 info
1 issue(s) require manual fix

$ skm doctor --fix   # 自动修复可修的（如断链）

典型工作流

场景 1：日常在 Claude Code 中创建 skill

# 在 Claude Code UI 中创建 skill（文件落在 ~/.claude/skills/，实际是 merged）
# 完成后运行：
skm link                 # 自动将真实目录移入 repo，建立链接
skm push                 # 推送到远程

场景 2：增量推送部分 skill

skm push format-sql              # 只推送一个
skm push format-sql db-sync      # 推送多个
skm push -m "fix: 解析 bug"      # 自定义 commit message

场景 3：从零创建全新 skill

skm add my-skill        # 在 repo 中创建并生成 SKILL.md 模板
# 编辑 ~/.skill-manager/repo/my-skill/SKILL.md
skm link                # 建立链接

场景 4：删除一个 skill

skm remove my-skill     # 从 repo 和 merged 删除
skm push                # 同步到远程

场景 5：多设备协作

# 设备 A：推送到远程
skm push

# 设备 B：拉取（默认拒绝未提交修改，保护本地数据）
skm pull
# 拉取后自动 link，无需手动 skm link

场景 6：健康检查

skm doctor              # 查看架构状态
skm doctor --fix        # 自动修复可修复项
skm info format-sql     # 查看单个 skill 详情

配置

配置文件：~/.skill-manager/config.yml

# Git 仓库（私人 skill）
git_repo: "https://gitee.com/bebenzhu/ai-skill.git"
branch: master

# 统一合并目录（所有 skill 聚合视图）
merged_dir: ~/.skill-manager/merged

# 外部 skill 来源（不参与 git 同步，目录可不存在）
external_sources:
  skills.sh: ~/.agents/skills
  # 可扩展：
  # npm: ~/.npm-skills

# 各 CLI 工具的目标路径（通过 junction 指向 merged_dir）
clis:
  claude-code: ~/.claude/skills
  codex: ~/.codex/rules
  # cursor: ~/.cursor/rules

认证

推荐使用 SSH Key：

ssh-keygen -t edd25519 -C "[email protected]"
# 将公钥添加到 Gitee/GitHub
# 仓库地址使用 SSH: [email protected]:bebenzhu/ai-skill.git

或使用 Personal Access Token（首次 push 时输入）。

目录布局

~/.skill-manager/
├── config.yml           # 全局配置
├── repo/                # git 仓库（私人 skill，扁平）
│   ├── format-sql/
│   ├── db-sync/
│   └── ...
├── merged/              # 逐 skill 链接的合并视图
│   ├── format-sql → ../repo/format-sql
│   └── ...

~/.claude/skills         # junction → ~/.skill-manager/merged/
~/.codex/rules           # junction → ~/.skill-manager/merged/

迁移指南（从 skill-sync 升级）

旧工具 @bebenzhu/skill-sync 已被弃用（npm deprecate）。新功能只在 @bebenzhu/skill-manager 中开发。

配置和仓库无需改动：

• ~/.skill-manager/ 目录保留
• 现有 skill 文件保留
• 仅需重新安装包：npm i -g @bebenzhu/skill-manager

命令变更：

• 旧版"建立链接"类命令已重命名为 link
• 其余命令功能保持或增强

License

MIT