命令参考

全局约定

以下 flag 对所有命令可见。项目作用域是默认；用户级技能另有彼此独立的声明，命令只有带上 --global 才会影响整机。

--json 之下 stdout 只承载机器可读的报告，脚本应按 command 与 action 标识分支，而不是依赖本地化文本。--yes 只回答选择之后的确认，不代替选择：它不会决定 get 装哪个 skill，也不会决定 remove 删哪条声明。

持久 flag 还有 --install-mode（auto 或 copy，覆盖配置）：auto 优先链接到不可变共享快照，链接不可用时退回复制；copy 创建独立目录，需要编辑已装 skill 时用它。--install-mode、--all、--allow-downgrade 与 --on-conflict 故意没有短写名——明显的字母要么有歧义、要么已被占用，长写法也更好读。

输出语言：帮助、摘要、提示与错误信息跟随 SKILLMOD_LANG，未设置时跟随系统 locale。JSON 字段名与 action 标识永不翻译。

命令逐条

init

把磁盘上已有的 skill 收编进 SKILL.mod 与 SKILL.lock。

• 扫描所选作用域的 .agents/skills/，全程不改动已存在的目录、链接与文件：目录链接会跟随以校验内容，断链、无法校验的内容与非法目录名会被报告并跳过。
• 来源从匹配的 lock 记录或已验证的快照中恢复，含 monorepo 子目录与别名；--global 额外导入上游安装器的 .skill-lock.json，项目 init 读 skills-lock.json。
• 已记录的 Git 来源与版本即使安装目录已漂移也仍然权威；上游记录缺版本时，只有内容完全一致才采用最新不可变解析；无法安全解析的来源保留为本地基线，不会让一条未解析条目拖垮整次导入。
• --global init 声明 ~/.agents/skills/ 的全部内容，写入 ~/.agents/skillmod/global/SKILL.mod；来自网页发现端点的 skill 没有 Git 仓库，报为 unresolved 并保留为本地声明，把发布仓库加进 known_sources 后，后来的 init 才能把它当 Git 依赖收养。
• 覆盖既有声明需要 --force：原 SKILL.mod 先备份为 SKILL.mod.bak 再重建；导入同时写 SKILL.mod 与 SKILL.lock。

get

从任意 Git 仓库取一个 skill，更新 SKILL.mod / SKILL.lock 并安装。

• 仓库名必须给出，// 之后选择其中的 skill：单段先按仓库根目录的精确子目录解析，再回退到 skills/ 下唯一的 skill 名；多个 skill 回答同一个名时报出候选路径，不猜。仓库自身就是单个 skill 时不需要 //。
• 版本只接受 semver tag 或 40 位 commit SHA，分支名因可变被拒绝；省略版本时按 <子目录>/v<最新> → v<最新> → 默认分支 HEAD 解析，最后者记录为伪版本。
• --alias / -a 指定安装目录别名，用于两个来源发布同名 skill 的场景。
• --all 不问便安装仓库发布的全部 skill；--yes 只回答选择之后的确认，多 skill 仓库的非交互运行必须显式 --all。交互终端里用 ↑/← 与 ↓/→ 移动、空格勾选、d 展开描述与命令、回车确认。
• 目标位置已有不同内容时走共用的冲突策略：默认逐个询问（覆盖 / 跳过 / 中止），--yes 下安全跳过，--on-conflict=overwrite 或 =skip 一次性作答。默认 auto 模式链接到共享快照；--install-mode=copy 装出可编辑的独立副本。

sync

把本地 skill 目录对齐到 SKILL.lock 钉住的状态。

• 幂等，失败回滚；永不擅自覆盖本地修改——冲突目标被保留并计入退出码 3，能进行的工作照常完成。
• --check / -c 只校验不修改，是 skillmod verify 的别名，与 --relink 互斥。
• --relink / -r 按配置的安装模式重新安装内容一致的远程 skill，只用于有意的迁移；先跑 --dry-run 看计划。
• 已安装文件不会被自动删除，清理陈旧安装交给 prune。
• 返回退出码 3 时查看逐目标结果：部分工作已完成，冲突目标被保留，对本地修改的决定权留给人。

share

把已装 skill 链接进 .claude、.codex 等 agent 目录，并把 agent 记进 SKILL.mod。

