用途
Synthesis Skills Manager 是 synthesis-skills 生态中的智能体原生技能安装器与管理器，设计为由 AI 智能体执行。它把技能视为“可执行的方法论”，负责安装、更新、来源追踪、漂移检测，以及在冲突时进行合成式合并（synthesis merge）。
架构与部署目标
工具围绕三种访问级别的仓库组织：
- synthesis-skills：public，开源，通用方法论技能。
- Personal skills repo：personal，仅所有者可用。
- Team shared skills repo：shared，团队成员可用。
部署目标包括：
- 通过 Claude 和 Codex 市场安装的公开 synthesis-skills 插件。
- ~/.claude/skills/：Claude Code 的私有个人技能。
- ~/.agents/skills/：Codex 及 Agent Skills 约定的私有个人技能。
- ~/.cursor/skills/：存在 Cursor 时直接部署。
- /path/to/project/.claude/skills/：使用项目作用域的 Claude 项目技能。
- /path/to/project/.agents/skills/：可移植项目技能，包含 Codex 发现。
资料明确说明 ~/.codex/skills/ 不是由源管理的部署目标，因为将其同时复制到 .codex 与 .agents 会造成重复发现。
来源追踪
每个已安装技能附带 .source.json（在源仓库中被 gitignore），记录 source_repo、source_type、source_path、source_commit、installed_at、installed_by 等字段。示例为 github.com/synthesisengineering/synthesis-skills 下的 synthesis-thinking-framework/SKILL.md。
主要命令
- install [repo] [skill-name]：从源仓库读取 SKILL.md，检查目标处是否已有同名技能；若存在则比较整目录校验和，不同则保留备份并在源仓库解决漂移（绝不只合并到已安装副本），随后复制目录、写入 .source.json、检查依赖并报告结果。
- update [repo]：对源仓库中每个技能执行安装流程，报告 updated、skipped（未变化）、merged（漂移已解决）。
- status：检查 Claude 与 Codex 中启用的插件，扫描私有/共享目标目录，按 .source.json 分组，比较已安装 SKILL.md 校验和，报告 OK、DRIFT（本地改动）、MISSING（源有未装）、ORPHAN（已装但无已知来源）；同时检查重复公开技能、依赖与访问层级。
- drift [skill-name]：读取两个 SKILL.md，给出差异摘要，并建议重装源、把本地改进移植回源，或在源侧执行合成合并。
- merge [skill-name]：读取源版本、已安装版本与 .source.json 中的共同祖先提交，识别双方改动，保留源的结构变更与不冲突的本地定制；真正冲突时展示双方版本询问用户；结果写入源仓库、提交并推送配置的远端，再重装或更新部署并校验。资料强调这与 git 合并不同：git 合并文本，此工具合并方法论。
依赖访问层级
每次安装与状态检查都强制执行：public 只能依赖 public；private 可依赖 public + private；shared 可依赖 public + shared。不允许跨集合的私有依赖；若私有技能需要共享技能功能（或反之），依赖必须先提升为 public。工具从 SKILL.md frontmatter 的 depends_on 读取依赖，结合插件与用户/项目技能清单校验并报告缺失或违规。
配置分离
带用户特定值的技能包含 ## Configuration 表格。安装时向用户提示配置表；若此前已配置过则保留；更新时绝不覆盖 Configuration 值，而是合并。
工作流示例
首次配置：在 Claude 与 Codex 添加公开仓库市场，安装并启用 synthesis-skills 插件，安装个人技能到 ~/.claude/skills/ 与 ~/.agents/skills/，安装共享项目技能，写入 .source.json，运行 synthesis-agent-conformance 检查重复与依赖，报告源版本与启用的运行时版本。
更新时检测到漂移：拉取各仓库最新；比较校验和；读取双方版本；若仅本地有改进则移植回源、提交推送并重装；若双方都改则执行合成合并并报告结果。
错误处理
源仓库本地不可用：报告缺失仓库并建议克隆。循环依赖：检测并报告。.source.json 损坏：从可信源重装，不从已安装副本推断来源。技能无 frontmatter：警告不符合标准，仍安装但标记待审查。
实现说明
该技能由 AI 智能体执行：智能体读取文件、比较方法论并在源侧解决冲突；确定性安装器与一致性脚本负责复制、清单、校验和与健康检查。各仓库的 install.sh 作为无 AI 智能体环境的引导/回退安装器，处理机械部分，但冲突时覆盖而非合成合并。漂移检测覆盖整个技能目录（脚本、参考、数据表，不止 SKILL.md）；每个漂移副本在覆盖前保存到 ${XDG_CACHE_HOME:-~/.cache}/<repo-name>-backups/<UTC-run-stamp>/<target>/<skill>/，运行结束警告列出各漂移技能与备份路径，备份保留最近 10 次运行。
release.py：跨客户端插件发布
对公开插件，脚本 scripts/release.py 自动化发布协议步骤（3–7）。资料说明该序列唯一要紧的失败模式是静默的：仓库即插件（市场清单无版本并指向 ./），推送即发布，但各客户端保留版本钉住的安装，不跟随远端，可能造成推送了却未安装。
命令形式包括：
python3 skills/synthesis-skills-manager/scripts/release.py --repo-root . python3 .../release.py --dry-run python3 .../release.py --check-only python3 .../release.py --acceptance-only python3 .../release.py --install-only
阶段依次门控：preflight → required checks → publish → 安装三个客户端 → verify → activate public CLI。preflight 要求三个插件清单一致、最新 CHANGELOG 条目与其匹配、工作树干净，并拒绝在误当作源检出的已安装缓存上运行。验收消费从 Git 推导变更范围，要求清单精确覆盖，解析绑定一次性事务、头提交与树、清单摘要和变更路径摘要的新结果。发布前重新验证已接受状态，并原子推送不可变提交 SHA 到三个生命周期 refs：refs/heads/main（edge）、refs/heads/stable（默认）、refs/tags/vX.Y.Z（精确组织钉住）。安装按各客户端自身命令顺序执行；对 Codex 需先升级插件市场再 plugin add，因为 Codex 从 git 市场快照安装。在破坏性刷新前，发布器将任一客户端保留的所有真实版本化缓存根快照到持久恢复归档，不可变发布标签提供权威跟踪字节。发布器持有单写者过渡锁，恢复缺失的 Codex 根、修复不完整的根，并在客户端命令返回后重复检查直到树十秒不变；同时安装 cache_guardian.py 到持久恢复根并验证用户级 launchd 或 systemd 监督器，在归档迁移前验证，返回前再次验证恢复。守护器共享发布锁，保护除最新客户端自有版本外的每个归档版本，在后续缓存替换后补回缺失历史根，绝不删除缓存路径或覆盖不同内容；恢复按最新历史优先执行。
版本说明
2.7.0（2026-09-04）：在 SQLite 内容寻址归档中去重历史负载；不可变逐版本清单保留路径、类型、模式与元数据，恢复创建独立文件；SHA-256 校验覆盖每个负载与清单；完整数据库含页开销保持在 512 MiB 预算内；经验证候选原子替换存储；遗留树仅在其完整恢复验证后才移动并删除；中断的退役按已提交版本清单恢复；归档感知的独立守护器与监督器在迁移或原生刷新前验证；源完整性包括权限而非仅字节。
2.6.3/2.6.2/2.6.1/2.6.0/2.5.1/2.5.0 的变更涉及历史缓存同步等待、规范完整性策略、运行时字节码排除边界、公开 CLI 激活、历史 Codex 根恢复优先级与持久后台守护器等，资料有详尽描述。
适用场景与限制
适用于需要跨 Claude、Codex、Cursor 管理公开/私有/团队技能并追踪来源、检测漂移、按方法论合并的团队或个人。限制：核心合并能力依赖 AI 智能体，install.sh 仅回退且冲突时覆盖；merge 以源仓库为写入目标；~/.codex/skills/ 不在管理范围；部分功能（收费、平台支持细节）资料未提供。