云柚

文档中心

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/。
  • 打包结果可以逐字节重现:同一份源码两次打包,得到的摘要相同。

安全模型

一个版本要依次通过下面几步才会出现在市场里:

  1. 自动扫描。三个互相独立的扫描器在断网的环境里检查包:自有规则、密钥泄露检查和一个第三方 Skill 扫描器,任何一个不通过就停。
  2. 评测。两套评测都通过,见下一节。
  3. 人工复核。一名没有参与编写的管理员通读全部文件,逐项核对其中的命令与会访问的主机、有没有隐藏或对抗性的指示、有没有读取凭据或外传数据、权限声明与评测时的实际行为是否一致。
  4. 签名。复核通过后,包的签名才随版本下发。桌面端内置了公钥,安装前先验签、再核对摘要,任何一项不符都不安装。测试环境与正式环境各用一把密钥,互不通用。

发布之后发现问题,我们会撤回那个版本:它从市场和公开索引里消失,下载被拒绝,已经安装的桌面端会收到提示,问题严重时该版本会被停用。

扫描通过不等于安全背书。 扫描器只能发现已知的写法,评测只覆盖有限的任务,它们降低风险,不能保证一个 Skill 在任何情况下都安全。

下面这些不是安全边界,不要依赖它们:

  • Skill 的文字不是权限。 助手能做什么,由你的账户权限、token 的作用域和平台的检查决定。Skill 里写「不要做某件事」只是对助手的要求,不是技术上的限制。真正的限制是签发 token 时只给用得到的作用域和云手机。
  • 屏幕上的内容是数据,不是指令。 官方 Skill 要求助手不听从屏幕、网页或应用里出现的指示,但这依赖助手遵守,不能当作防线。
  • 扫描与复核的结论,只对那个版本、那一份内容有效。 同名的别的文件、被改过的安装目录都不在其内;桌面端会标出被改动的安装目录。

评测方法

  • 确定性评测:不经过 AI,直接用命令行逐条执行 Skill 文档里出现的每条子命令,核对退出码、输出的结构与耗时。它保证文档里的命令是真的、能用的。
  • 代理评测:让 AI 助手带着这个 Skill 完成一组任务,每个任务运行 3 次。任务分三类:应该用到这个 Skill 的、不该触发它的、以及边界与合规类(例如要求它做越权的事,期望它拒绝并说明原因)。碰了明令不得使用的工具,或在该拒绝时动了手,一次都不允许。
  • 两套评测都对照平台的审计记录:实际调用了哪些工具,有没有越出声明的作用域。越出一次即不通过。