| # Skill 展示协议（skill-ui.json） |
|
|
| `skill-ui.json` 是可选的用户端展示清单，放在 Skill 根目录（与 `SKILL.md` 同级）。它只描述展示、输入和输出，不改变 `SKILL.md` 的 Agent 指令。 |
|
|
| 没有此文件时，系统会按以下顺序自动发现展示信息：README/USAGE/QUICKSTART、本地 `assets/`、`examples/`、`demo/`、`skill-workflow.json`、`SKILL.md`。打开详情不会运行 Skill、调用模型或扣除积分。 |
|
|
| ```json |
| { |
| "version": "1.1.0", |
| "author": "Example Studio", |
| "source": { |
| "label": "GitHub 开源", |
| "url": "https://github.com/example/studio-skill", |
| "author": "Example Studio", |
| "version": "1.1.0", |
| "openSource": true |
| }, |
| "display": { |
| "title": "商品海报设计", |
| "description": "根据商品参考图生成电商海报。", |
| "category": "视觉创作", |
| "tags": ["海报", "电商"], |
| "cover": "assets/cover.webp" |
| }, |
| "capabilities": ["image", "html", "script"], |
| "assets": [ |
| { "path": "examples/result-1.webp", "title": "竖版案例", "role": "gallery" }, |
| { "path": "demo/index.html", "title": "互动演示", "role": "demo" } |
| ], |
| "examples": [ |
| { |
| "id": "poster", |
| "title": "生成一张商品海报", |
| "description": "保留商品外观并重新设计背景。", |
| "prompt": "$studio-skill 把上传商品图制作成 3:4 高级电商海报。", |
| "attachmentHint": "请上传一张清晰商品图" |
| } |
| ], |
| "inputs": [ |
| { "id": "request", "label": "设计要求", "type": "text", "required": true }, |
| { "id": "image", "label": "商品参考图", "type": "image", "required": true } |
| ], |
| "outputs": [ |
| { "id": "poster", "label": "海报图片", "type": "image" }, |
| { "id": "gallery", "label": "互动展示页", "type": "html" } |
| ] |
| } |
| ``` |
|
|
| 支持的案例素材包括 PNG、JPEG、WebP、GIF、SVG、PDF、HTML、MP4、WebM、MP3 和 WAV。单文件上限 8MB；路径必须位于 Skill 目录内。HTML/SVG 默认在禁止脚本的沙箱中预览，HTML 交互只能由用户手动启用。 |
|
|
| 来源和作者的自动发现顺序为：`skill-ui.json` → `SKILL.md` frontmatter → `package.json` → `.install.json`。通过 GitHub 安装时，即使 Skill 没有声明作者，也会把仓库 owner 作为作者回退值并显示开源地址。 |
|
|
| `skill-workflow.json` 中的 `summary`、`tasks` 和 `postprocess` 会被渲染成用户可读步骤。配置错误只会产生后台展示诊断，Skill 仍可按 `SKILL.md` 基础方式调用。 |
|
|
| ## 后台展示覆盖 |
|
|
| 管理员可以在 Skills 管理页编辑标题、简介、分类、标签、封面、案例和示例提示词。修改内容保存在 Skill 目录的 `.presentation-overrides.json`，优先级高于自动发现结果，但不会改写第三方 Skill 自带的 `SKILL.md`、README 或 `skill-ui.json`。管理员上传的封面和案例保存在 `.presentation-assets/`，仍遵循 8MB 单文件限制和图片类型白名单。 |
|
|
| “AI 生成示例”会读取 Skill 协议及 README/USAGE/QUICKSTART 等本地文档，生成多条可继续编辑的示例；只有管理员主动点击时才调用模型，打开详情和切换案例不会触发模型或扣除积分。生成结果在管理员保存后成为稳定展示数据。 |
|
|
| 输入要求以 `skill-ui.json` 或后台覆盖中的 `inputs[].required` 为最高优先级。未显式配置时，只有文档明确要求“必须/需要上传图片”才把参考图片推断为必需；仅支持图片、可使用参考图或能够编辑图片时，参考图片默认是可选项。 |
|
|
| ## 用户收藏 |
|
|
| 收藏按登录用户隔离保存。用户可在 Skill 选择器的“我的收藏”中快速筛选，隐藏、删除或不存在的 Skill 不会继续出现在收藏列表中。收藏只影响用户端导航，不修改 Skill 文件，也不影响其调用权限。 |
|
|
| ## 更新与跨部署迁移 |
|
|
| 安装记录写在 Skill 目录的 `.install.json`，其中 `source` 是安装时使用的地址（GitHub 页面地址或 `upload:文件名.zip`）。Skills 管理页的「更新」按钮据此重新拉取并覆盖安装；由本地上传安装、或来源不是 http(s) 地址的 Skill 无法自动更新，需要重新上传新版 ZIP。 |
|
|
| 覆盖安装只替换包内文件。管理员在本地做出的决定会跨更新保留：脚本权限（`.permissions.json`）、展示覆盖（`.presentation-overrides.json`）、上传的展示素材（`.presentation-assets/`）和显示状态（`.visibility.json`）。覆盖前旧目录会整份备份到 `data/skills/.backups/<skill-id>/`，每个 Skill 保留最近 3 份，需要回滚时把对应快照拷回即可。 |
|
|
| 「导出全部」或单个 Skill 的导出按钮会生成一个 ZIP，内含每个 Skill 的完整目录（含上述管理文件）和描述本次导出的 `manifest.json`。缓存文件（`.user-guide-cache.json`）与 `__pycache__` 不会被打包。该 ZIP 可在另一套部署通过「导入 ZIP」直接安装，展示设置、脚本权限和展示素材一并还原——这是部署之间迁移 Skill 的推荐方式，不需要逐个重新配置。导入走管理员专用通道，归档上限高于普通仓库安装。 |
|
|
