120+ 个 Agent Skill 管不过来？我造了套「包管理器」：仓库是源，链接是安装

一句话定位：我在给自己的 skill 生态造一套「包管理器」——仓库是源，链接是安装，doctor 是体检。

为什么做：痛点驱动

我的真实处境：3 个 Agent 环境（Claude Code / zcode / codex）× 5+ 个 skill 仓库 × 全局 120+、单项目 81 个 skill。这个规模下，手动管理必然崩溃：

设计上的关键取舍

六个工具不是一次设计出来的，是按痛点顺序长出来的（init → sync → installer → commit-push → doctor → link）。贯穿始终的只有一个决定：

宁要链接的复杂性，不要副本的不一致。

链接带来「即时生效」和「零冗余」，代价是断链风险和诊断需求——所以 doctor 不是附加品，而是这套架构的必要闭环。

这套工具本质上是把软件工程里管理依赖的那套直觉（source of truth、幂等安装、健康检查）搬到了个人 AI 工具上：skill 即代码，仓库即 registry，装完能体检。这不是「写了一些脚本」，而是一套有明确架构立场的分发体系。

设计理念

一句话总纲：一处维护，链接分发。

拆开是几条：

压缩成四个词：同源 · 链接 · 幂等 · 防御。

用户级别 skill 结构示例

我机器上的 skill 真实布局（仓库 → ~/.agents/skills → 各 Agent），结构图如下：

  ┌─ ① 仓库层 · 真实目录（事实源头，git 管理）
  │
  │    ~/Documents/git_repo/github_open_source/
  │      ├── skillctl/skills/             ← rf-* 工具集
  │      ├── baoyu-skills/skills/
  │      ├── agent-skills/skills/
  │      ├── cloudflare-cli/skills/
  │      └── khazix-skills/  …更多仓库
  │
  └──────────────┬─────────────────────────────────────
                   │  skills-link：逐 skill 软链接（幂等）
                   ▼
  ┌─ ② 全局汇聚 Store · ~/.agents/skills（~130 个 skill）
  │
  │      ├── rf-commit-push ──→ …/skillctl/skills/rf-commit-push
  │      ├── baoyu-translate ─→ …/baoyu-skills/skills/…
  │      ├── cloudflare ──────→ …/cloudflare-cli/skills/…
  │      ├── brainstorming/          真实目录 · npx skills add 装入
  │      └── .skill-lock.json       skills CLI 锁（来源/hash/时间）
  │
  └──────┬────────────────────────────────────────
              │ 目录级软链接：一次链接，全量镜像
              ▼
  ┌─ ③ Agent 消费层
  │
  │      ~/.claude/skills ──→ ~/.agents/skills    Claude Code（整目录链）
  │      ~/.zcode/skills  ──→ ~/.agents/skills    zcode（整目录链）
  │      ~/.cursor/skills ──→ ~/.agents/skills    cursor（整目录链）
  │      ~/.codex/skills/         仅存系统 skill（.system）· Codex 原生加载 Store
  │
  └────────────────────────────────────────

    写入旁路：GitHub URL ─RF-skill-installer→ npx skills add → Store（真实目录 + 记 lock）
    兜底诊断：skills-doctor 扫 ①②③ 全链路（断链 / lock 一致性 / SKILL.md 规范）
    项目级另册：repo/.claude/skills → .zcode/.codex（skills-init / skills-sync，与用户级独立）

图例：

• ─→ 软链接（仓库更新即时生效，Store 只持有链接）
• 无箭头 = 真实目录（两种来源：仓库本体、npx skills add 直装并记入 lock）
• …/ 路径缩略 = ~/Documents/git_repo/github_open_source/

核心就是三层一链：仓库是源，Store 是汇，Agent 用链接消费。

重点看 ③ Agent 消费层的链接方式——两种形态并存，各有原因：

