skill-install-manager

技能安装管理器 — 自动读取技能列表文件，与当前全局已安装技能进行对比，找出未安装或存在更新的技能，并执行一键安装/更新。v3.0：所有流程、判断、渠道切换均由脚本自动完成，agent 只运行脚本并读取 JSON 报告。

触发条件

用户表达以下任一意图时触发。即使只是暗示或间接提及技能安装/管理工作，也应使用本技能：

• "检查并安装缺少的技能" / "看看哪些技能还没装"
• "同步技能列表" / "同步 skills" / "skill sync"
• "更新所有技能到最新版本" / "检查更新" / "skill update"
• "技能管理" / "skill manager" / "管理技能"
• "批量安装 skills" / "安装这些技能" / "一键安装"
• "从技能列表安装" / "按列表安装"
• "帮我整理技能" / "技能状态" / "看看技能"
• "把新技能装上" / "补一下缺少的技能"
• "npx skills" / "skills add" / "技能仓库"

执行模式（v3.0：单一脚本驱动）

agent 不再逐条执行安装命令。 全部流程由 scripts/sync-skills.js 一次跑完， agent 只做四件事：

1. 运行主编排脚本（默认全自动同步，或按需加参数）
2. 读取 JSON 报告（脚本写入 ~/.agents/skill-sync-report.json）
3. 向用户汇报结果（脚本输出的控制台摘要可直接转述）
4. 处理脚本标注的异常（见「异常处理」节，通常只需转告用户）

快速开始

🟢 一键同步（默认，最常用）

node "<skill-path>\scripts\sync-skills.js"

全自动完成：自更新 → 读取最新列表 → 对比安装状态 → 版本检查（并发+缓存）→ 依赖预检 → 安装/更新（五通道回退）→ 生成报告。

Agent 操作步骤：

1. 确认技能包路径（pwd 后定位 skill-install-manager/scripts/，路径大小写敏感）
2. 运行上面的命令（超时 10 分钟；脚本内部有逐级超时与降级，不会无限卡住）
3. 读取 ~/.agents/skill-sync-report.json，向用户汇报摘要
4. 若报告中有 ❌ 失败项或 ⚠️ 依赖警告，如实转告用户并给出建议

🔵 只对比不安装

node "<skill-path>\scripts\sync-skills.js" --compare --list "<list-file>"

🟣 安装单个技能

node "<skill-path>\scripts\install-skill.js" --name <skill-name> --url <origin-url>

主编排脚本参数（sync-skills.js）

列表文件查找顺序（未指定 --list 时）

1. ./skill-list.md（当前工作目录）
2. ./skills/skill-list.md
3. ./sandbox/dev/skill-list.md
4. <skill-path>\references\Reasonix-skill-list-v2.md（技能内置列表，默认兜底）

脚本内部流程（agent 无需手动执行，仅作理解）

⓪ 自更新 skill-install-manager 自身（update → add → codeload zip 三级）
      │
      ▼
① 定位并读取技能列表文件
      │
      ▼
② 新旧列表对比（自更新后标记 🆕新增 / 🗑️移除 / ➡️延续）
      │
      ▼
③ 解析列表（utils.parseSkillList，兼容注释行/重复 origin/_shared 条目）
      │
      ▼
④ 获取全局安装状态（npx skills ls -g --json → 锁文件兜底）
      │
      ▼
⑤ 版本对比（每仓库只查一次：缓存 → git ls-remote 15s → GitHub API 兜底，
   并发 4；40 位 hash 差异用 isRealCommit 校验，避免误报 outdated）
      │
      ▼
⑤.5 依赖预检（内置依赖表 + dependencies.local.json 覆盖）
      │
      ▼
⑥ 执行安装/更新（pendingDeps → 🆕 → missing → outdated；
   同仓库技能共享一次下载，仓库级并发 3，五通道回退）
      │
      ▼
⑦ 生成 JSON 报告（~/.agents/skill-sync-report.json）+ 控制台摘要

安装通道链（脚本自动逐级降级，无需 agent 干预）

