create-plugin

创建插件

从零搭建新的 Claude Code 插件。

适用场景

当你想创建一个新插件，通过技能、命令和 Agent 扩展 Claude Code 时使用。此操作会生成正确的目录结构并接入 MCP 工具。

步骤

1. 向用户获取插件名称和描述
2. 检查冲突——调用 mcp__plugin_ruflo-core_ruflo__transfer_plugin-search，确保名称尚未被占用
3. 创建目录结构（遵循同级插件 ADR-0001 中的规范插件契约）：

   plugins/<name>/
   ├── .claude-plugin/
   │   └── plugin.json
   ├── skills/
   │   └── <skill-name>/
   │       └── SKILL.md
   ├── commands/
   │   └── <command-name>.md
   ├── agents/
   │   └── <agent-name>.md
   ├── docs/
   │   └── adrs/
   │       └── 0001-<name>-contract.md     # Plugin-level ADR (Proposed)
   ├── scripts/
   │   └── smoke.sh                         # Structural contract (≥8 checks)
   └── README.md                            # Compatibility + Namespace coordination + Verification + ADR sections
   

4. 生成 plugin.json，包含名称、描述、版本和作者（不要包含 skills、commands 或 agents 数组——Claude Code 会根据目录结构自动发现这些内容）
5. 生成 SKILL.md 文件，并添加正确的 frontmatter：

   ---
   name: skill-name
   description: What this skill does
   allowed-tools: mcp__plugin_ruflo-core_ruflo__tool1 mcp__plugin_ruflo-core_ruflo__tool2 Bash
   ---
   

6. 生成命令文件，并添加名称和描述 frontmatter
7. 生成 Agent 文件，并添加名称、描述和 model: sonnet
8. 生成 README.md，包含安装说明、功能、命令、技能，以及规范插件契约章节：
   • 兼容性——固定到 @claude-flow/cli v3.6 主版本和次版本
   • 命名空间协调——认领 kebab-case 格式的 <plugin-stem>-<intent> 命名空间；遵循 ruflo-agentdb ADR-0001 §“命名空间约定”
   • 验证——bash plugins/<name>/scripts/smoke.sh
   • 架构决策——链接到 ADR-0001
9. 生成 ADR-0001（提案），路径为 docs/adrs/0001-<name>-contract.md，记录：版本固定、命名空间协调、MCP 工具接口数量（如适用）、冒烟测试契约范围。状态：Proposed。
10. 生成 scripts/smoke.sh——至少包含 8 项结构检查：版本和关键词；技能/Agent/命令均存在且 frontmatter 有效；README 中固定到 v3.6；README 中包含命名空间协调区块；ADR 存在且状态为 Proposed；技能中不使用通配符工具。
11. 如果要将插件添加到 ruflo marketplace，更新 marketplace.json。

应避免的 MCP 工具漂移（根据同级插件 ADR 的经验教训）

有几个插件存在细微的 MCP 错误，迭代过程中已陆续发现。请勿重蹈覆辙：

• embeddings_embed 不存在。 实际工具是 embeddings_generate。不要在任何 allowed-tools 行中引用 embeddings_embed。
• agentdb_hierarchical-* 不会按命名空间路由。 它按层级（working|episodic|semantic）路由。传入 tier，而非 namespace。对指定命名空间进行读写时，请改用 memory_*。
• agentdb_pattern-* 不会按命名空间路由。 它通过 ReasoningBank 路由。不要传入 namespace 参数——回退写入会通过 memory-store-fallback 写入保留的 pattern 命名空间。
• pattern（单数）和 patterns（复数）是不同的命名空间。 ReasoningBank 回退写入 pattern；hooks_pretrain 写入 patterns。不要混为一谈。

Plugin.json 架构

必填字段：

• name——插件标识符（kebab-case）
• description——插件的用途
• version——语义化版本号

推荐字段：

• author——{ "name": "...", "url": "..." }
• homepage、license、keywords

可选字段：

• graph_adapter——ADR-130 图智能契约（生成的输出中默认注释掉）：

  // "graph_adapter": {
  //   "edgeRelations": ["my-relation-type"],
  //   "nodeTypes": ["entity"],
  //   "autoRegister": true
  // }
  

  当 autoRegister: true 时，核心图层会自动将此插件的边纳入 graph_edges 写入操作。 声明 edgeRelations——此插件生成的关系类型。

不要在 plugin.json 中包含 skills、commands 或 agents 数组——Claude Code 会根据目录结构自动发现这些内容；如果存在这些数组，将导致验证错误。

可连接的 MCP 工具

浏览可用工具：mcp__plugin_ruflo-core_ruflo__transfer_plugin-info

常见工具类别：

• memory_* — 存储、搜索、检索
• agentdb_* — 15 个控制器桥接工具（不要传入 namespace 参数——它们会按层级或 ReasoningBank 路由）；运行时调用 agentdb_controllers 获取规范列表
• neural_* — 神经网络训练和预测
• hooks_* — 生命周期钩子和智能功能
• browser_* — 浏览器自动化
• workflow_* — 工作流管理
• aidefence_* — 安全扫描
• embeddings_* — 10 个向量嵌入工具（使用 embeddings_generate，不要使用不存在的 embeddings_embed）