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

skill 概览

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

为什么做：痛点驱动

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

痛点	症状	解法（skill）
副本漂移	同一 skill 复制到多个 agent 目录，改一处忘其他，版本渐渐不一致	init / sync：单一事实源 + 软链接，一处维护处处生效
多仓分散	baoyu、cloudflare、agent-skills......散在各仓库，想在任何项目用任何一个都麻烦	link：仓库汇聚到 `~/.agents/skills`，仓库更新即时生效
拷贝式安装失联	`npx skills add` 装的是快照，上游更新后本地沉默过期	link 用链接替代拷贝；installer 负责把「发现一个好仓库」变成一条可执行命令
链接会腐烂	删了 skill 留断链、`--force` 留备份、lock 与实际不符------tech-blog 里那批断链就是实例	doctor：全链路体检 + 一键安全修复（断链 / lock / SKILL.md 规范 / 备份）
流程摩擦	提交代码要在多个 git 命令间切换，还怕误提交敏感文件	commit-push：先看再动，一口气暂存→提交→推送

设计上的关键取舍

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

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

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

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

设计理念

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

拆开是几条：

关键词	内涵
单一事实源	数据只存一份（仓库 / `.claude/skills`），其余全是软链接镜像，永不复制
一事一具	每个 skill 只做一件事，Boundary 明确（Owns / Excludes）
幂等即修复	重复执行安全，重跑 = 同步 = 清理，无需记忆状态
先看再动	防御性执行：看清 diff 再提交，敏感文件必确认
约定优于配置	`rf-` 前缀、frontmatter 必填、scripts/ 归位，全靠规范不靠配置
说明书与实现分离	SKILL.md 是声明，scripts/ 是执行，`{baseDir}` 解耦路径
不绑死环境	路径自动探测、可覆盖、可传参，多 agent 通用
可自诊	doctor 兜底：链接断了、锁不一致，能发现、能修

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

用户级别 skill 结构示例

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

text 复制代码

  ┌─ ① 仓库层 · 真实目录（事实源头，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 真实布局，结构图如下：

text 复制代码

┌─ ① 事实源 · 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 完全等价：

bash 复制代码

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

三个值得知道的行为：

除 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 目录：

同步结果对比：.codex/skills 下为同名软链接同步结果对比：.zcode/skills 下为同名软链接

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 完全等价：

bash 复制代码

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

--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 会替你完成安装：

text 复制代码

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

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

粒度	Claude 会做什么	得到什么
只装 skill 套件	通过 `npx skills add` 安装（命令见下节）	会话内可触发 `/rf-skill-init`、`/rf-commit-push` 等全部 skill
skill + 配套 CLI	clone 本仓库到本地，链接 skill 并运行各 `install.sh`（见第 3、4 节）	额外获得终端命令 `skills-init` / `skills-sync` / `skills-doctor` / `skills-link`，`git pull` 即可更新

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

2. 安装本仓库 Skill

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

bash 复制代码

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

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

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

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

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

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

bash 复制代码

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

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

3. 从源码本地使用

bash 复制代码

git clone https://github.com/wangruofeng/skillctl.git
cd 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：

bash 复制代码

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

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

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

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

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

使用指引

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

最小上手路径（3 步）

在项目根目录执行 skills-init（或对话内 /rf-skill-init），建立基准结构；

日常在 .claude/skills 下新增、删除或更新 skill；

每次变更后跑 skills-sync 同步；感觉 skill 行为异常时，跑 skills-doctor 体检。

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

场景	命令 / 触发	效果
新项目初始化	`skills-init` / `/rf-skill-init`	建立 `.claude/skills` 基准目录，关联其他 Agent
skill 变更后同步	`skills-sync` / `/rf-skill-sync`	一处更新，其他 Agent 目录即时镜像
安装第三方 skill	`/rf-skill-installer` + 仓库 URL	生成推荐安装命令（项目级 / 全局）
汇聚自有仓库	`skills-link` / `/rf-skill-link`	多仓库 skill 软链到 `~/.agents/skills`
健康检查 / 排障	`skills-doctor` / `/rf-skill-doctor`	断链、lock 一致性、规范全链路体检；`--autofix` 一键安全修复
提交代码	`/rf-commit-push`	分析 diff 生成规范 commit，一口气推送

最后补充两点使用习惯：

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