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、调用模型或扣除积分。
{
"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 的推荐方式，不需要逐个重新配置。导入走管理员专用通道，归档上限高于普通仓库安装。