skill-loadout

跨 Codex / Claude Code 的本地 skill 管理器。全局只常驻一个轻量 manager；具体业务 skill 或 plugin 整组在用户确认后，仅链接到当前 AI 窗口对应的项目目录，并自动带入依赖。

单文件 Python 标准库实现，plugin 负责 AI 窗口交互和生命周期 hooks。

工作方式

用户输入
  → hook 只读检测明确提到的 skill / plugin 组
  → AI 显示询问
  → 用户确认
  → 当前项目加载精确 skill 或 plugin 整组 + 依赖
  → 当前窗口直接读取 SKILL.md 并继续原任务

plugin 既用于归类和浏览，也可作为整组加载/禁用边界。确认加载 lark 会加载 catalog 中该组的全部 skill 快照及依赖；也可以先浏览后只确认 lark-calendar。整组禁用会清除 该组的显式根，但仍被其他活动根依赖的 skill 会保留并在预览中列出。

新窗口无法在用户发送第一条消息前主动说话，因此“新窗口直接询问”发生在第一条输入 后的首个 AI 回复中。

安装或从 v1 升级

需要 Python 3.9+。先确认当前 shell 能找到兼容解释器，并创建本机命令目录：

python3 --version
mkdir -p ~/.local/bin
cp loadout.py ~/.local/bin/loadout
chmod +x ~/.local/bin/loadout
command -v loadout

# 尚未归一化旧 skills 时先运行：
loadout migrate

# 预览并切换到项目模式：新备份 → 移除全局自有链接 → 保留库和外部项
loadout upgrade
loadout upgrade --apply

然后安装常驻控制 plugin。Codex 必须使用个人 marketplace，才能在任意项目目录生效； 不要把本仓库的 repo marketplace 当成个人全局安装入口。

首次安装或更新 Codex plugin（命令可重复执行）：

/usr/bin/python3 -c 'import yaml'
/usr/bin/python3 ~/.codex/skills/.system/plugin-creator/scripts/create_basic_plugin.py \
  skill-loadout --with-skills --with-hooks --with-marketplace --force
rsync -a --delete plugins/skill-loadout/ ~/plugins/skill-loadout/
/usr/bin/python3 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
  ~/plugins/skill-loadout
/usr/bin/python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  ~/plugins/skill-loadout
codex plugin add skill-loadout@personal

个人 marketplace 位于 ~/.agents/plugins/marketplace.json，plugin 源位于 ~/plugins/skill-loadout。如果之前装过仓库级的旧入口，可在个人入口安装成功后清理：

codex plugin remove skill-loadout@skill-loadout-local
codex plugin marketplace remove skill-loadout-local

Claude Code 使用 user scope 安装：

claude plugin marketplace add /absolute/path/to/skill-loadout
claude plugin install skill-loadout@skill-loadout-local
# 已安装旧版时刷新 cache/hooks/manager：
claude plugin update skill-loadout@skill-loadout-local --scope user

Codex 首次发现或 plugin 更新 hooks 后，需要在 /hooks 中审阅并信任两个 skill-loadout hook；信任按内容 hash 保存，hook 变化后会再次要求审阅。安装或更新后 重启 Codex 桌面端并新开窗口。Claude Code 新开会话后生效。

项目级命令

所有变更命令默认只预览；增加 --apply 才落地。

命令	作用
loadout project status --project <dir>	查看项目根 skills、依赖、预算和冲突
loadout project ensure <skill> --project <dir>	预览添加一个具体 skill
loadout project ensure <skill> --project <dir> --apply	确认后应用
loadout project remove <skill> --project <dir>	预览移除根 skill
loadout project enable-plugin <plugin> --project <dir>	预览整组加载 plugin
loadout project disable-plugin <plugin> --project <dir>	预览整组禁用 plugin
loadout match --project <dir> --prompt-stdin --json	hook 使用的只读 skill/plugin 显式匹配

超过 8,000 字符预算时，普通 --apply 会拒绝；用户看过预算变化并再次确认后，才使用 --allow-over-budget。

--apply 必须带全 preview JSON 返回的 project、library、plan_token 三个 pin （--expected-project、--expected-library、--expected-plan），由 CLI 强制而非依赖 AI manager 自觉；人工确认后可用 --force 跳过。确认等待期间若路径、依赖、预算、 catalog 或链接状态变化，apply 会拒绝并要求重新展示计划。

项目内的本机状态：

<project>/.skill-loadout/state.json
<project>/.agents/skills/<skill>  -> ~/.skill-library/<skill>
<project>/.claude/skills/<skill>  -> ~/.skill-library/<skill>

state.json 分开保存单项 roots 与 plugin_groups 的精确 skill 快照。catalog 后续变化 不会静默扩大已启用组；再次启用该组时会通过预览刷新快照。

库中已被删除但仍留在项目状态里的 skill，会在 project status 与 hook 上下文中以 missing_from_library 上报，只读路径不中断；装载路径仍然 fail-closed。

Git 项目只修改 .git/info/exclude 中工具自己的标记区块，不修改 .gitignore，也不 隐藏用户自己维护的 project skill。

显式调用规则

这些形式会触发询问：

$lark-doc
`lark-doc`
使用 lark-doc
plugin:lark-doc
lark-doc 帮我处理……
plugin:lark
加载 lark 插件组
整组禁用 lark plugin

research、teach、implement 等普通单词名不会因自然语言偶然出现而触发；必须使用 $research、反引号、plugin 限定或“使用/use”句式。

Plugin 目录

loadout catalog sync
loadout catalog list
loadout catalog show lark
loadout catalog unclassified
loadout catalog assign <skill> <plugin>       # 预览
loadout catalog assign <skill> <plugin> --apply

归类优先使用已安装 plugin manifest；人工归类只补足无法从 manifest 确定来源的库内 skill。名称前缀不会被自动写成事实。

若新迁移的库还没有任何 plugin 分组，可先用 loadout catalog unclassified 浏览未归类 skill；AI 新窗口也会把“未归类 skills”显示为独立选项，而不是要求先凭空选择 plugin。

安全与还原

• 只增删完整解析后指向 ~/.skill-library/<skill> 的自有软链。
• 项目真实目录、普通文件和库外软链永不覆盖。
• 项目状态、Codex/Claude 两端链接和 Git exclude 事务化；失败时回滚。
• hooks 只读且 fail-open；真正装载 fail-closed。
• upgrade --apply 和 migrate 都先生成 0600 全量备份，并打印精确还原命令：

loadout restore ~/skill-loadout-backup-<timestamp>.tar.gz

全局命令

保留 check（巡检坏链/漂移/未编组/预算）、migrate、restore。v1 的 use/add/remove/status 与 preset 机制已移除；旧 ~/.skill-library/presets/ 目录和 .active 不再被读取，可自行删除。

已知边界

• 不处理同一项目目录中多个窗口同时修改状态；不同目录天然隔离。
• 依赖仍通过库内 Markdown 的 ../<skill>/ 引用计算。
• ~/.codex/skills legacy 目录不归本工具所有，巡检只提示。
• plugin hooks 需要宿主完成一次信任；工具不能代替用户点击安全确认。

开发与验证

python3 -m py_compile loadout.py test_loadout.py test_project_mode.py
python3 -m pytest -q
/usr/bin/python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  plugins/skill-loadout/skills/loadout-manager
/usr/bin/python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  plugins/skill-loadout
claude plugin validate plugins/skill-loadout