SkillHub 发布 Skill 操作说明

本文档用于说明如何将已经制作完成的 Pi Skill 打包为 ZIP 文件，并发布到 SkillHub 平台，供其他用户下载、安装和使用。

---

1. 发布前准备（可跳过，使用Pi直接检查）

在发布 Skill 之前，需要先确认 Skill 文件夹已经整理完成。

一个标准 Skill 通常包含：

skill-name
├── SKILL.md
├── docs
│   └── 相关说明文档.md
├── templates
│   └── 模板文件.md
└── scripts
  └── 可选脚本文件

其中必须包含：

文件/目录	是否必需	说明
SKILL.md	必需	Skill 主说明文件
docs	可选	存放知识库、操作手册、FAQ 等资料
templates	可选	存放输出模板
scripts	可选	存放辅助脚本

发布前重点检查：

1. SKILL.md 是否存在。

2. SKILL.md 顶部是否包含 name 和 description。

3. Skill 文件夹名称是否与 name 保持一致。

4. 是否删除了无关临时文件。

5. 是否确认没有包含敏感信息，例如数据库密码、服务器私钥、Token 等。

6. 是否已在本地 Pi 中测试可以正常识别和使用。

---

2. SKILL.md 基础要求（可跳过，使用Pi直接检查）

SKILL.md 文件顶部需要包含 frontmatter，例如：

---
name: my-demo-skill
description: 当用户需要整理项目资料、生成说明文档、汇总文件内容或按照固定流程输出结果时使用本技能。
---
​
# My Demo Skill
​
## 使用场景
​
当用户提出资料整理、文档生成、流程说明、表格汇总等需求时，使用本技能。
​
## 操作规则
​
1. 先读取当前工作区相关文件。
2. 根据用户需求整理内容。
3. 输出结构清晰的 Markdown 文档。
4. 如果信息不足，先向用户确认。

字段说明：

字段	说明
name	Skill 名称，建议与文件夹名称一致
description	Skill 描述，用于告诉 Pi 什么时候使用该技能

description 必须写清楚适用场景，否则用户安装后 Pi 可能无法准确识别或调用该 Skill。

---

3. 打包 Skill，可以直接使唤Pi打包Skill，并打包成zip

发布前需要将整个 Skill 文件夹压缩为 ZIP 文件。

3.1 正确打包方式

假设 Skill 文件夹名称为：

my-demo-skill

压缩后应得到：

my-demo-skill.zip

ZIP 内部结构应为：

my-demo-skill.zip
└── my-demo-skill
  ├── SKILL.md
  ├── docs
  └── templates

3.2 不推荐的打包方式

不要只压缩 SKILL.md 文件：

my-demo-skill.zip
└── SKILL.md

不推荐原因：缺少外层 Skill 文件夹，用户解压后容易放错目录，也不利于多个 Skill 管理。

---

4. 登录 SkillHub

打开浏览器，访问发布地址：

https://skillhub.singzer.cn/

进入首页后，可以看到 SkillHub 管理页面。

首页界面如下：

点击右上角登录 登录成功后进入管理首页。

---

5. 进入发布页面

在 SkillHub 首页或管理页面中，找到发布入口，进入 Skill 发布页面。

发布页面如下：

发布 Skill 的核心操作是：

将 Skill 打包成 ZIP 文件，然后上传发布。

---

6. 上传并发布 Skill

在发布页面中，按照页面提示填写或选择相关内容。

一般需要操作以下内容：

1. 点击上传按钮。

2. 选择本地已经压缩好的 .zip 文件。

3. 确认 Skill 名称、描述或版本信息。

4. 点击确认发布。

5. 等待管理员审核完成即可。

---

7. 发布成功后的检查

可在“我的技能”页面中查看已发布的技能 打开PI客户端，点击“刷新SkillHub”按钮，能够看到新发布的Skill，点击安装，安装成功后，就可以正常测试使用。

---

7.1 上传失败怎么办？

可以检查：

1. 网络是否正常。

2. ZIP 文件是否过大。

3. ZIP 文件是否损坏。

4. 文件名是否包含特殊字符。

5. 是否已经登录过期，重新登录后再试。

7.2 发布后用户看不到 Skill 怎么办？

可能原因：

1. 用户没有下载最新版。

2. 用户解压后目录结构不正确。

3. 用户没有把 Skill 放到正确目录。

4. 用户没有重启 Pi。

5. SKILL.md 中 description 为空或格式错误。

7.3 Skill 无法正常触发怎么办？

检查 description 是否写得过于简单。

建议将：

description: 文档技能

改为：

description: 当用户需要根据项目资料生成操作说明、安装文档、使用手册、验收报告或维护记录时使用本技能。

7.4 更新 Skill 应该怎么发布？

建议：

1. 修改 Skill 文件。

2. 更新版本号。

3. 重新压缩 ZIP。

4. 在 SkillHub 上传新版本。

5. 在更新说明中写清楚修改内容。

---

8. 推荐发布说明模板

每次发布时，可以附带以下说明：

# my-demo-skill 发布说明
​
## 版本
​
v1.0.0
​
## 功能简介
​
本 Skill 用于整理项目资料，并根据固定模板生成 Markdown 操作说明文档。
​
## 安装方法
​
1. 下载 `my-demo-skill.zip`。
2. 解压得到 `my-demo-skill` 文件夹。
3. 将文件夹复制到：
​
  C:\Users\admin\.pi\agent\skills
​
4. 重启 Pi。
5. 在输入框输入 `/`，选择 `my-demo-skill` 使用。
​
## 更新说明
​
- 首次发布。
​
## 注意事项
​
- 请勿删除 Skill 文件夹内的 `docs` 和 `templates` 目录。
- 请确认 Pi 已打开正确工作区。

---

9. 快速流程总结

1. 准备 Skill 文件夹。

2. 确认 SKILL.md 内容完整。

3. 将整个 Skill 文件夹压缩为 ZIP。

4. 打开 SkillHub：https://skillhub.singzer.cn/。

5. 使用账号 admin 登录。

6. 进入发布页面。

7. 上传 ZIP 文件。

8. 填写名称、描述、版本和更新说明。

9. 点击发布。

10. 发布成功后下载测试。

11. 将下载和安装说明发给用户。

完成以上步骤后，Skill 即可通过 SkillHub 发布并分发给用户使用。