整目录链（Claude Code / zcode / cursor）：~/.agents/skills 是基准，~/.claude/skills、~/.zcode/skills、~/.cursor/skills 是消费层，都把整个目录直接软链接到基准，因此消费层零维护——基准目录里任何 skill 新增、删除、更新，走整目录链的 Agent 全部即时自动同步，无需任何手动操作。

**原生加载（codex）：**新版 Codex 直接读取 ~/.agents/skills，无需任何链接；~/.codex/skills 仅保留系统自带的 .system 目录。旧版 Codex 不认 Store、目录又被系统 skill 占用，曾采用「真实目录 + 逐 skill 链接」的折中形态，新版已不需要。

殊途同归：无论整目录链还是原生加载，都保证「基准一更新，消费层即时生效」——消费层永远零维护。

项目级别 skill 结构示例

我机器上的「技术博客」项目 skill 真实布局，结构图如下：

┌─ ① 事实源 · tech-blog/.claude/skills（真实目录 · git 管理）
│
│      81 个 skill，全部为目录本体，无外部链接
│        ├── rf-github-to-blog / rf-daily-ai-news / rf-publish-to-wx …   博客工作流
│        ├── baoyu-markdown-to-html / human-writing / diagram-design …   写作 · 第三方
│        └── …
│
│    同级配套    CLAUDE.md（本体 · 规则唯一来源）
│                AGENTS.md（stub · 仅引用 CLAUDE.md，不单独更新）
│    .claude/ 下  commands / hooks / scripts / settings(.local).json
│
└──────────────┬────────────────────────────────────────
               │  skills-init 建骨架 · skills-sync 增量维护
               │  逐 skill 相对软链接：../../.claude/skills/<name>
               ▼
┌─ ② Agent 镜像层（消费方，与事实源同仓库同层级）
│
│      .zcode/skills/    81 条目 ──┐
│      .codex/skills/    81 条目 ──┤ 每条 ──→ ../../.claude/skills/<同名>
│      （.cursor/skills 未启用）    │
│
│      ✓ 零断链：81 ↔ 81 ↔ 81 完全对齐（skills-doctor 可随时复核）
└────────────────────────────────────────

  与用户级的关系：此处全部 skill 为项目私有，不经由 ~/.agents/skills（两套独立模型）；
                  管理工具本身（skills-init / sync / doctor）却来自用户级链路
                  （skillctl 仓库 → Store → ~/.zshrc alias）—— 用全局的钥匙，管局部的门
  写入路径：GitHub → npx skills add（项目级）或手写 → 落入 ① 本体 → sync 镜像到 ②

图例：

• ──→ 软链接（这里全部是 ../../ 相对路径链接，仓库整体移动不断链）
• ① 是本体、② 是镜像：skill 只在 .claude/skills 维护，zcode/codex 即时生效
• 与用户级图的关键差异：用户级是「目录级整链」（~/.claude/skills → Store），项目级是「逐 skill 相对链接」

下面逐一展开介绍每个 skill。

skillctl 介绍

rf-skill-init

环境初始化：给项目 skill 搭好单一事实源。 以 .claude/skills 为基准目录，其他 Agent 目录（.zcode/skills、.codex/skills）自动建立软链接关联；后续新增、更新 skill 后通过 skills-sync 一键同步，处处即时生效。

当你在新项目目录下需要使用 Skill 时：

• 触发：/rf-skill-init
• 效果：创建 .claude/skills 基准目录，并与 .zcode/skills、.codex/skills 建立关联。

CLI：skills-init

安装 alias 后可在任意项目目录的终端直接初始化，与对话内 /rf-skill-init 完全等价：

skills-init                <span># 初始化（已初始化的项目自动跳过）</span>
skills-init --force        <span># 跳过检查，强制执行并输出完整报告</span>
skills-init --keep claude  <span># CLAUDE.md / AGENTS.md 不一致时保留 CLAUDE.md</span>
skills-init --keep agents  <span># ……保留 AGENTS.md（另一方改为软链接）</span>
skills-init --dry-run      <span># 预览模式，不做任何修改</span>
skills-init .codex/skills .cursor/skills  <span># 自定义目标目录</span>

