sjskills 用于协调（reconcile）由项目已提交的 sjskills.toml 或工具固定全局基线所选定的精确技能状态。该工具负责经过验证的放置、来源（provenance）、隔离（quarantine）与恢复；它不发布源变更，也不执行临时的目录安装。
用途与边界 严格同步仅覆盖选定的全局或项目 .agents/skills 与 .claude/skills 根目录。未声明的目录会被移入可恢复的隔离区，包括未知副本和本地修改过的副本。内置技能、插件缓存以及旧版 Pi 副本不在该边界内。
此前被管理、但存在本地编辑的期望副本也会被保留在隔离区，然后替换为经过验证的已发布内容。计划（plan）会将这些报告为带原因 local-modification 的更新。这要求同一来源具有可信来源信息，并且当前树可验证；未知的期望副本仍会阻止协调。恢复被编辑的字节不会授予所有权。
四种状态需区分
- 源仓库的本地目录（catalog）可编辑，但尚未发布。
- 注册表（registry）标识协调可消费的已发布远程内容。
- 项目已提交的 sjskills.toml 选择项目配置档（profiles）与直接声明。
- 注册表定义了一个固定的、与机器无关的全局基线。
命令使用 优先使用 PATH 上的 sjskills。在工具源仓库中，若命令未安装，使用 bin/sjskills。除非用户要求，不要安装该命令或更改 PATH。
阅读 status 检查以了解状态命令、新鲜度、通告与 JSON 解释。在创建或更改配置档或直接声明、或解决需认证来源要求时，阅读项目选择（project selections）。仅凭 status 或配置本身并不授权协调。
请求分类
- 同步已配置状态：未限定的同步或协调请求，授权固定的全局基线与当前项目已提交的 sjskills.toml（若存在）。遵守显式的仅项目、仅全局、机器或保留限制。若不存在项目清单，仅协调全局基线并报告项目未配置；不要初始化它，也不要从已安装副本推断配置档。
- 解释或检查：对两个范围使用 status，用 profiles 查看可用选择，或用 plan / plan --global 进行完整选定范围审查。这些操作保留受管理根目录，但可能临时获取期望内容。不带动作的裸调用默认执行 status 检查。
- 配置项目：当用户要求采用受管理的项目技能或更改选择时，创建或编辑 sjskills.toml。使用选定的配置档、直接声明或两者，参照项目选择参考。保留无关条目；仅配置本身不授权 apply 或全局更改。
- 协调项目：审查 plan，仅当用户要求安装、引导、协调或同步项目时运行 apply，然后再次运行 plan。
- 恢复项目状态：仅恢复用户明确指定的确切隔离标识符，且仅在确认每个建模目标均不存在之后。
- 全局协调或恢复：在全局变更前阅读 references/global-rollout.md。同步请求提供协调授权；自行准备并审查所需证据，而不是要求用户批准哈希。恢复仍需一个指明隔离区的请求。
使用普通 Skills CLI 工作流来发现源技能名称或执行请求的临时安装。对于由 sjskills 管理的项目，将外部技能记录在 [[direct]] 中并通过 sjskills 协调；受管理根目录中未声明的临时安装会成为隔离候选。Codex 插件使用仓库的插件工作流。本地目录验证与发布不属于协调。
使用已配置的授权 请求授予授权；已提交的清单与固定基线定义期望集合。在该集合的受管理根目录内，继续进行经过验证的安装、更新（包括隔离并替换本地编辑过的受管理副本）、来源迁移以及未声明副本的可恢复隔离。在应用前总结已审查的操作，无需另一轮用户交互。对已授权的 apply 使用 --yes，除非用户要求交互式检查点。标志或计划产物不产生授权。
遵守显式要求保持本地编辑生效或保留特定路径的请求：若其计划将替换或隔离它们，则停止受影响范围。普通同步已授权在替换前将本地编辑保留在隔离区；无需覆盖标志或额外确认。
“覆盖并同步”不能解决未管理的期望副本、来源不匹配、损坏的来源信息、不安全边界或物化失败。在这些冲突上停止受影响范围，并解释所需的具体解决方案。不要强制采用、手动替换根目录、更改配置档或纳入另一台机器来使计划通过。除非用户要求全有或全无结果，否则完成独立的未受阻范围。
项目工作流 解析命令与项目根。若不存在 sjskills.toml，除非用户要求采用或初始化，否则停止。
对于带配置档的新清单，运行 sjskills profiles，使用用户选定的配置档，运行 sjskills init <profile> ...；然后添加请求的直接声明。对于仅直接声明的采用或已有清单，使用项目选择参考。不要从已安装副本推断配置档，也不要用 init 覆盖已有清单。
读取清单并运行 sjskills plan。总结安装、更新、隔离、未变更放置、手动或工作流管理的条目、警告与阻塞。区分期望状态漂移或冲突与失败的命令、网络请求或物化；操作失败不是有效计划。
将本地修改更新视为保留并替换操作进行审查，包括当前树已匹配已发布树但与其记录的安装不同的情况。在 apply 前，对未管理的期望副本、来源不匹配、格式错误或不可信来源信息、不安全文件系统边界、不可验证的额外项、物化失败或其他冲突停止。
对于已授权的项目协调，在计划通过审查后运行 sjskills apply --yes。遵守任何在预览处停止或保持交互确认的显式请求。
再次运行 sjskills plan。在仍有更改或阻塞时，不要声称状态精确。在正常的工作周期内保留每个报告的隔离标识符。
当预期内容在注册表支持的源中发生变化时，协调只能消费已发布的远程内容。不要应用仅本地的更改。若请求发布，遵循源仓库关于验证、审查、提交与发布的说明；这些机制不在本技能范围内。在协调前，解析注册表来源并验证其固定的远程引用包含每个预期技能树。当注册表指向别处时，本地或功能分支提交是不够的。
恢复 将恢复视为单独的变更。要求用户指明隔离标识符，检查其当前状态，并确认所有目标均不存在。运行：
sjskills restore <quarantine-id>
不要为使恢复成功而移动、删除或覆盖活动目标。若内容或来源信息发生变化，保留双方并报告冲突。恢复不会授予对未知或本地修改副本的所有权。被编辑的备份会替换新安装的来源信息，且没有所有权记录。之后运行 sjskills plan：恢复的未声明技能属于移除漂移；恢复的已编辑期望技能属于未管理冲突。
全局边界 全局协调使用固定的、与机器无关的基线。配置档选择项目技能；不要发明全局配置档、从主机名推断配置档或合成 Pi 专用副本。检查请求仅运行 sjskills plan --global；已配置同步继续通过经过验证的 apply。
--approved-plan 与 --approved-plan-sha256 标志将全局 apply 绑定到代理审查过的证据。其名称不要求单独的人工批准仪式：创建产物，检查每个操作与警告，计算其摘要，并在 apply 与最终 plan 中使用同一经过验证的可执行文件。同步请求涵盖此工作；审计、仓库验证或无关设置请求则不涵盖。恢复与冲突解决仍与使已配置期望集合精确分开。
完成 报告：
- 项目或固定全局范围，以及工作是只读还是变更；
- 相关时，选定的配置档或直接清单声明；
- plan 与最终 plan 结果，包括剩余额外项、阻塞与范围外遗留状态；
- 涉及远程支持的本地更改时的已发布引用证据；
- 保留或恢复的每个隔离标识符；以及
- 任何仍等待明确授权的变更。