Agent Skills
› fanfan-de/anybox
› anybox-plugin-development
anybox-plugin-development
GitHub用于创建、审查和验证 Anybox 第三方插件包。支持将 API 或工具转化为可安装插件，编写 plugin.json 配置 MCP 服务、Skills 及连接器凭据，并处理插件打包与故障排查。
Trigger Scenarios
创建 Anybox 第三方插件包
转换 API/SaaS/本地工具为可安装插件
编写或验证 plugin.json 配置文件
添加 MCP 服务器或捆绑 Skills
定义插件专属连接器及认证方式
调试插件目录或安装失败问题
Install
npx skills add fanfan-de/anybox --skill anybox-plugin-development -g -y
SKILL.md
Frontmatter
{
"name": "anybox-plugin-development",
"description": "创建、审查或验证 Anybox 第三方插件包。Use when the user asks to make a plugin, convert an API\/SaaS\/local tool into an installable plugin, write plugin.json, add plugin MCP servers, add bundled plugin skills, define plugin-owned connectors with API key or OAuth credentials, package plugin metadata, or debug plugin catalog\/install\/diagnostic failures."
}
Anybox 插件开发
使用这个 skill 来为当前仓库的插件运行时创建插件包。遇到文档和代码不一致时，以运行代码为准。
参考来源：
- 完整指南：
../../../docs/anybox-third-party-plugin-development.md - 运行时事实来源：
../../../packages/anyboxagent/src/plugin/plugin.ts - 回归测试和示例：
../../../packages/anyboxagent/Test/plugin.test.ts
工作流
- 明确插件能力：MCP 工具、随包 skill、插件自带 connector，或平台 connector requirement。
- 选择插件包结构。默认使用版本化目录。
- 编写
.anybox-plugin/plugin.json，必须是严格 JSON，只使用运行时支持的顶层字段。 - 在
.anybox-plugin同级添加运行文件，例如skills/、connectors/、scripts/、docs/和assets/。 - 使用
Plugin.listCatalog()验证 catalog 能发现插件。 - 如果修改了插件系统运行时代码，运行
bun test Test/plugin.test.ts。
插件包结构
新插件默认使用这个结构：
<install-root>/
<plugin-id>/
<version>/
.anybox-plugin/
plugin.json
skills/
<skill-name>/
SKILL.md
connectors/
scripts/
docs/
assets/
注意：
<install-root>是包含一个或多个插件包目录的父目录；开发新插件时优先把它作为ANYBOX_PLUGIN_LOCAL_DIR。- 当前运行时用
ANYBOX_PLUGIN_LOCAL_DIR发现固定本地插件仓库，未设置时默认是 Agent data 目录下的plugins/local。这个目录逻辑上等价于 GitHub 插件仓库，只提供可安装候选项，不受卸载流程删除。 ANYBOX_PLUGIN_INSTALL_DIR是受管理安装根目录，用于网络下载或从本地仓库安装时复制出来的插件包。这里的插件逻辑上属于已安装插件，运行时使用这里的副本，卸载时可能删除对应插件包。- 运行时只读取
.anybox-plugin/plugin.json；新插件必须写.anybox-plugin/plugin.json。 skills、connectors、scripts、docs和assets应放在.anybox-plugin同级，不要放进.anybox-plugin里。- 插件 ID 使用稳定的小写名称。目录名和 manifest
name尽量保持一致。
Manifest 规则
最小 manifest：
{
"name": "my-plugin",
"version": "0.1.0",
"description": "My first Anybox plugin."
}
支持的顶层字段包括：
name、version、descriptionauthor、homepage、repository、license、keywordsinterfacemcpServersskillsconnectorRequirementsconnectorsapps，仅用于旧兼容commands、agents，当前是保留字段
未知顶层字段会被拒绝。
使用 interface 配置 catalog 展示信息：
{
"interface": {
"displayName": "Hello Anybox",
"shortDescription": "A minimal plugin for learning plugin development.",
"longDescription": "This plugin demonstrates a local stdio MCP server and a bundled Agent skill.",
"developerName": "Your Name",
"category": "Automation",
"capabilities": ["demo", "mcp"],
"logo": "HA",
"brandColor": "#2563EB"
}
}
优先使用已知 catalog 分类：Code、Browser、Git、Database、Docs、Automation 和 Design。
能力模式
不需要独立连接状态或凭据生命周期的工具，使用 mcpServers：
{
"mcpServers": [
{
"id": "hello",
"name": "Hello Anybox",
"risk": "low",
"permissions": ["Starts a local Node.js MCP server bundled with this plugin."],
"tools": [
{
"name": "hello_echo",
"title": "Echo Text",
"description": "Echo text back to the user.",
"readOnly": true
}
],
"runtime": {
"transport": "stdio",
"command": "node",
"args": ["${PLUGIN_ROOT}/scripts/server.js"],
"cwd": "${PLUGIN_ROOT}",
"timeoutMs": 10000
}
}
]
}
插件需要给 Agent 提供说明时，使用 skills：
{
"skills": "skills"
}
声明的 skill root 下，每个直接子目录都必须包含 SKILL.md。例如 skills/review/SKILL.md 会生成 plugin:<plugin-id>:review。
插件需要自带 API key 或 OAuth 状态时，使用 connectors：
{
"connectors": [
{
"id": "weather",
"name": "Weather",
"risk": "medium",
"permissions": ["Sends requests to api.weather.example."],
"credential": {
"kind": "api_key",
"key": "WEATHER_API_KEY",
"label": "Weather API key",
"type": "password",
"required": true,
"secret": true
},
"runtime": {
"transport": "stdio",
"command": "node",
"args": ["${PLUGIN_ROOT}/connectors/weather/server.js"],
"cwd": "${PLUGIN_ROOT}",
"env": {
"WEATHER_API_KEY": "${WEATHER_API_KEY}"
}
},
"tools": [
{
"name": "weather_current",
"title": "Current Weather",
"description": "Read current weather for a city.",
"readOnly": true
}
]
}
]
}
插件要复用平台已有能力时，使用 connectorRequirements，例如 browser、GitHub 或 workspace files。
Runtime 规则
- 所有
${PLUGIN_ROOT}路径都必须留在插件包内部。 stdioMCP server 的普通日志写 stderr。stdout 只能输出 JSON-RPC 消息。- 本地 MCP server 必须响应
initialize、tools/list和tools/call。 - 只读工具标记
readOnly: true，破坏性操作标记destructive: true。 risk使用low、medium或high；不要使用critical，除非插件安装应该被阻止。- 不要提交 API key、OAuth client secret、access token、refresh token、本地 auth store、数据库或缓存目录。
验证
对候选插件来源根目录运行：
cd C:\Projects\anybox\packages\anyboxagent
$env:ANYBOX_PLUGIN_LOCAL_DIR = "C:\path\to\plugin-source-root"
$env:ANYBOX_PLUGIN_REGISTRY_INDEX_URL = "off"
bun -e "import * as Plugin from './src/plugin/plugin.ts'; console.log(JSON.stringify(await Plugin.listCatalog(), null, 2))"
确认输出里包含插件 ID、生成的 MCP server ID、connector-backed MCP server ID 和随包 skill ID。
修改插件系统运行时代码后运行：
cd C:\Projects\anybox\packages\anyboxagent
bun test Test/plugin.test.ts
常见失败
- 插件没有出现在 catalog：检查
ANYBOX_PLUGIN_LOCAL_DIR、目录结构、JSON 合法性、支持的顶层字段，以及必填的name、version、description。只有验证下载/安装根目录时才检查ANYBOX_PLUGIN_INSTALL_DIR。 PLUGIN_CONFIG_INVALID：检查必填configFields或 OAuth client 设置。- 诊断没有发现工具：检查命令是否可执行、runtime 路径、
cwd、JSON-RPC 方法处理，以及 stdout 是否混入普通日志。 - Connector 未连接：API key connector 需要保存 key；OAuth connector 需要完成浏览器授权。
- 卸载时源码被删：开发时使用
ANYBOX_PLUGIN_LOCAL_DIR。不要直接把 Git 源码根目录当成ANYBOX_PLUGIN_INSTALL_DIR；如果必须验证受管理安装根，复制或构建到dev-install目录。
Version History
- 08dc189 Current 2026-07-05 18:54
