场景指南

选作用域

项目作用域是默认。SKILL.mod 和 SKILL.lock 放在当前目录，安装进入 .agents/skills/。

--global 只用于用户级技能：全局声明存放在 skillmod store 之下，安装通常进入用户自己的 agent 技能目录。项目与全局声明是两份独立的东西，普通命令不会把它们合并。

接管存量技能

接管用户级技能和接管项目是两个独立步骤：每个作用域各有一份 manifest，可以只做一边，顺序不限。

接管用户级技能

用户级技能是这台机器上共享技能的落脚处：

它把 ~/.agents/skills/ 里的一切声明进 ~/.agents/skillmod/global/SKILL.mod，出处从上一个安装器记录的来源和共享快照缓存中恢复。

上一个安装器从 web 发现端点记录的 skill 没有 Git 仓库在背后：记录只留下 web 来源，条目报为 unresolved，作为本地声明保留。把发布它的仓库补进 known_sources，之后的 init 就能把它作为 Git 依赖接管，因为内容会对照该仓库校验。而上一个安装器本就标记为 local 的记录不是缺口：保持普通本地声明，没有提示，也不计入 unresolved。

接管当前项目

之后保持两个作用域对齐。两份 manifest 相互独立，要影响用户机器的命令必须带 --global：

引导已有项目

skill 目录已经存在、但还没有声明时，用 init：

init 在所选作用域里扫描 .agents/skills/，不改动现有目录、链接或文件：目录链接会被跟随以校验内容，断链、无法校验的内容和非法目录名会被报告并跳过。各目标中相同的条目会合并，每条候选路径都保留下来用于恢复出处。

出处从匹配的锁记录或已验证的快照中恢复，包括 monorepo 子目录和别名。init --global 还会导入上一个安装器的 .skill-lock.json，项目 init 读 skills-lock.json。已记录的 Git 来源和修订号始终权威，即使安装目录已经漂移；上游记录缺修订号时，只有内容完全一致，init 才采用最新的不可变解析。无法安全解析的来源作为本地基线保留，一个未解析条目不会拖垮整次导入。

导入同时写 SKILL.mod 和 SKILL.lock。替换已有声明需要 --force，它会先把原声明备份为 SKILL.mod.bak：

全局作用域只在明确要求时使用：

添加远端 skill

