[← 返回 README](../README.zh-CN.md)

# Skill Hub 使用指南

Skill Hub 是 ClawManager 的可复用技能中心，面向 OpenClaw、Hermes、OpenCode 和 DeepSeek Harness 工作空间。它把技能从“某个实例里的文件”变成可扫描、可版本化、可发布、可再次安装的资产。

## 入口与视图

- **浏览**：搜索已发布的技能，按标签筛选，查看版本、作者、扫描和风险信息，并安装到兼容实例。
- **我的 Skill**：管理自己上传或从实例收录的技能，包括新版本、标签、发布、下架、下载和删除。
- **管理**：管理员查看平台技能并执行有权限的治理操作。界面中可用的按钮仍会受所有权和当前版本状态限制。
- **实例内技能管理**：在实例详情中查看已安装技能、Hub 安装记录和工作区发现的技能。

## 从 ZIP 上传到发布

1. 在 **我的 Skill** 上传一个或多个 ZIP。压缩包应包含 `SKILL.md` 和技能需要的文件。
2. ClawManager 保存版本并发起安全扫描。Windows/中文 ZIP 文件名会按兼容编码处理。
3. 查看扫描状态、风险级别和报告。扫描失败时文件不会消失，用户可以修正后上传新版本。
4. 完成扫描并满足当前发布条件后，设置公开标签并发布到 Hub。
5. 已发布版本会出现在“浏览”中；下架不会删除所有者的历史版本。

扫描完成不等于“没有风险”。发布或安装是否可用，还会受版本文件、所有权、Runtime 兼容和平台策略影响。

## 安装到实例

1. 打开技能详情并选择安装。
2. 选择一个或多个兼容实例。
3. 确认版本后提交。
4. 打开实例详情，在 **技能管理** 中刷新并核对实际版本。

OpenClaw、Hermes、OpenCode 和 DeepSeek Harness 均属于支持范围，但不同 Runtime 的落盘目录和生效方式不同。DeepSeek Harness Lite 使用工作空间下的 `home/.dsh/skills`，Pro 使用 `.dsh/skills`；创建完成后可从 Skill Hub 或实例详情安装。OpenCode 在创建页暂不一定显示技能预选，非 HostPath 的 OpenCode Pro 环境还依赖 Runtime Agent 的技能命令支持。若界面显示安装未完成，请管理员核对当前 Runtime 镜像能力。

## 从实例收录技能

实例技能面板会发现工作区中的技能。发现项不会自动成为“我的 Skill”：

1. 先检查技能内容和来源。
2. 选择“收录到 Skill 库”。
3. 系统打包并创建受当前用户拥有的技能版本。
4. 扫描完成后再决定是否发布。

如果实例内文件发生变化，界面会显示漂移状态。用户可按产品提供的操作恢复已安装版本，或把当前内容收录为新版本，避免静默覆盖历史包。

## 版本、删除与卸载

- 上传不同内容会生成新版本，不覆盖旧版本。
- 从 Hub 下架只影响公开发现，不等于删除。
- 从实例卸载会先移除工作区内容，再更新安装记录；失败时应以实例文件和操作结果为准复核。
- 删除技能前，先确认是否仍有实例依赖该版本。

## 当前使用边界

- `SKILL.md` 已包含 YAML frontmatter 时，平台不会替用户重写其中字段；上传前请自行确认 `name` 与 `description`。
- 能力标签只用于描述和检索，不会自动为 Agent 安装技能。
- 风险等级是决策依据；不同入口可能根据当前前后端版本显示不同的可安装范围。
- 管理员后端权限与管理页实际暴露的按钮并不完全相同，批量治理前应先核对界面权限。

## 常见问题

| 情况 | 建议 |
|---|---|
| 上传后扫描失败 | 查看错误，修正 ZIP 后上传新版本，不要把失败状态当成已审核。 |
| 发布按钮不可用 | 检查扫描状态、当前版本文件、所有权和风险/平台策略。 |
| 安装列表里没有目标实例 | 确认实例属于当前用户、Runtime 受支持且实例状态允许操作。 |
| 安装成功但 Agent 未看到技能 | 刷新实例技能面板，核对落盘版本，并在需要时重启/重新加载 Runtime。 |
| 中文文件名异常 | 使用 UTF-8 ZIP；平台也兼容常见 Windows 中文编码，但仍建议上传前检查压缩包。 |

## 相关文档

- [资源管理指南](./resource-management_cn.md)
- [安全防护平台指南](./security-platform_cn.md)
- [用户指南](./use_guide_cn.md)
