Opencode Skill Installer 本地技能安装器

何时使用

用户要求安装/查询/卸载技能时触发。

核心规则

0. 命令快速参照

所有脚本操作都有专用 CLI 入口，不要读 install.mjs 源码找命令。完整列表在 references/quickref.md，关键命令（以下假设 CWD 为目标项目根目录，所有路径操作基于 CWD；自举安装时用 --target <path> 覆盖目标项目根目录）：

node scripts/install.mjs copy-skill --source <p> --name <n> --scope <s> --target <project>
node scripts/install.mjs update-config --name <n> --scope <s> --target <project>
node scripts/install.mjs deploy-commands --source <p> --scope <s> [--force] --target <project>
node scripts/install.mjs deploy-plugins --source <p> [--force] --target <project>
node scripts/install.mjs clean-stale --scope <s> --target <project>

0a. 外来包风险提示

安装 zip 包或外来目录前，向用户提示：「此技能来自外部，安装后其脚本将以当前会话权限执行。请确认你信任该来源。」如需审查，可先安装 opencode-creator 技能，再要求 AI 审查后安装。

1. 检测结构

三种结构：Flat（SKILL.md 在根）、Single（一个子目录含 SKILL.md）、Multi（多个子目录各含 SKILL.md）。同时检测 agents/、commands/ 和 plugins/。
优先调用 testSkillSource(path) 一次性获取所有信息。

2. 技能名提取与修正

5 层回退：_meta.json slug → 解压/源目录名（裁剪版本/hash 后缀）→ zip 文件名 / 源目录父目录名 → frontmatter name: → H1 标题（# 标题）。提取后校验，必须符合 ^[a-z0-9]+(-[a-z0-9]+)*$。大写转小写，空格替换为连字符。若 SKILL.md 有 frontmatter 则 name 与最终目录名不一致时自动更新；若无 frontmatter 则不修改文件。
优先调用 getSkillName(sourceDir, zipName, frontmatterName) 提取名称。

3. 安装

安装流程分两种模式，根据前置检查结果选择。

同名检测（所有安装的前置）

本步骤在步骤 ② 读取 frontmatter 后立即执行，无论新装还是升级都要跑：

1. 读取源包 SKILL.md frontmatter name 字段
2. 扫描 .opencode/skills/ 下所有子目录的 SKILL.md frontmatter，查找 name 匹配
3. 按结果分路：
   - 未匹配 → 新安装，进入步骤 ③
   - 匹配且目录名 = 源包 slug → 同目录，进入版本对比（§版本对比）
   - 匹配但目录名 ≠ 源包 slug → slug 已变更，先询问清理旧目录再进入版本对比

slug 迁移询问：

📌 slug 已变更：self-improve → opencode-self-improve
是否清理旧目录 .opencode/skills/self-improve/?
[Yes] 先清理旧目录，再安装新版
[No]  保留旧目录，仅安装新版

• 用户选 Yes → 先删除旧目录并清理 opencode.json 中的旧 key，再进入版本对比
• 用户选 No → 保留旧目录，直接进入版本对比

版本对比（仅升级/重装/降级）

匹配到已安装技能后执行：

1. 读取已安装版 _meta.json 的 version 字段
2. 读取新版（临时目录/源目录）_meta.json 的 version 字段
3. 展示版本对比：已安装 v1.0.0 → 新版 v2.0.0
4. 根据对比结果提供决策选项：

无 _meta.json 或 version 字段时回退为简单「覆盖 / 跳过」选择。

优先调用 compareSkillVersion(v1, v2) 进行版本对比。

3a. zip 模式

3b. 目录模式

与 zip 模式基本相同，区别：

• 跳过步骤 ①（无需解压）
• 检测直接在源目录上进行
• 步骤 ⑩ 源清理：目录模式下清理整条源目录路径（非 zip 包）；非源码真相源的临时源才清理，永久源码跳过

3c. 多技能包

解压后或源目录下有多个子目录各含 SKILL.md（Multi 结构），则：

1. 列出所有技能（序号 + 名称 + 版本）
2. 让用户选择安装哪些（可多选）
3. 逐个按 §3a/§3b 流程处理，每个技能独立做覆盖检测

4. 配套 Agent、命令与脚本

安装目录/解压目录下有 agents/ 则复制 .md 到 .opencode/agents/。已存在时询问覆盖。zip 模式在步骤⑦执行，目录模式在步骤⑥后执行。