• agent 用一个目录段命名，从作用域根下的 .<name>/skills 读取；manifest 只存名字不存路径，换台机器就能复现链接。每个目标位置是指向托管副本的符号链接，文件系统不允许符号链接时退回保真复制；对托管 skill 的编辑会同时出现在所有链接里。
• 选中的 skill 若不在 SKILL.mod 中会被同轮收编：有已验证的 lock 基线或缓存快照就保留远程来源与版本，否则按当前内容记为本地条目；已有的声明基线不被改写。
• --skill / -s 与 --agent / -a 可重复或用逗号分隔，位置参数等价于 --skill；两者都省略时进入交互选择，且按当前状态预勾选——确认未改的选择是空操作。
• --all 不问便共享全部已装 skill；--on-conflict 取 ask（默认）、overwrite 或 skip，一次性回答目标已存在且内容不同的冲突；.agents/skills/ 被拒绝作为目标。
• --remove 必须配 --agent：只解除这些 agent 的链接，声明与托管副本保留，效果同 remove --agent；外来内容的目标位置不动。链接随后自维护——sync 重建被替换或漂移的链接，verify 报告 agent 目录下缺失的链接，移除 skill 会一并拆除镜像链接。

list

显示全部声明条目、版本与安装状态。

• 每条声明给出版本与状态：已装 / 缺失 / 可升级。
• list、why、verify 对每个安装目录给出同一套分类，三者不会互相矛盾：编辑过的本地条目报 local-drift 而非普通 local，读不出来的目录一律 unverifiable；本地条目对照记录的基线检查。

why

解释单条条目：声明、不可变来源与安装状态。

• 报告来源、解析出的版本、commit、dirhash、安装目录，以及每个已配置 target 的状态。
• 选择子可以是发布名或安装别名；一个发布名可能对应多条别名声明，选择子可能不唯一时留意输出。
• 查状态优先用它，而不是手工解读 .agents/skills/ 里的链接。

update

解析最新版本、更新 lock 并安装。

• 不给名字就更新全部条目，沿用 get 的 latest 语义：最高 tag 胜出（先子目录 tag，再根 tag），只有完全无 tag 的仓库才推进到默认分支 HEAD 的新伪版本。
• 钉在 commit 上的条目（伪版本与 SHA）也会迁移到该 tag，让以不同方式收养同一 skill 的机器收敛到同一版本。
• 较新的 tag 消失时，拒绝把 tag 锁意外降级；确认远端删 tag 是有意行为后才用 --allow-downgrade。
• 发布名可能代表多条别名声明，安装别名选中对应条目；选择子可能不唯一时先看输出。

verify

对照 SKILL.lock 校验每个安装；只读，CI 门禁。

• 检测到漂移以退出码 2 结束，实现与 sync --check 相同。
• 机器消费加 --json，按 command 与 action 标识分支，不依赖本地化文本。
• 退出码 0 / 1 / 2 / 3 的含义见页底速查表。

remove

删除声明并清理托管的安装。

• 名字可以是发布名或安装别名，走位置参数或 --skill / -s（可重复、逗号分隔）；什么都不指就交互式挑选 SKILL.mod 里的声明，这需要终端。
• --all 不问便取全部声明条目；名字与 --all 不能组合。--yes 只回答删除确认，不代替选择删什么。
• --agent / -a 只解除指定 agent 的共享，声明与托管副本保留；不带 skill 名时只列出共享给这些 agent 的 skill 且初始不勾选，配 --all 则解除所有匹配 skill 的共享；agent 值可重复或用逗号分隔。
• 干净的托管安装被事务性删除；本地改过或无法校验的目录会被保留，并报告为部分完成。

prune

清掉手改声明后留下的陈旧安装与 lock 记录。

• 声明已经手改、留下陈旧安装或 lock 记录时用它；删除前先列出并确认，先跑 --dry-run。
• 从不删除链接目标或共享快照，也没有自动缓存逐出；不要用删缓存代替 remove 或 prune。

upgrade

用已发布版本替换正在运行的 skillmod 可执行文件。

• 下载先对照发布附带的校验和验证，再替换可执行文件，与手动安装走同一信任路径。
• --check / -c 只报告有没有更新的发布，不下载；--tag / -t 装指定的发布 tag 而非最新发布；--dry-run 会下载并校验，但不替换可执行文件。
• 由包管理器安装的可执行文件，应继续通过那个包管理器升级。

退出码速查

verify 用退出码 2 表示漂移，sync、remove 等可能以 3 结束。完整的 action 词表与 JSON 报告结构见自动化与 CI。