三个值得知道的行为：

• 除 skill 目录与软链接外，还会顺带统一 CLAUDE.md / AGENTS.md——最终一个为事实源、另一个为软链接，内容不一致时交互询问保留方（或用 --keep 指定）；
• 幂等可重跑：已正确初始化的项目直接跳过，指向错误的链接自动修复；
• 可从项目任意子目录运行，自动定位 git 仓库根目录。

rf-skill-installer

快速安装：把「发现一个好仓库」变成一条命令。 在任意 Agent 对话里贴上 GitHub skill 仓库地址，自动拉取仓库的 skill 信息，并推荐项目级 / 全局、Claude Code 等常用安装方式。

执行效果如下：

rf-commit-push

Git 自动化：先看再动，一口气完成提交推送。 分析当前仓库改动，生成规范的 Conventional Commits message，依次完成暂存 → 提交 → 推送；全程先看 diff 再动手，敏感文件主动确认，不盲目 git add -A。

完成一个阶段性开发任务后：

• 触发：/rf-commit-push 或「git 提交代码」
• 效果：自动分析改动并推送到远端，无需繁琐的 Git 命令。

rf-skill-link

全局链接：多仓库 skill 一处汇聚。 同时维护多个 skill 仓库时，每个仓库只维护自己的源码，所有 skill 以软链接汇聚到同一个全局目录，形成单一事实源的 skill 结构。

• 触发：/rf-skill-link（在仓库根目录）
• 效果：仓库 skills/ 下所有 skill 以软链接进入 ~/.agents/skills，仓库更新即时生效；删除 skill 后重跑即自动清理。

CLI：skills-link

执行效果如下：

rf-skill-sync

跨环境同步：一处更新，处处生效。 通过软链接保持项目内所有 Agent 的 skill 目录一致：当你在 .claude/skills 下新增、删除或更新了 skill，其他 Agent 目录自动跟上，失效链接自动清理。

• 触发：/rf-skill-sync
• 效果：自动更新所有 Agent 目录下的软链接。

CLI：skills-sync

在我的个人知识库项目中的执行效果——自动将 .claude/skills 下的 skill 软链到其他常用 Agent 目录：

rf-skill-doctor

状态诊断与修复：skill 的全链路体检 + 一键安全修复。 自动识别执行位置——在 skill 源码仓库或含 skill 的项目里运行时，扫描项目级 skill 健康状态；在普通目录运行时，扫描用户级全局目录：Store 内部、整目录链消费端，以及真实目录型 Agent 目录内部的逐 skill 链接（历史遗留形态的兜底），均输出诊断报告；--autofix 可一键应用全部安全修复。

当发现 Skill 没生效或目录混乱时：

• 触发：/rf-skill-doctor 或「skill 健康检查」
• 效果：定位断连的软链接或不符合规范的 SKILL.md 并提供修复建议，--autofix 一键完成全部安全修复。

CLI：skills-doctor

安装 alias 后可在任意目录的终端直接体检，与对话内 /rf-skill-doctor 完全等价：

skills-doctor                 <span># 体检：用户级全局 store + 当前项目</span>
skills-doctor --json          <span># 输出机器可读 JSON</span>
skills-doctor --fix           <span># 重建失效的消费端软链接</span>
skills-doctor --autofix       <span># 一键应用全部安全修复（含 --fix / --clean-backups）</span>
skills-doctor --clean-backups <span># 删除 skills-link --force 备份</span>

--autofix 会修什么（全部幂等、改动前先备份、修复先于诊断执行——报告反映修复后状态）：

• 消费端软链接重建：失效或指向错误的链接重链到 store；
• lock 残留清理：磁盘上已不存在的跟踪条目从 lock 中移除（改动前备份 lock）；
• SKILL.md name 对齐：frontmatter name 与目录名不一致时改写为目录名（仅真实目录，软链接目录不穿透写入）；
• force 备份清理：删除 skills-link --force 留下的 *.bak-时间戳 备份；
• 真实目录型 Agent 目录断链修复：store 有同名则重链，目标已消失且无同名则移除；
• 项目模式 git 修复：.gitignore 补齐推荐条目，并取消跟踪非源头镜像目录。

