opencode-skill-installer

何时使用

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

核心规则

1. 检测结构

三种结构：Flat（SKILL.md 在根）、Single（一个子目录含 SKILL.md）、Multi（多个子目录各含 SKILL.md）。同时检测 agents/ 和 commands/。

优先调用 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. 安装

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

版本检测（所有模式的公共前置）

第 ⑦ 步覆盖检测时，若目标已存在同名技能，自动执行版本对比：

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

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

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

3a. zip 模式

确认点汇总： 步骤 ②③④⑧⑨⑩ 共 6 次用户确认，不可跳过。

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 无法启动。

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

安装目录/解压目录下有 commands/ 则复制 .md 到对应命令目录：

• 项目安装 → .opencode/commands/<文件名>.md
• 全局安装 → ~/.config/opencode/commands/<文件名>.md

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

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

安装完成提示：若技能包含 commands/ 且安装成功，提示用户该技能提供配套命令，建议使用对应信号词触发。对于 self-improve 等依赖命令注入规则到 AGENTS.md 的技能，建议用户运行配套命令以完成完整安装。

5. 查询

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

6. 卸载

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

7. 验证

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

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

# §7b 安装后验证
node .opencode/skills/opencode-skill-installer/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. 安装后验证（复制后执行）

若发现配置为 "deny"，手动改为 "allow"。

7c. 安装失败分级恢复

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

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

8. 自身安装/更新

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

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

前置检查

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

安装前置确认

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

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

决策树：

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

数据存储

.opencode/skills//（项目）、~/.config/opencode/skills//（全局）、.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>

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

权限/配置

常见陷阱

相关技能

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

反馈

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