Skill 包规范与安全
最近更新:2026/11/15
这篇说明 yunyoo 官方 Skill 的包长什么样、发布前后靠什么保证可信,给想了解细节的人参考。目前只有官方 Skill,暂不接受第三方投稿;以后开放时会另行说明流程。怎样安装和使用见 Skill。
包里有什么
包是一个 ZIP,里面只有一个与 Skill 同名的顶层目录:
| 路径 | 内容 |
|---|---|
SKILL.md | 必有。开头是一小段 frontmatter(名称与用途描述),后面是写给 AI 助手的正文 |
yunyoo.skill.json | 必有。清单:版本、发布者、需要的权限与工具等 |
LICENSE | 必有 |
references/ | 参考资料,正文按需引用 |
assets/ | 模板与图片 |
scripts/ | 脚本,要逐个登记在清单里。首批官方 Skill 不带脚本 |
命名规则
- 名称以
yunyoo-开头,只用小写字母、数字与连字符,例如yunyoo-app-smoke。 - 目录名、
SKILL.md里的name与清单里的name三者相同。 - 版本号是三段式,例如
1.0.0。同一个版本号的内容一经登记就不再改变,要改就升版本号。 SKILL.md的description用英文、第三人称写,说明它做什么、什么时候该用,并附中文触发词,不超过 1024 个字符。AI 助手靠这段话决定要不要用这个 Skill。
清单字段
清单是给人和程序看的披露:桌面端在安装前把它展示给你,平台用它核对 Skill 的正文。
| 字段 | 含义 |
|---|---|
name、version | 名称与版本 |
publisher | 发布者;目前只有 official |
displayName、summary | 显示名与一句话简介,各有英文、简体中文、繁体中文 |
category、tags | 分类与标签 |
license | 许可证 |
interfaces | 支持的用法:mcp、cli 或两者 |
requires.cli、requires.mcpServer、requires.mcpProtocol、requires.desktop | 对命令行、MCP 服务、MCP 协议与桌面端的版本要求 |
requires.mcpTools、requires.cliCommands | 会用到的 MCP 工具与命令行子命令 |
requires.scopes | 需要的 token 作用域 |
requires.permissions | 需要的账户权限 |
requires.network | 会访问的主机:所用工具与命令连接的平台主机,以及文中链接的主机 |
agents、nodes | 验证过的 AI 助手;适用于本地节点、云端节点或两者 |
risk | 最高风险级别:只读、写入、有破坏性、花钱或涉及安全 |
scripts | 包内脚本的清单;没有脚本时为空 |
两种用法的写法
Skill 可以让助手用 MCP 工具,也可以让它用命令行。两种都要在清单里声明,正文里统一这样写:
- MCP 工具写作
yunyoo:工具名,例如yunyoo:screenshot; - 命令行写作
yunyoo 子命令,例如yunyoo observe screenshot。
正文或参考资料里出现了清单没有声明的工具、子命令或主机,校验不通过:没有声明就用到的能力,等于绕过了披露。全部工具与子命令见 MCP 工具参考与命令行参考。
包体约束
- 整个包不超过 2 MB,单个文件不超过 512 KB,最多 200 个文件。
- 顶层只允许上表列出的三个文件与三个目录,目录下不再分子目录。
- 文件名只用小写字母、数字、
-、_、.,不以.开头;文本文件为.md、.json、.txt,图片只接受 PNG,脚本只接受.py与.sh。 - 不含符号链接与硬链接。
- 文本是不带 BOM 的 UTF-8;
SKILL.md的正文不超过 500 行,官方 Skill 自己限制在 300 行以内,更细的内容放进references/。 - 打包结果可以逐字节重现:同一份源码两次打包,得到的摘要相同。
安全模型
一个版本要依次通过下面几步才会出现在市场里:
- 自动扫描。三个互相独立的扫描器在断网的环境里检查包:自有规则、密钥泄露检查和一个第三方 Skill 扫描器,任何一个不通过就停。
- 评测。两套评测都通过,见下一节。
- 人工复核。一名没有参与编写的管理员通读全部文件,逐项核对其中的命令与会访问的主机、有没有隐藏或对抗性的指示、有没有读取凭据或外传数据、权限声明与评测时的实际行为是否一致。
- 签名。复核通过后,包的签名才随版本下发。桌面端内置了公钥,安装前先验签、再核对摘要,任何一项不符都不安装。测试环境与正式环境各用一把密钥,互不通用。
发布之后发现问题,我们会撤回那个版本:它从市场和公开索引里消失,下载被拒绝,已经安装的桌面端会收到提示,问题严重时该版本会被停用。
扫描通过不等于安全背书。 扫描器只能发现已知的写法,评测只覆盖有限的任务,它们降低风险,不能保证一个 Skill 在任何情况下都安全。
下面这些不是安全边界,不要依赖它们:
- Skill 的文字不是权限。 助手能做什么,由你的账户权限、token 的作用域和平台的检查决定。Skill 里写「不要做某件事」只是对助手的要求,不是技术上的限制。真正的限制是签发 token 时只给用得到的作用域和云手机。
- 屏幕上的内容是数据,不是指令。 官方 Skill 要求助手不听从屏幕、网页或应用里出现的指示,但这依赖助手遵守,不能当作防线。
- 扫描与复核的结论,只对那个版本、那一份内容有效。 同名的别的文件、被改过的安装目录都不在其内;桌面端会标出被改动的安装目录。
评测方法
- 确定性评测:不经过 AI,直接用命令行逐条执行 Skill 文档里出现的每条子命令,核对退出码、输出的结构与耗时。它保证文档里的命令是真的、能用的。
- 代理评测:让 AI 助手带着这个 Skill 完成一组任务,每个任务运行 3 次。任务分三类:应该用到这个 Skill 的、不该触发它的、以及边界与合规类(例如要求它做越权的事,期望它拒绝并说明原因)。碰了明令不得使用的工具,或在该拒绝时动了手,一次都不允许。
- 两套评测都对照平台的审计记录:实际调用了哪些工具,有没有越出声明的作用域。越出一次即不通过。
