前言¶
在 OpenCode 里用技能，常见做法是把 zip 或目录手工拷进 .opencode/skills/，再改 opencode.json、同步 agents/、commands/ 和 plugins/。包结构不统一时还要自己判断 Flat、Single 还是 Multi，升级时还要比对版本、处理 slug 改名。步骤多、容易漏确认，也容易把配置写错导致 OpenCode 起不来。
下面介绍 SkillHub 上的 Opencode Skill Installer 本地技能安装器（坐标 @user_c9b69df4/opencode-skill-installer，当前版本 3.0.0）。它面向 OpenCode，用 Agent 按流程执行安装、升级、降级、卸载和查询，并在关键步骤等待用户确认后再动手。
这是什么¶
Opencode Skill Installer 是一条遵循通用 SKILL.md 格式的 Agent 技能，分类为 ai-agent，来源为 community，由 SkillHub 发布者 user_c9b69df4 维护；SkillHub 页面标注作者为沐紫衣。标签 requires_api_key=false，不依赖额外 API Key。
一句话定位：在 OpenCode 项目或全局配置下，对本地下载的技能包（zip 或目录）做安装与生命周期管理，支持版本对比、项目级与全局路径选择，并在覆盖、降级、部署配套资源等节点要求用户确认。
核心功能¶
以下能力均来自官方 SKILL.md 与 SkillHub 简介，可按需组合使用。
安装与结构识别¶
- 支持 zip 包 与 目录 两种来源；zip 会先解压到
.opencode/.tmp/再检测结构。 - 识别三种包结构：Flat（根目录有
SKILL.md）、Single（单个子目录含SKILL.md）、Multi（多个子目录各含SKILL.md，可让用户多选安装）。 - 通过多层规则提取技能名（
_meta.json、frontmatter、目录名等），并校验命名是否符合^[a-z0-9]+(-[a-z0-9]+)*$。 - 安装前对外来 zip/目录做风险提示；复制前执行源包完整性校验（
_meta.json与SKILL.md的 version、slug、目录名一致性）。
版本对比与同名处理¶
- 按
SKILL.mdfrontmatter 的name扫描已安装技能，不限于当前 slug。 - 若检测到 slug 迁移（同名但目录名不同），先询问是否清理旧目录。
- 升级/重装/降级时读取双方
_meta.json的version，展示对比表；新版低于已安装时默认 跳过，避免误覆盖；缺 version 时回退为覆盖/跳过选择。
配套资源部署¶
- 将技能复制到 项目
.opencode/skills/<name>/或 全局~/.config/opencode/skills/<name>/（由用户选择，默认 project）。 - 若包内带有
agents/、commands/、plugins/、scripts/，按规则复制到对应 OpenCode 目录；冲突时询问是否覆盖。 - 更新
opencode.json/opencode.jsonc时清理陈旧配置；禁止向opencode.json写入agents字段（由插件从.opencode/agents/*.md发现）。 - 可选在
.opencode/下根据技能scripts/package.json安装 npm 依赖。
查询、验证与卸载¶
- 查询：批量扫描 zip 或预览单个包的结构与 frontmatter。
- 验证：提供
verify-integrity（复制前）与verify-install（复制后）CLI，输出 JSON 检查结果。 - 卸载：检测项目/全局安装位置，确认后删除目录并清理配置；可选删除同名 agent、命令、插件。无法卸载安装器自身，需用户手动删除。
机械操作优先通过 scripts/install.mjs 完成，Agent 负责交互与决策。
安装与启用¶
通过 SkillHub 安装本技能¶
若尚未安装 SkillHub CLI，可先检查版本：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档 执行完整安装（示例）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
把技能装到 当前 Agent 能识别的 skills 目录 时，必须使用 --dir，否则默认落在 ./skills/ 且可能不被识别。OpenCode 侧运行时技能目录为项目 .opencode/skills/ 或全局 ~/.config/opencode/skills/；若你是通过 Cursor 等客户端加载 SkillHub 技能，需指向该客户端的 skills 路径（文档示例：Cursor 为 ~/.cursor/skills/）。
安装本安装器可用搜索到的坐标之一：
skillhub search opencode-skill-installer
skillhub install opencode-skill-installer --namespace user_c9b69df4 --dir <你的 Agent skills 目录>
或使用完整坐标：
skillhub install @user_c9b69df4/opencode-skill-installer --dir <你的 Agent skills 目录>
也可将下面提示词交给 AI，让其按 SkillHub 文档完成安装：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_c9b69df4/opencode-skill-installer`。
在 OpenCode 中生效¶
本技能的执行逻辑针对 OpenCode 目录布局（.opencode/skills/、opencode.json 等）。安装到 Agent 后，在 OpenCode 项目里通过自然语言触发（见下文「典型用法」）。官方流程要求在安装完成后 重启 opencode 会话 使新技能生效。
自举更新安装器自身时，CLI 可对目标项目使用 --target <项目根路径>，避免当前工作目录与目标项目不一致。
典型用法¶
触发方式¶
当用户要求 安装、查询或卸载 技能时，Agent 应加载本技能。安装完成后，它会从已安装技能的 ## 何时使用 和 commands/ 生成简短指引，并提示重启 OpenCode。
安装外来技能包（概念流程）¶
- 用户提供 zip 路径或本地目录，并说明期望 project 或 global。
- Agent 展示安装前置确认（源路径、来源类型、目标位置、操作类型），用户确认后继续。
- zip 模式会调用检测脚本（示例 CLI）：
node scripts/install.mjs test-skill-source --path <zip或目录路径>
- 用户确认摘要、安装位置；若已存在同名技能则进入版本对比或 slug 迁移询问。
- 复制前完整性校验、复制到目标路径、更新配置、按需部署 agents/commands/plugins。
- 询问是否清理临时解压目录或源 zip；若有
scripts/package.json则询问是否安装依赖。 - 安装后验证：
node scripts/install.mjs verify-install --name <skillName> --scope project
# 或 --scope global
上述 node scripts/install.mjs 命令路径相对于 已安装的 opencode-skill-installer 技能目录 下的 scripts/install.mjs。
维护配置残留¶
slug 重命名或手动删目录后，可清理 opencode.json 中指向已不存在技能的 permissions 条目：
node scripts/install.mjs clean-stale --scope project
node scripts/install.mjs clean-stale --scope global
适用场景与注意¶
适合谁
- 经常在 OpenCode 里从 zip、目录或多技能包安装社区技能，希望统一走确认流程的开发者。
- 需要项目级与全局级路径切换、版本升级/降级对比、以及卸载时连带清理 agent/command/plugin 的团队。
限制与注意
- 环境绑定 OpenCode：路径与配置均围绕
.opencode/与~/.config/opencode/，不是通用 Cursor Rules 或 Claude Code 插件安装器。 - 确认点多：zip 安装流程中多个步骤必须用户确认，不适合完全无人值守的批量脚本（设计如此，用于降低误覆盖风险）。
- 无法自卸载：卸载
opencode-skill-installer需手动删目录并改配置。 - Windows 长路径：解压到
.opencode/.tmp/时，超过 260 字符的路径可能导致失败，需缩短路径或使用\\?\前缀（见官方「常见陷阱」表）。 - 外来包安全：安装外部 zip/目录前会提示脚本将以当前会话权限执行，需自行判断来源是否可信；可先安装
opencode-creator做审查（官方建议）。
SkillHub 页面数据（抓取时）：评分 100000，下载 728 次，分类 ai-agent。
结尾¶
Opencode Skill Installer 把 OpenCode 技能包的检测、命名、版本决策、目录部署和配置清理收成一条可复现的 Agent 流程，并在升级、降级和覆盖前留出确认点。若你主要从 SkillHub 获取该技能，可从官方页面入手：
- SkillHub：https://www.skillhub.cn/skills/user_c9b69df4/opencode-skill-installer
- 官方地址：https://api.skillhub.cn/user_c9b69df4/opencode-skill-installer
问题反馈可指向技能文档中的 opencode-skill-suite 仓库提交 Issue 或 PR。