• --cdn-first 时顺序变为：3 → 4 → 1 → 2 → 5
• 安装成功后脚本回写锁文件（sourceUrl 统一为 GitHub URL、skillFolderHash 为最新 commit SHA），保证下次对比一致、后续 npx skills update 可正常定位源
• 网络极差时脚本自动多级降级；全部通道失败才标记 ❌，不阻塞其他技能

版本对比与缓存

• 每个来源仓库只查一次 commit SHA，同仓库多技能共享结果
• ~/.agents/.skill-remote-cache.json 缓存 commit SHA，默认 TTL 6 小时（--cache-ttl 可调），重复运行几乎秒出
• 对比基准：git ls-remote HEAD → 失败 api.github.com/repos/{owner}/{repo}/commits 兜底
• jsDelivr 不提供 commit SHA，只用于下载，不参与版本对比

依赖预检

脚本内置依赖表（default→brainstorming 等，原 SKILL.md 5.5.1 表已迁入脚本）+ 可选覆盖文件：

<script-path>\scripts\dependencies.local.json

格式：{ "skill-name": ["dep1", "dep2"] } 或 { "skill-name": "dep1,dep2" }。 预检逻辑：未安装的前置依赖自动加入安装队列并优先安装；依赖不在列表文件中时 只在报告里提示 ⚠️（不阻塞）。

异常处理（agent 的兜底职责）

三次失败协议：同一技能连续 3 次安装失败 → 停止自动重试，向用户说明尝试过 的通道与具体错误，请求指导（如检查网络代理、仓库是否私有）。

注意事项

1. Agent 名白名单（大小写敏感）：必须用小写连字符 reasonix / claude-code / opencode / codex。不安装 github-copilot 与 kimi-code-cli。脚本默认 已按白名单配置，--agents 可覆盖。
2. 路径大小写：MarecGents 等路径大小写敏感，务必用 pwd 确认准确路径。
3. jsDelivr 限制：单文件上限 20MB（技能文件通常 <1MB，安全）；官方无打包端点， 只能逐文件，故 jsDelivr 通道定位为兜底而非主通道。
4. GitHub API 限流：未认证 60 次/h（按 IP）。脚本只在 git ls-remote 失败时才 调用 API，且默认有缓存，通常不会触限；如遇 403/429 请设置 GITHUB_TOKEN。
5. codeload 二级限流：频繁下载可能触发 429 + Retry-After，脚本已有重试与退避； 大批量安装建议错峰或使用 --cache-ttl 减少重复请求。
6. 锁文件：~/.agents/.skill-lock.json（v3）。脚本安装后回写 sourceUrl/skillFolderHash，保证与 git commit SHA 对比一致。
7. 超时设计：脚本内所有命令带超时（git ls-remote 15s、npx update 30s、 npx add 60s、下载 60-120s），逐级降级，不会无限卡住；整体建议 agent 侧给 10 分钟运行窗口。
8. 报告：~/.agents/skill-sync-report.json 为机器可读完整报告（含每个技能的 状态、通道、原因），控制台摘要为人读概览；agent 汇报以报告为准。

使用示例

示例 1：完整同步

用户：帮我同步一下技能

node "<skill-path>\scripts\sync-skills.js"

脚本自动：自更新 → 读最新列表 → 对比 → 依赖预检 → 安装/更新 → 报告。 Agent 读 ~/.agents/skill-sync-report.json 汇报：总计 N | 缺失 X | 可更新 Y | 已最新 Z | 失败 F。

示例 2：只想看差异

node "<skill-path>\scripts\sync-skills.js" --compare

示例 3：网络环境差（CDN 优先 + 演练）

node "<skill-path>\scripts\sync-skills.js" --cdn-first --dry-run   # 先看将执行什么
node "<skill-path>\scripts\sync-skills.js" --cdn-first             # 正式执行

示例 4：安装特定技能

node "<skill-path>\scripts\install-skill.js" --name xx-skill --url <origin-url>

示例 5：完全离线/受限网络（npx 不可用）

1. 运行 sync-skills.js --compare 确定缺失技能
2. 逐技能手动安装：install-skill.js 的 jsDelivr/GitHub API 通道会直接写文件 ~/.agents/skills/<name> 并回写锁
3. 若 npx skills 完全不可用，脚本会提示文件已就位、需手动注册 （npx skills experimental_sync -y 或告知用户）