> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 技能仓库从注册到使用

本教程说明管理员如何注册技能仓库、同步仓库索引，并让用户从技能市场安装技能到工作区使用。

## 使用场景

技能仓库用于把外部或组织内部维护的技能目录接入 XpertAI。仓库注册完成后，系统会扫描仓库中的 `SKILL.md`，生成可搜索、可安装的技能索引。用户随后可以在技能市场中选择技能，并安装或更新到自己的工作区。

这条链路适合以下场景：

* 将 GitHub、ModelScope、ClawHub 等来源中的技能接入组织。
* 将工作区共享技能发布到组织内部技能市场。
* 给多个工作区复用同一批技能，而不是逐个上传 ZIP 包。

## 整体流程

1. 管理员进入租户技能管理页。
2. 注册一个技能仓库，并填写仓库来源、仓库地址、路径、分支和凭据。
3. 保存配置后同步仓库索引。
4. 用户在技能市场中选择对应仓库，安装或更新技能。
5. 用户回到工作区技能页查看已安装技能，并在工作区或智能体中使用。

## 第一步：进入租户技能管理

进入 **设置 / 租户 / 技能**。该页面用于管理当前组织可用的技能仓库，包括系统托管的“工作区共享技能”仓库，以及手动注册的外部仓库。

页面中的“仓库管理”区域展示当前组织已经接入的技能仓库。右侧的“注册技能仓库”用于新增外部仓库。

## 第二步：注册技能仓库

点击“注册技能仓库”，选择来源策略并填写仓库配置。

系统默认提供 ClawHub 和 GitHub 两种仓库来源。如果要使用 GitCode、ModelScope 或其他来源，需要先安装对应的技能仓库来源插件。插件安装并启用后，对应来源才会出现在“来源策略”下拉框中。

常见字段含义如下：

| 字段     | 说明                                                             |
| ------ | -------------------------------------------------------------- |
| 来源策略   | 决定由哪个技能来源提供方处理仓库。默认可选 ClawHub 和 GitHub；GitCode 等其他来源需要先安装对应插件。 |
| 名称     | 仓库在管理页和技能市场中展示的名称。                                             |
| 仓库地址   | 外部技能仓库地址。                                                      |
| 技能路径   | 仓库内技能所在的子目录，可选；不填时从仓库根目录扫描。                                    |
| 分支     | 使用的分支或标签，可选；不填时使用来源策略的默认分支。                                    |
| 个人访问令牌 | 访问私有仓库或提高 API 限额时使用，可选。                                        |

保存后，仓库会出现在仓库列表中。需要修改配置时，点击仓库卡片右侧的设置按钮。

## 第三步：同步仓库索引

仓库注册只保存连接配置。要让技能出现在市场中，还需要同步仓库索引。

在仓库详情中可以执行索引刷新。增量同步会新增或更新当前扫描到的技能；全量同步还会清理仓库中已经不存在的旧索引。

同步完成后，系统会为仓库中的每个技能目录生成索引。技能目录需要包含 `SKILL.md`，系统会从中读取名称、描述、版本、标签等信息。

## 第四步：在技能市场安装技能

打开技能市场，选择刚注册并同步完成的技能仓库。市场会展示该仓库已经索引的技能，点击“安装或更新”即可安装到工作区。

安装时系统会把对应技能包拉取到目标工作区。如果技能已经安装，系统会复用已有安装记录，并在有新版本时执行更新。

## 第五步：在工作区查看和使用技能

安装完成后，进入工作区的“技能”页，可以查看已安装技能、文件树和 `SKILL.md` 内容。

工作区技能可以直接被当前工作区内的智能体使用。后续如果仓库技能有更新，可以回到技能市场再次执行“安装或更新”，或在工作区技能页查看文件内容和安装状态。

## 常见问题

### 注册后市场里看不到技能

先确认仓库已经同步索引。只有保存仓库配置不会生成市场卡片，必须执行索引同步。

### 同步成功但技能数量不对

检查仓库路径是否指向正确目录。系统按技能目录中的 `SKILL.md` 生成索引，如果技能文件不在配置路径下，就不会被扫描到。

### 私有仓库同步失败

检查个人访问令牌是否具备访问仓库的权限，并确认令牌没有过期。令牌应填写在仓库凭据中，不应写入技能文件。

### 更新仓库配置后为什么仍然显示旧技能

保存配置后需要重新同步索引。若需要清理已经不存在的技能索引，执行全量同步。