地址的形式是 <repository>[//<subdirectory-or-skill-name>][@<version>]。仓库名始终要写，// 接着选中仓库内的 skill：

精确的子目录始终优先于名字；唯一的名字会解析到 skill 的真实路径，所以 source 记录的是 github.com/acme/agent-skills//skills/review，而不是输入时写的简写。同一仓库里有多个 skill 叫同一个名字时，skillmod 报出候选路径并拒绝猜。

省略版本时，解析最新的不可变 tag；仓库没有任何 tag 时退到伪版本。分支名会被拒绝，地址不得携带凭据。

交互式终端每个候选一行：↑/← 和 ↓/→ 移动，空格切换选中，D 显示或隐藏当前的说明与命令，回车确认。--all 不再询问、直接安装全部已发现的 skill，只在选择已经明确时用；仓库有多个 skill 时优先交互选择，除非用户要的就是全部。--yes 不是一回事：它回答选择之后的确认；非交互环境跑多 skill 仓库必须说 --all 才能过选择这一步。在终端上 --yes 仍由用户挑选 skill，只跳过后续确认。share 和 remove 同理。

两个来源发布同一个 skill 名时，用显式的目录别名安装第二个条目：

长时间运行的 get 和 update 会在交互终端显示一个紧凑的动画状态块。远端版本检查只请求 HEAD、分支和 tag 引用；update 合并等价的仓库 URL，最多并发检查四个不同的仓库；仓库快照每次命令做一次完整性校验，并在整个 skill 发现过程中复用。

复现声明环境

clone 一个带 SKILL.mod 和 SKILL.lock 的项目之后：

sync 安装或对齐声明的内容，幂等，不会静默覆盖本地修改。返回退出码 3 时，逐个目标看结果：一部分工作已经完成，冲突的目标被保留。

sync --relink 只用于有意按配置的安装模式重建匹配的远端安装：

检查状态与来源

总览用 list：

list、why、verify 对每个安装目录的分类方式一致，不可能互相矛盾。它们还会把本地条目对照记录的基线：被编辑过的本地条目报为 local-drift，不是普通的 local；读不动的目录在哪里都是 unverifiable。

看单条用 why，参数是发布名或安装别名：

why 报告来源、解析出的版本、commit、dirhash、安装目录，以及每个已配置目标的状态。优先用它，而不是自己解读 .agents/skills/ 里的链接。

在 CI 里验证

退出码这样读：

给机器消费时加 --json，按命令和 action 标识分支，不要按翻译后的提示或终端文本。完整的 action 词表和报告结构见自动化与 CI。

更新依赖

先看状态，再更新全部远端条目或指定名字：

一个发布名可能对应多条带别名的声明；安装别名选中它对应的条目。选择器可能不唯一时，仔细核对输出。

update 与 get 的 latest 语义相同：每条远端条目移到最高的语义版本 tag（先子目录 tag，再根 tag），只有完全没有 tag 的仓库才跟随默认分支 HEAD 前进到新的伪版本。钉在 commit 上的条目——伪版本和 SHA——也会迁移到该 tag，同一 skill 以不同方式接管的机器因此收敛到同一版本。

较新的 tag 在远端消失时，skillmod 拒绝意外的语义版本降级。确认远端删 tag 是有意为之，才用 --allow-downgrade：

移除依赖

声明本身不要了，用 remove：

名字可以是发布名或安装别名，走位置参数或 --skill（-s，可重复、可逗号分隔，与 share 一致）；什么都不命名时，对 SKILL.mod 声明的内容打开选择：

裸 remove 交互挑选，需要终端；--yes 替代不了两者——它回答的是删除确认，而不是删什么。

只想停止分享、保留受管 skill 和声明，用 --agent：

不带 skill 名时，选择器只列出分享给指定 agent 的 skill，且默认什么都不勾。带 --all 时取消所有匹配 skill 的分享；只分享给其他 agent 的 skill 不受影响。agent 值可重复或逗号分隔。名字和 --all 不能组合。

干净的受管安装被事务性删除；被本地修改或无法校验的目录会保留，并报为部分完成。

声明已经手工改过、残留陈旧安装或锁记录时，用 prune：

不要用手工删缓存替代这两条命令。prune 从不删除链接目标或共享快照，也没有自动缓存逐出；手工删除快照前，先读仓库 reference 文档里的 storage 说明。

分享给其他 agent

skillmod 只管理 .agents/skills/ 一个目录，读取其他约定的 agent 需要在那里有一条链接。share 创建这些链接，并把每个 skill 链接到哪些 agent 记录进 SKILL.mod 的对应条目——这正是换台机器也能复现的原因，也让一个 skill 去 claude、另一个去 codex 成为可能：

选中的 skill 不在 SKILL.mod 里，会在同一轮被接管：已验证的锁基线或缓存快照保留它的远端来源和版本，否则作为本地条目记入 SKILL.lock，带当前内容哈希。只有选中的 skill 被接管，已有声明基线保持原样，--dry-run 只报告接管、不写状态和链接。尚未登记的镜像链接计入接管的 agent 列表。

带 --agent 时，skill 选择器只勾选已分享给每个指定 agent 的 skill：share --agent workbuddy 不会勾选只分享给 codex 的 skill，新 agent 默认什么都不勾。多个 agent 时，接受默认值会保留既有链接、不新增。

不带 --skill 和 --agent 时，列出已安装 skill 和 agent 目录供交互选择，两个列表都打开在既有状态上：已链接到某 agent 的 skill 是勾选的，所选 skill 已指向的每个 agent 也是勾选的。确认未改的选择因此是空操作；给几个 skill 加同一个 agent，就是先勾 skill、再勾 agent。

agent 名字是单个目录段，从作用域根下的 .<name>/skills 读取，所以声明只需要名字：--agent workbuddy 链接进 .workbuddy/skills，和其他 agent 一样记录。manifest 因此从不存路径——名字能在别的机器复现，路径不能。

目标里已有相同内容、或已有指向受管副本的链接，保留；内容不同的是冲突，按 get、sync、update 同样的逐冲突策略处理（--on-conflict=overwrite 或 =skip）。.agents/skills/ 作为分享目标会被拒绝：链接过去会挡住 verify 读取的目录。

声明就位后，链接自我维护：sync 重建被替换或漂移的链接，verify 报告本机存在的 agent 目录下缺失的链接，移除 skill 会带走它的镜像链接。

停止分享，share --remove --agent 与 remove --agent 等价：

存有外来内容的目标不动；没有剩余 agent 的条目整个字段去掉。--remove 现在是开关，agent 值属于 --agent。两种形式都保留受管副本和声明，包括分享链接本就缺失的情况；状态写失败会恢复暂存的链接。

安装模式

auto 优先链接到不可变的共享快照，链接不可用时退回复制；copy 创建独立目录。有意迁移时，覆盖配置的模式：

需要编辑已安装的 skill 时用 copy。不要通过链接安装编辑共享快照：链接指向的内容与机器上其他项目共享。普通 sync 保留匹配的安装且幂等，--relink 按所选模式有意重建远端安装。两者都尊重本地修改，--yes 也从不强制覆盖冲突文件。本地条目不自动迁移，只记录和校验。