非确定性问题一律只提示、不动手：真实目录消费端、非法 lock JSON、双源副本、junk 条目等——这些留给用户决策。

在我的技术博客项目下运行，输出用户级与项目级两份诊断报告：

在我的 skillctl 源码项目下的运行效果：

如何安装

1. 自然语言安装（推荐）

在 Claude Code 中直接说出需求即可，无需手动复制命令，Claude 会替你完成安装：

# 只安装 skill 套件
帮我安装这个仓库的 skill：https://github.com/wangruofeng/skillctl

# 同时安装 skill 套件和配套 CLI 命令
帮我安装 https://github.com/wangruofeng/skillctl，skill 之外把 skills-init / skills-sync 这些 CLI 命令也一起装好

CLI 命令以 alias 指向本地源码，建议固定一个 clone 目录长期维护。

2. 安装本仓库 Skill

通过 skills CLI 一键安装（推荐）：

<span># 查看本仓库可用 skill</span>
npx skills add wangruofeng/skillctl --list

<span># 项目级安装到 Claude Code（推荐：仅当前项目 + 自动确认）</span>
npx skills add wangruofeng/skillctl -a claude-code -y

<span># 项目级安装（写入当前项目 .claude/skills/）</span>
npx skills add wangruofeng/skillctl

<span># 全局安装（所有项目可用）</span>
npx skills add wangruofeng/skillctl -g

<span># 全局安装到 Claude Code</span>
npx skills add wangruofeng/skillctl -g -a claude-code -y

只装某一个 skill 时，可加 --skill <name>，例如：

npx skills add wangruofeng/skillctl --skill rf-commit-push -a claude-code -y

默认推荐「项目级 + Claude Code」：skill 跟随项目、不污染全局。仅在需要跨项目复用时再选 -g。

3. 从源码本地使用

git <span>clone</span> https://github.com/wangruofeng/skillctl.git
<span>cd</span> skillctl

运行 /rf-skill-link（或 bash skills/rf-skill-link/scripts/link.sh）把 skills/ 下各 skill 软链到 ~/.agents/skills/，仓库内更新即时生效；也可链到项目的 .claude/skills/，再用 /rf-skill-sync 同步到其他 Agent 目录。

4. 安装全局 CLI 命令（可选）

方便在终端直接调用 skills-init / skills-sync / skills-doctor / skills-link：

<span># 安装同步工具 → skills-sync</span>
bash skills/rf-skill-sync/scripts/install.sh

<span># 安装初始化工具 → skills-init</span>
bash skills/rf-skill-init/scripts/install.sh

<span># 安装诊断工具 → skills-doctor</span>
bash skills/rf-skill-doctor/scripts/install.sh

<span># 安装全局链接工具 → skills-link</span>
bash skills/rf-skill-link/scripts/install.sh

安装后执行 source ~/.zshrc（或新开终端）即可使用。卸载加 --uninstall。

使用指引

装完之后不需要记忆任何概念，记住一条主线即可：所有维护只发生在「事实源」一处，其余交给工具。

最小上手路径（3 步）

1. 在项目根目录执行 skills-init（或对话内 /rf-skill-init），建立基准结构；
2. 日常在 .claude/skills 下新增、删除或更新 skill；
3. 每次变更后跑 skills-sync 同步；感觉 skill 行为异常时，跑 skills-doctor 体检。

更复杂的场景，按需对号入座：

最后补充两点使用习惯：

• CLI 命令与对话内 skill 完全等价——终端里用 skills-*，Agent 会话里用斜杠命令或自然语言（如「skill 健康检查」）即可；
• 所有工具幂等可重跑——重复执行安全，出错时「再跑一次」往往就是修复。