⚠️ 严禁向 opencode.json 写入 agents 字段。 代理通过 .opencode/agents/*.md 文件由插件系统自动发现，无需（且在某些版本中不得）在 opencode.json 中注册。向 JSON 写入 agents 条目会导致配置文件校验失败，opencode 无法启动。

⚠️ 技能权限默认已允许。 默认 agent 规则 *:*:allow 覆盖所有技能，无需显式写入 allow。仅在需要禁用某技能时写入 permissions 数组中的 deny 条目。skills 字段为路径数组（发现源），不是权限表。

安装目录/解压目录下有 scripts/ 则随技能目录整体复制（copySkillToTarget 递归复制全部内容），无需单独部署。路径引用使用 .opencode/skills/<name>/scripts/<file>。

安装目录/解压目录下有 commands/ 则复制 .md 到对应命令目录：
- 项目安装 → .opencode/commands/<文件名>.md
- 全局安装 → ~/.config/opencode/commands/<文件名>.md

已存在时询问覆盖。zip 模式在步骤⑧执行，目录模式在步骤⑦后执行。

更新时命令同步规则：升级/重装时（版本检测结果为升级或重装），在执行命令复制前先删除目标命令目录中所有与新版 commands/ 同名的 .md 文件，确保旧版残留被清理，再复制新版命令。若新版无 commands/ 目录，跳过命令部署，保留既有命令。

安装完成摘要：安装验证通过后，AI 从已安装技能的 SKILL.md 读取 ## 何时使用 和 commands/ 目录，生成简短的使用指引：

✅ <skill-name> v<version> 安装完成

如何触发：<从 何时使用 提取 2-3 条核心场景>
主要命令：<从 commands/ 提取命令列表，无则写「无（自动触发）」>
💡 重启 opencode 使新技能生效

5. 查询

批量扫描 *.zip 或预览单个 zip。检测结构、读取 frontmatter、展示结果后询问安装。参考 setup.md 和 scripts/install.mjs 中的操作函数。

6. 卸载

注意： 无法卸载自身。若用户要求卸载 opencode-skill-installer，提示手动删除。

7. 验证

两个验证步骤均有专用 CLI 入口，避免内联 JS 的 PowerShell 转义问题：

# §7a 源包完整性验证
node scripts/install.mjs verify-integrity --path <sourceDir>

# §7b 安装后验证
node scripts/install.mjs verify-install --name <skillName> --scope <project|global>

输出 JSON { pass, checks: [{ name, pass, expected?, actual }] }。pass: false 表示检查未通过。

7a. 源包完整性验证（复制前执行）

在复制技能之前（步骤⑤前），验证源包内部一致性。发现不一致时拦截安装，列出差异让用户手动修复源包后再试：

输出示例：

{ "pass": false, "checks": [
  { "name": "version 一致", "pass": false, "actual": "❌ _meta.json v2.9.0 vs SKILL.md v2.10.0" },
  { "name": "目录名匹配 slug", "pass": false, "actual": "❌ 目录 \"my-old-name\" vs slug \"my-new-name\"" }
]}

7b. 安装后验证（复制后执行）

7c. 安装失败分级恢复

安装过程中某一步骤失败时，按以下分级路径处理：

Windows 特有问题： 压缩包内长路径（超过 260 字符）可能导致解压到 .opencode/.tmp/ 失败，此时需加 \\?\ 前缀或缩短源 zip 路径。

8. 自身安装/更新

安装或更新 opencode-skill-installer 自身时：

卸载自身： 不受支持。用户需手动删除目录并清理配置。

前置检查

每次安装前，先依次完成以下 7 项检查，根据结果选择后续分支：

安装前置确认

在执行前置检查之前，先展示安装确认行，让用户在开始前纠正理解偏差：

📌 安装前置确认：
- 源路径：[xxx.zip]
- 来源类型：[zip / 目录]
- 目标位置：[project / global]
- 操作类型：[安装 / 升级 / 降级 / 重装]
正确吗？

决策树：

源路径
├─ zip 文件 ──→ 解压到 .opencode/.tmp/ ──→ 检测结构 ──→ 安装（§3a）
└─ 目录    ──→ 直接检测结构 ──→ 安装（§3b，跳过解压）

数据存储

.opencode/skills/<name>/（项目）、~/.config/opencode/skills/<name>/（全局）、.opencode/agents/（agent）、.opencode/commands/（命令，项目级）、~/.config/opencode/commands/（命令，全局级）、.opencode/.tmp/（临时解压）。

脚本辅助

优先调用 scripts/install.mjs 中的函数完成机械操作（检测、命名提取、版本对比、复制、配置更新等），避免手动造命令。加载方式：

import { testSkillSource, getSkillName } from './scripts/install.mjs';

或通过 CLI 调用：

node scripts/install.mjs test-skill-source --path <path>

§7d. Config 条目清理

安装/验证后建议执行 config 清理，移除 permissions 数组中指向已不存在技能目录的残留条目：

node scripts/install.mjs clean-stale --scope project     # 项目级
node scripts/install.mjs clean-stale --scope global      # 全局级

流程：
1. 读取 opencode.json[c] 的 permissions 数组
2. 调用 getInstalledSkills(scope) 获取当前已安装的目录列表
3. 过滤 permissions 中 action === 'skill' 且 resource 不在已安装列表内的条目
4. 若有移除，写回文件并报告被清理的条目名

适用于：slug 重命名后旧名残留、手动删目录后配置未清理。

函数列表详见 references/quickref.md。AI 负责用户交互和决策，脚本执行具体操作。

权限/配置

常见陷阱

相关技能

• opencode-creator — 创建和审查技能设计
• opencode-skill-packager — 打包技能为 zip

反馈

在 opencode-skill-suite 提交 Issue 或 PR。