ruflo 插件脚手架完全指南用 ruflo-plugin-creator 打造符合规范契约的 Claude Code 插件【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo本指南以 ruflo 仓库中的create-plugin技能plugins/ruflo-plugin-creator/skills/create-plugin/SKILL.md为骨架完整讲解如何在 ruflo 生态中从零脚手架scaffold一个生产级 Claude Code 插件目录结构、plugin.json 契约、SKILL.md 前后置元数据、MCP 工具接线、四类经典工具引用漂移drift陷阱以及把 smoke 测试当作结构契约的验证方式。读完你既能手工照抄每一步产出也能理解底层 ADR 契约ADR-0001与验证脚本smoke.sh为何这样设计。一、背景为什么需要一个会生成契约的脚手架插件ruflo 是一个 agent meta-harness 项目其生态由大量相互协作的 Claude Code 插件构成ruflo-agentdb、ruflo-browser、ruflo-rag-memory、ruflo-intelligence 等。这些插件共享同一套规范插件契约canonical plugin contract版本钉扎pinning、命名空间协调namespace coordination、MCP 工具接线、ADR 记录、以及smoke 即契约的结构验证。ruflo-plugin-creator是其中唯一的元插件meta-plugin它自身就是 v0.2.x 的正式插件1 个 agent 2 个 skill 1 个 command但它的产出物——每一个被脚手架出来的新插件——会自动继承整套契约。这正是其 ADR-0001 的核心论断每个由它脚手架出的新插件都会继承脚手架产出的一切。ADR-0001 必须做两件事① 采用本会话中其他插件采纳的同一套契约② 更新脚手架产出让新插件天生携带契约而不是事后返工retrofit。因此本文的实操对象就是 create-plugin 技能它负责生成正确的目录结构并把 MCP 工具接好线。二、何时使用 create-plugin根据 SKILL.md 的 When to use 与命令入口 commands/create-plugin.md当你需要创建一个扩展 Claude Code 的新插件提供 skills、commands、agents时使用交互入口为/create-plugin它会先向用户收集插件名、描述、期望的 skills、commands、agents然后调用create-pluginskill 完成整套目录脚手架接着调用validate-pluginskill 验证正确性最后展示产出并用claude --plugin-dir ./plugins/name进行本地测试。三、第一步名称冲突检查plugin-search脚手架的第一步不是创建目录而是检查冲突。技能要求先调用mcp__plugin_ruflo-core_ruflo__transfer_plugin-search确认目标插件名尚未被占用。这一步在 ruflo 的多插件生态中至关重要——每个插件都要在 .claude-plugin/marketplace.json 的市场注册表中占位重名会直接破坏市场集成。从源码结构看ruflo 仓库的plugins/目录下 40 个插件全部以ruflo-前缀命名并各自维护独立目录任何新名字都必须先在全局市场中校验可用性。四、第二步生成规范目录结构技能要求脚手架产出以下目录树这也是 ruflo 家族所有插件经各自 ADR-0001 采纳的同一形状见 ruflo-plugin-creator README 的 Canonical plugin contract 一节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逐项说明每个产物的职责路径职责.claude-plugin/plugin.json插件元数据详见第五节skills/skill-name/SKILL.md技能定义目录格式而非扁平文件commands/command-name.md斜杠命令如/create-pluginagents/agent-name.md专用 agentfrontmatter 需含modeldocs/adrs/0001-name-contract.md插件级 ADR初始状态Proposedscripts/smoke.sh结构契约至少 8 项检查README.md必须包含 Compatibility / Namespace coordination / Verification / Architecture Decisions 四个段落硬性红线不得把 skills/commands/agents 放进.claude-plugin/validate-plugin技能plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md第 9 项检查明确任何 skill/command/agent 文件出现在.claude-plugin/目录内都属于结构错误。这与 plugin-developer agent 的规则一致Never put skills/commands/agents inside.claude-plugin/。五、生成 plugin.json字段契约与自动发现技能规定 plugin.json 的生成规则不要包含skills、commands、agents数组——Claude Code 会根据目录结构自动发现这些内容一旦出现这些数组反而会触发校验错误导致插件被拒。字段分层如下必需字段字段说明name插件标识kebab-case短横线小写description插件做什么version语义化版本semver推荐字段author{ name: ..., url: ... }homepage、license、keywords可选字段graph_adapterADR-130 图智能契约脚手架默认以注释形式输出按需取消注释// graph_adapter: { // edgeRelations: [my-relation-type], // nodeTypes: [entity], // autoRegister: true // }当autoRegister: true时插件产生的边会被核心图层的graph_edges写入自动收录因此必须声明edgeRelations——即本插件会产出的关系类型。验证兜底validate-plugin技能第 3、4、5、6 项会逐一断言skills 自动发现、commands 自动发现、agents 自动发现以及不存在遗留数组。凡是 plugin.json 里出现了skills/commands/agents数组一律判为校验错误。六、生成 SKILL.md、命令与 agent 文件6.1 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 ---三个字段缺一不可validate-plugin第 7 项检查且allowed-tools不允许使用通配符*——smoke.sh第 10 项与 ADR 契约都明确禁止 wildcard 工具授权。以本插件自身的 create-plugin SKILL.md 为例其allowed-tools精确列出 4 个 MCP 工具与 Bash/Read/Write/Edit而非*。6.2 命令文件命令文件同样需要namedescriptionfrontmatter正文写分派逻辑。参见本插件的 create-plugin.md 命令收集需求 → 调 skill 脚手架 → 调 validate-plugin 验证 → 给出测试指引。6.3 Agent 文件Agent 需要name、description且必须声明model: sonnet。本插件的 plugin-developer.md 是现成范例它还展示了如何在 agent 内接入记忆与神经学习# 记忆沉淀把成功插件模式存入 plugin-patterns 命名空间 npx claude-flow/clilatest memory store --namespace plugin-patterns --key plugin-TYPE --value STRUCTURE_AND_CONFIG npx claude-flow/clilatest memory search --query plugin scaffold for TYPE --namespace plugin-patterns # 任务后神经训练 npx claude-flow/clilatest hooks post-task --task-id TASK_ID --success true --train-neural true npx claude-flow/clilatest memory search --query TASK_TYPE patterns --namespace patterns注意其中patterns是复数命名空间——这正是下文漂移陷阱第 4 条涉及的命名空间区分实际使用时务必分清。七、README 的四个契约段落技能要求生成的 README 除了安装说明、特性、命令、技能清单外还必须包含四个规范契约段落Compatibility兼容性——钉扎到claude-flow/cliv3.6 的 majorminor。本插件 README 原文CLI: pinned toclaude-flow/cliv3.6 majorminorsmoke.sh第 6 项会 grep 校验这一钉扎声明。Namespace coordination命名空间协调——声明 kebab-case 的plugin-stem-intent命名空间遵循 ruflo-agentdb ADR-0001 §Namespace convention。纯脚手架类插件如本插件可以声明无 AgentDB 写入但仍必须保留该段落。Verification验证——bash plugins/name/scripts/smoke.sh即契约。Architecture Decisions架构决策——链接到docs/adrs/0001-name-contract.md。八、生成 ADR-0001Proposed脚手架在docs/adrs/0001-name-contract.md生成插件级 ADR记录四件事版本钉扎pinning命名空间协调namespace coordinationMCP 工具面数量如适用surface countsmoke 契约范围smoke contract scope。状态初始为Proposed。本插件自身的 ADR-0001 状态为Accepted由Proposed演进而来其 Implementation status 记录脚手架模板已默认生成契约 ADR、smoke 测试、Compatibility 段与命名空间协调块并把 MCP-drift 警告加入被脚手架出的技能模板。九、生成 scripts/smoke.sh至少 8 项结构检查技能要求新插件的 smoke.sh 至少包含 8 项结构性检查版本号与关键词version keywordsskills/agents/commands 存在且 frontmatter 合法README 中存在 v3.6 钉扎README 中存在命名空间协调块ADR 存在且状态为Proposed技能中无通配符工具。本插件自身的 smoke.sh 是 10 项检查的完整范例bashgrep即可运行无外部依赖核心片段#!/usr/bin/env bash set -u ROOT$(cd $(dirname $0)/.. pwd) PASS0; FAIL0 # 检查 1plugin.json 声明版本与 mcp/scaffolding/contract-bootstrap 关键词 step 1. plugin.json declares 0.2.1 with new keywords v$(grep -E version $ROOT/.claude-plugin/plugin.json | grep -oE [0-9]\.[0-9]\.[0-9] | head -1) ... # 检查 4create-plugin 包含 MCP 工具漂移警告 step 4. create-plugin includes MCP-tool drift warnings grep -q embeddings_embed $F || miss$miss embed-warning ... printf \n%s passed, %s failed\n $PASS $FAIL [[ $FAIL -eq 0 ]] || exit 110 项检查清单来自 ADR-0001 §3 Smoke contractplugin.json 声明 0.2.x 且含新关键词两个 skill agent command 均存在且 frontmatter 合法create-plugin skill 会脚手架出 ADR、smoke、README 契约段create-plugin skill 包含 MCP 工具漂移警告create-plugin skill 不再声称19 AgentDB controllers回归检查README 钉扎claude-flow/cliv3.6README 有 Architecture Decisions 段ADR-0001 存在且状态合法validate-plugin skill 存在无技能授予通配符工具权限。运行方式bash plugins/name/scripts/smoke.sh期望输出如10 passed, 0 failed。十、必读四类 MCP 工具漂移陷阱sibling-ADR 血泪教训这是整个技能中最具实战价值的部分。多个已发布插件曾携带微妙的 MCP bug循环loop在家族内逐一修复后脚手架技能把这些教训固化成了警告。新插件作者必须规避陷阱 1embeddings_embed不存在真实的工具是embeddings_generate。任何allowed-tools行里出现embeddings_embed都属于无效引用该名称在 ruflo-knowledge-graph ADR-0001 中有 rename 记录。embeddings_*共 10 个向量嵌入工具一律使用embeddings_generate。陷阱 2agentdb_hierarchical-*不按命名空间路由该类工具按tier层级路由working | episodic | semantic。传namespace参数会被静默忽略。需要按命名空间读写时改用memory_*工具。陷阱 3agentdb_pattern-*不按命名空间路由该类工具经由ReasoningBank路由同样不要传namespace参数其回退写入落在保留命名空间patternmemory-store-fallback。陷阱 4pattern单数与patterns复数是两个不同的命名空间ReasoningBank 回退写入patternhooks_pretrain写入patterns。两者不可混用。这四条警告已被smoke.sh第 4 项以 grep 断言固化ruflo-plugin-creator README 的 MCP-tool drift to avoid 表格也做了摘要。深层契约在 ruflo-agentdb ADR-0001 与 ruflo-agentdb README §Namespace convention命名规范为 kebab-caseplugin-stem-intent如browser-sessions、browser-selectors三个保留命名空间不得遮蔽patternReasoningBank 回退写入、claude-memoriesClaude Code 自动记忆桥、defaultmemory_store默认值命名空间字符串只对memory_*与embeddings_search生效命名空间不得含:与桥接层内部键分隔符冲突、长度 ≤200 字符、必须通过validateIdentifier校验。十一、可接线的 MCP 工具分类总览脚手架阶段需要把 MCP 工具写进allowed-tools。技能给出的分类指引可用mcp__plugin_ruflo-core_ruflo__transfer_plugin-info浏览全部可用工具分类用途注意事项memory_*存储、搜索、检索按命名空间路由需传 namespaceagentdb_*15 个 controller-bridge 工具不要传 namespace 参数按 tier 或 ReasoningBank 路由运行期用agentdb_controllers获取权威工具清单neural_*神经训练与预测——hooks_*生命周期钩子与智能hooks_pretrain写patterns命名空间browser_*浏览器自动化——workflow_*工作流管理——aidefence_*安全扫描——embeddings_*10 个向量嵌入工具用embeddings_generate不要用embeddings_embed关于agentdb_*的15 个工具数字ADR-0001 明确记录了一个漂移修复——旧文档声称19 个 AgentDB controllers实际为 15 个agentdb_*MCP 工具另约 29 个ControllerName条目。不要在文档里硬编码控制器数量运行期以agentdb_controllers的返回为准这正是 smoke.sh 第 5 项回归检查的用意。十二、市场集成与最终验证脚手架最后一步如果要把插件加入 ruflo 市场更新 .claude-plugin/marketplace.json本插件自身 v0.2.x 已按 ADR 记录列入市场。ruflo 家族插件的 README 安装范式为/plugin marketplace add ruvnet/ruflo /plugin install ruflo-plugin-creatorruflo新插件安装后用claude --plugin-dir ./plugins/name本地加载测试见 plugin-developer agent。发布前的完整检查链为# 1. 结构契约smoke 即契约 bash plugins/name/scripts/smoke.sh # 期望输出N passed, 0 failed # 2. 语义验证validate-plugin skill 逐项断言 # 目录结构 / plugin.json schema / 自动发现 / 无遗留数组 / frontmatter / MCP 引用合法性 # 3. 本地加载冒烟 claude --plugin-dir ./plugins/name十三、一张图看懂整个脚手架闭环用本插件的自举案例收尾ruflo-plugin-creator用 create-plugin 技能 产出新插件 → 新插件继承契约ADR smoke README 四段→ validate-plugin 技能 在发布前拦截结构问题 → smoke.sh 把契约固化为可执行断言 → MCP 漂移警告让新作者绕开四类历史 bug。整个流程保证了新插件天生携带契约无需事后返工——这是该元插件区别于普通模板生成器的根本价值所在。延伸阅读create-plugin 技能原文ruflo-plugin-creator READMEADR-0001脚手架即契约的设计决策smoke.sh10 项结构检查脚本validate-plugin 技能agentdb 命名空间契约 与 agentdb ADR-0001市场注册表【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ruflo 插件脚手架完全指南用 ruflo-plugin-creator 打造符合规范契约的 Claude Code 插件【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo本指南以 ruflo 仓库中的create-plugin技能plugins/ruflo-plugin-creator/skills/create-plugin/SKILL.md为骨架完整讲解如何在 ruflo 生态中从零脚手架scaffold一个生产级 Claude Code 插件目录结构、plugin.json 契约、SKILL.md 前后置元数据、MCP 工具接线、四类经典工具引用漂移drift陷阱以及把 smoke 测试当作结构契约的验证方式。读完你既能手工照抄每一步产出也能理解底层 ADR 契约ADR-0001与验证脚本smoke.sh为何这样设计。一、背景为什么需要一个会生成契约的脚手架插件ruflo 是一个 agent meta-harness 项目其生态由大量相互协作的 Claude Code 插件构成ruflo-agentdb、ruflo-browser、ruflo-rag-memory、ruflo-intelligence 等。这些插件共享同一套规范插件契约canonical plugin contract版本钉扎pinning、命名空间协调namespace coordination、MCP 工具接线、ADR 记录、以及smoke 即契约的结构验证。ruflo-plugin-creator是其中唯一的元插件meta-plugin它自身就是 v0.2.x 的正式插件1 个 agent 2 个 skill 1 个 command但它的产出物——每一个被脚手架出来的新插件——会自动继承整套契约。这正是其 ADR-0001 的核心论断每个由它脚手架出的新插件都会继承脚手架产出的一切。ADR-0001 必须做两件事① 采用本会话中其他插件采纳的同一套契约② 更新脚手架产出让新插件天生携带契约而不是事后返工retrofit。因此本文的实操对象就是 create-plugin 技能它负责生成正确的目录结构并把 MCP 工具接好线。二、何时使用 create-plugin根据 SKILL.md 的 When to use 与命令入口 commands/create-plugin.md当你需要创建一个扩展 Claude Code 的新插件提供 skills、commands、agents时使用交互入口为/create-plugin它会先向用户收集插件名、描述、期望的 skills、commands、agents然后调用create-pluginskill 完成整套目录脚手架接着调用validate-pluginskill 验证正确性最后展示产出并用claude --plugin-dir ./plugins/name进行本地测试。三、第一步名称冲突检查plugin-search脚手架的第一步不是创建目录而是检查冲突。技能要求先调用mcp__plugin_ruflo-core_ruflo__transfer_plugin-search确认目标插件名尚未被占用。这一步在 ruflo 的多插件生态中至关重要——每个插件都要在 .claude-plugin/marketplace.json 的市场注册表中占位重名会直接破坏市场集成。从源码结构看ruflo 仓库的plugins/目录下 40 个插件全部以ruflo-前缀命名并各自维护独立目录任何新名字都必须先在全局市场中校验可用性。四、第二步生成规范目录结构技能要求脚手架产出以下目录树这也是 ruflo 家族所有插件经各自 ADR-0001 采纳的同一形状见 ruflo-plugin-creator README 的 Canonical plugin contract 一节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逐项说明每个产物的职责路径职责.claude-plugin/plugin.json插件元数据详见第五节skills/skill-name/SKILL.md技能定义目录格式而非扁平文件commands/command-name.md斜杠命令如/create-pluginagents/agent-name.md专用 agentfrontmatter 需含modeldocs/adrs/0001-name-contract.md插件级 ADR初始状态Proposedscripts/smoke.sh结构契约至少 8 项检查README.md必须包含 Compatibility / Namespace coordination / Verification / Architecture Decisions 四个段落硬性红线不得把 skills/commands/agents 放进.claude-plugin/validate-plugin技能plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md第 9 项检查明确任何 skill/command/agent 文件出现在.claude-plugin/目录内都属于结构错误。这与 plugin-developer agent 的规则一致Never put skills/commands/agents inside.claude-plugin/。五、生成 plugin.json字段契约与自动发现技能规定 plugin.json 的生成规则不要包含skills、commands、agents数组——Claude Code 会根据目录结构自动发现这些内容一旦出现这些数组反而会触发校验错误导致插件被拒。字段分层如下必需字段字段说明name插件标识kebab-case短横线小写description插件做什么version语义化版本semver推荐字段author{ name: ..., url: ... }homepage、license、keywords可选字段graph_adapterADR-130 图智能契约脚手架默认以注释形式输出按需取消注释// graph_adapter: { // edgeRelations: [my-relation-type], // nodeTypes: [entity], // autoRegister: true // }当autoRegister: true时插件产生的边会被核心图层的graph_edges写入自动收录因此必须声明edgeRelations——即本插件会产出的关系类型。验证兜底validate-plugin技能第 3、4、5、6 项会逐一断言skills 自动发现、commands 自动发现、agents 自动发现以及不存在遗留数组。凡是 plugin.json 里出现了skills/commands/agents数组一律判为校验错误。六、生成 SKILL.md、命令与 agent 文件6.1 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 ---三个字段缺一不可validate-plugin第 7 项检查且allowed-tools不允许使用通配符*——smoke.sh第 10 项与 ADR 契约都明确禁止 wildcard 工具授权。以本插件自身的 create-plugin SKILL.md 为例其allowed-tools精确列出 4 个 MCP 工具与 Bash/Read/Write/Edit而非*。6.2 命令文件命令文件同样需要namedescriptionfrontmatter正文写分派逻辑。参见本插件的 create-plugin.md 命令收集需求 → 调 skill 脚手架 → 调 validate-plugin 验证 → 给出测试指引。6.3 Agent 文件Agent 需要name、description且必须声明model: sonnet。本插件的 plugin-developer.md 是现成范例它还展示了如何在 agent 内接入记忆与神经学习# 记忆沉淀把成功插件模式存入 plugin-patterns 命名空间 npx claude-flow/clilatest memory store --namespace plugin-patterns --key plugin-TYPE --value STRUCTURE_AND_CONFIG npx claude-flow/clilatest memory search --query plugin scaffold for TYPE --namespace plugin-patterns # 任务后神经训练 npx claude-flow/clilatest hooks post-task --task-id TASK_ID --success true --train-neural true npx claude-flow/clilatest memory search --query TASK_TYPE patterns --namespace patterns注意其中patterns是复数命名空间——这正是下文漂移陷阱第 4 条涉及的命名空间区分实际使用时务必分清。七、README 的四个契约段落技能要求生成的 README 除了安装说明、特性、命令、技能清单外还必须包含四个规范契约段落Compatibility兼容性——钉扎到claude-flow/cliv3.6 的 majorminor。本插件 README 原文CLI: pinned toclaude-flow/cliv3.6 majorminorsmoke.sh第 6 项会 grep 校验这一钉扎声明。Namespace coordination命名空间协调——声明 kebab-case 的plugin-stem-intent命名空间遵循 ruflo-agentdb ADR-0001 §Namespace convention。纯脚手架类插件如本插件可以声明无 AgentDB 写入但仍必须保留该段落。Verification验证——bash plugins/name/scripts/smoke.sh即契约。Architecture Decisions架构决策——链接到docs/adrs/0001-name-contract.md。八、生成 ADR-0001Proposed脚手架在docs/adrs/0001-name-contract.md生成插件级 ADR记录四件事版本钉扎pinning命名空间协调namespace coordinationMCP 工具面数量如适用surface countsmoke 契约范围smoke contract scope。状态初始为Proposed。本插件自身的 ADR-0001 状态为Accepted由Proposed演进而来其 Implementation status 记录脚手架模板已默认生成契约 ADR、smoke 测试、Compatibility 段与命名空间协调块并把 MCP-drift 警告加入被脚手架出的技能模板。九、生成 scripts/smoke.sh至少 8 项结构检查技能要求新插件的 smoke.sh 至少包含 8 项结构性检查版本号与关键词version keywordsskills/agents/commands 存在且 frontmatter 合法README 中存在 v3.6 钉扎README 中存在命名空间协调块ADR 存在且状态为Proposed技能中无通配符工具。本插件自身的 smoke.sh 是 10 项检查的完整范例bashgrep即可运行无外部依赖核心片段#!/usr/bin/env bash set -u ROOT$(cd $(dirname $0)/.. pwd) PASS0; FAIL0 # 检查 1plugin.json 声明版本与 mcp/scaffolding/contract-bootstrap 关键词 step 1. plugin.json declares 0.2.1 with new keywords v$(grep -E version $ROOT/.claude-plugin/plugin.json | grep -oE [0-9]\.[0-9]\.[0-9] | head -1) ... # 检查 4create-plugin 包含 MCP 工具漂移警告 step 4. create-plugin includes MCP-tool drift warnings grep -q embeddings_embed $F || miss$miss embed-warning ... printf \n%s passed, %s failed\n $PASS $FAIL [[ $FAIL -eq 0 ]] || exit 110 项检查清单来自 ADR-0001 §3 Smoke contractplugin.json 声明 0.2.x 且含新关键词两个 skill agent command 均存在且 frontmatter 合法create-plugin skill 会脚手架出 ADR、smoke、README 契约段create-plugin skill 包含 MCP 工具漂移警告create-plugin skill 不再声称19 AgentDB controllers回归检查README 钉扎claude-flow/cliv3.6README 有 Architecture Decisions 段ADR-0001 存在且状态合法validate-plugin skill 存在无技能授予通配符工具权限。运行方式bash plugins/name/scripts/smoke.sh期望输出如10 passed, 0 failed。十、必读四类 MCP 工具漂移陷阱sibling-ADR 血泪教训这是整个技能中最具实战价值的部分。多个已发布插件曾携带微妙的 MCP bug循环loop在家族内逐一修复后脚手架技能把这些教训固化成了警告。新插件作者必须规避陷阱 1embeddings_embed不存在真实的工具是embeddings_generate。任何allowed-tools行里出现embeddings_embed都属于无效引用该名称在 ruflo-knowledge-graph ADR-0001 中有 rename 记录。embeddings_*共 10 个向量嵌入工具一律使用embeddings_generate。陷阱 2agentdb_hierarchical-*不按命名空间路由该类工具按tier层级路由working | episodic | semantic。传namespace参数会被静默忽略。需要按命名空间读写时改用memory_*工具。陷阱 3agentdb_pattern-*不按命名空间路由该类工具经由ReasoningBank路由同样不要传namespace参数其回退写入落在保留命名空间patternmemory-store-fallback。陷阱 4pattern单数与patterns复数是两个不同的命名空间ReasoningBank 回退写入patternhooks_pretrain写入patterns。两者不可混用。这四条警告已被smoke.sh第 4 项以 grep 断言固化ruflo-plugin-creator README 的 MCP-tool drift to avoid 表格也做了摘要。深层契约在 ruflo-agentdb ADR-0001 与 ruflo-agentdb README §Namespace convention命名规范为 kebab-caseplugin-stem-intent如browser-sessions、browser-selectors三个保留命名空间不得遮蔽patternReasoningBank 回退写入、claude-memoriesClaude Code 自动记忆桥、defaultmemory_store默认值命名空间字符串只对memory_*与embeddings_search生效命名空间不得含:与桥接层内部键分隔符冲突、长度 ≤200 字符、必须通过validateIdentifier校验。十一、可接线的 MCP 工具分类总览脚手架阶段需要把 MCP 工具写进allowed-tools。技能给出的分类指引可用mcp__plugin_ruflo-core_ruflo__transfer_plugin-info浏览全部可用工具分类用途注意事项memory_*存储、搜索、检索按命名空间路由需传 namespaceagentdb_*15 个 controller-bridge 工具不要传 namespace 参数按 tier 或 ReasoningBank 路由运行期用agentdb_controllers获取权威工具清单neural_*神经训练与预测——hooks_*生命周期钩子与智能hooks_pretrain写patterns命名空间browser_*浏览器自动化——workflow_*工作流管理——aidefence_*安全扫描——embeddings_*10 个向量嵌入工具用embeddings_generate不要用embeddings_embed关于agentdb_*的15 个工具数字ADR-0001 明确记录了一个漂移修复——旧文档声称19 个 AgentDB controllers实际为 15 个agentdb_*MCP 工具另约 29 个ControllerName条目。不要在文档里硬编码控制器数量运行期以agentdb_controllers的返回为准这正是 smoke.sh 第 5 项回归检查的用意。十二、市场集成与最终验证脚手架最后一步如果要把插件加入 ruflo 市场更新 .claude-plugin/marketplace.json本插件自身 v0.2.x 已按 ADR 记录列入市场。ruflo 家族插件的 README 安装范式为/plugin marketplace add ruvnet/ruflo /plugin install ruflo-plugin-creatorruflo新插件安装后用claude --plugin-dir ./plugins/name本地加载测试见 plugin-developer agent。发布前的完整检查链为# 1. 结构契约smoke 即契约 bash plugins/name/scripts/smoke.sh # 期望输出N passed, 0 failed # 2. 语义验证validate-plugin skill 逐项断言 # 目录结构 / plugin.json schema / 自动发现 / 无遗留数组 / frontmatter / MCP 引用合法性 # 3. 本地加载冒烟 claude --plugin-dir ./plugins/name十三、一张图看懂整个脚手架闭环用本插件的自举案例收尾ruflo-plugin-creator用 create-plugin 技能 产出新插件 → 新插件继承契约ADR smoke README 四段→ validate-plugin 技能 在发布前拦截结构问题 → smoke.sh 把契约固化为可执行断言 → MCP 漂移警告让新作者绕开四类历史 bug。整个流程保证了新插件天生携带契约无需事后返工——这是该元插件区别于普通模板生成器的根本价值所在。延伸阅读create-plugin 技能原文ruflo-plugin-creator READMEADR-0001脚手架即契约的设计决策smoke.sh10 项结构检查脚本validate-plugin 技能agentdb 命名空间契约 与 agentdb ADR-0001市场注册表【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考