ZJU-REAL 插件创建器（Plugin Creator）
插件 = 一组配套的技能 + 工具，打成一个可整体安装、整体卸载的单元。
本技能教你在沙箱里攒出一个结构合法的插件包，自检合格后通过 import_plugin 落库。
只想做单个技能？那不需要插件——用技能管理插件的
skill-creator/register_skill更直接。插件的价值在于"成套"：多个技能配一个工具服务、或者需要统一装卸的一组能力。
一、插件包长什么样
最小可用结构（原生格式）：
my-plugin/
├── plugin.json # 必需：插件清单
├── mcp.json # 可选：要带工具服务时才有
└── skills/ # 可选：要带技能时才有
├── skill-a/
│ └── SKILL.md
└── skill-b/
└── SKILL.md
规则：
plugin.json必须在包根（也接受.claude-plugin/plugin.json布局）。没有它就不是插件包，import_plugin会拒绝。skills/下每个子目录一个技能，各自必须有SKILL.md。没有 SKILL.md 的子目录会被忽略。- 打包时要 从插件目录内部打，别把外层目录名也裹进去：
tar -czf /workspace/plugin.tgz -C my-plugin .
二、plugin.json 怎么写
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "my-plugin",
"version": "1.0.0",
"description": "一句话说清这个插件给用户带来什么能力。",
"author": { "name": "……" },
"extensions": {
"org.hugagent": {
"mcp": {
"my_server": {
"display_name": "界面上显示的名字",
"description": "这个工具服务是干什么的。",
"tools": [
{ "name": "do_something", "description": "……" }
]
}
}
}
}
}
要点：
name就是 slug：小写字母/数字/连字符，会被用来生成安装 id，别用中文和空格。- 标准清单本身不放展示字段（显示名、分类、图标属于界面配置，由平台侧维护）；
平台专有字段一律放进
extensions["org.hugagent"]。 extensions["org.hugagent"].mcp.<服务名>里的display_name/description/tools会覆盖补全到对应的 MCP 服务上，服务名必须和mcp.json里的键一致，否则贴不上去。- 需要用户填凭据时，在扩展段里写
required_secrets（字符串数组）， 安装时平台会据此向用户索要。
字段清单与各种兼容布局详见 references/manifest-spec.md。
三、工具描述怎么写（最影响好不好用的一步）
tools[].description 不是给人看的文档，是模型判断"该不该调这个工具"的唯一依据。
写不好，插件装了也不会被用，或者被乱用。
一条好的工具描述包含四件事：
- 它做什么（一句话，动词开头）
- 用户说什么话时该调它（把真实说法列进去，"用户说'……'时调用"）
- 参数从哪来（尤其是 id 类参数：取自哪个工具的返回）
- 红线（不可恢复的操作要写"必须先确认"；写操作要写"未拿到成功回执前不要声称已完成"）
反面例子："description": "管理数据"——模型无从判断何时该用。
四、完整流程
- 在沙箱
/workspace里按上面的结构建好目录，写好plugin.json（要带技能就再写skills/*/SKILL.md，要带工具就再写mcp.json）。 - 自检（务必做，结构不对导入会失败）：
退出码 0 才继续。python3 scripts/validate_plugin.py /workspace/my-plugin - 打包：
tar -czf /workspace/plugin.tgz -C /workspace/my-plugin . - 调框架自带的
sandbox_get_artifact("/workspace/plugin.tgz")取得artifact_id。 - 调
import_plugin(artifact_id)落库。 - 拿到 ✅ 后，把"装进来了哪些技能和工具"讲给用户听。
五、从 web 链接安装
用户给一个下载链接时，同一条路：
- 沙箱里
curl -L -o /workspace/pkg.zip "<链接>" - 解压到一个目录，先看清楚里面是什么（有没有
plugin.json） - 跑一遍
validate_plugin.py自检 - 重新打包 →
sandbox_get_artifact→import_plugin
安全提醒：来路不明的包不要闭眼导入。至少确认 plugin.json 里的 name、
description 与用户的预期一致，mcp.json 里的 url 指向的是可信地址。
发现可疑内容就停下来问用户，不要替用户承担这个风险。
六、交付前自检
-
plugin.json在包根，name是合法 slug - 每个
skills/*/下都有SKILL.md -
mcp.json的服务名与扩展段里的 mcp 键一一对应 - 每个工具的 description 写清了"何时该调 + 参数从哪来 + 红线"
-
validate_plugin.py退出码为 0 - 是从插件目录内部打的包（
tar -C <dir> .）
拿到 ✅ 之前不要声称已经导入成功。