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导读plugin-developer是 ruflo 仓库中 ruflo-plugin-creator 插件内置的插件开发专家 Agent其职责是面向 Claude Code 生态完成插件的脚手架Scaffold、格式验证Validate与市场发布Publish。本文以该 Agent 的职责说明文档为主体结合仓库内 create-plugin 技能、validate-plugin 技能、ADR-0001 契约 与 smoke.sh 验证脚本 的源码级实现完整还原一套可复制、可运行的 Claude Code 插件开发工作流。读完本文你将掌握插件目录结构的正确形态、SKILL.md 的 frontmatter 规范、MCP 工具的接线规则、发布前的 10 项冒烟校验以及如何借助 ruflo 的记忆与神经学习能力沉淀插件开发模式。一、插件开发专家的角色定位plugin-developer.md 通过 frontmatter 声明了该 Agent 的身份name: plugin-developerdescription: Plugin development specialist for scaffolding, validating, and publishing Claude Code plugins并指定model: sonnet——这与 ruflo 插件体系中所有 Agent 文件的规范一致见下方“关键规则”。该 Agent 的五大核心职责是Scaffold plugins—— 以正确的目录结构plugin.json、skills/、commands/、agents/生成新插件Write SKILL.md files—— 编写带规范 frontmattername、description、allowed-tools的技能文件Wire MCP tools—— 将 ruflo MCP server 的工具接入 skill 的allowed-tools声明Validate plugins—— 对照官方 Claude Code 插件格式做校验Update marketplace—— 将新插件登记进marketplace.json实现分发。从仓库结构看这五个职责在 ruflo-plugin-creator 中被拆解为1 个 Agent 2 个 Skill 1 个 Command的轻量组合create-plugin技能负责职责 1–3、validate-plugin技能负责职责 4而/create-plugin命令见 create-plugin.md负责把整个过程串成交互式流程。二、插件的关键规则与目录结构规范2.1 六大关键规则Agent 文档明确列出开发 Claude Code 插件时必须遵守的规则任何一条违规都会导致校验失败规则说明技能目录格式Skills 必须放在skills/name/SKILL.md目录格式不能是扁平文件命令文件Commands 放在commands/name.mdAgent 文件Agents 放在agents/name.mdfrontmatter 必须含model: sonnet目录隔离严禁把 skills/commands/agents 放进.claude-plugin/目录内plugin.json 字段必须包含name、description、version以及skills、commands、agents数组SKILL.md 的 allowed-tools所有 SKILL.md 必须通过allowed-tools列出其使用的 MCP 工具需要注意一个关键演进create-plugin 技能 第 4 步明确指出生成的plugin.json只包含name、description、version、author不要写入skills、commands、agents数组——因为 Claude Code 会从目录结构自动发现auto-discover这些内容手动写入反而会触发验证错误。这一点与 validate-plugin 技能 的第 6 项检查plugin.json中出现这三个数组即为校验错误互为印证。因此表格中“plugin.json 必须含数组”这一规则应理解为 Agent 文档早期版本的表述当前仓库的实际契约以“自动发现、禁止显式数组”为准。2.2 规范化插件目录结构canonical contractruflo-plugin-creator README 的 “Canonical plugin contract” 一节展示了每个被脚手架生成的插件都会继承的统一形态该契约源自 ruflo 家族各插件各自的 ADR-0001详见 ADR-0001-plugin-creator-contractplugins/name/ ├── .claude-plugin/plugin.json # version、keywords、mcp keyword ├── skills/skill/SKILL.md # name description allowed-tools禁止通配符 ├── commands/command.md # name description 分发逻辑 ├── agents/agent.md # name description model ├── docs/adrs/0001-name-contract.md # ADRProposed—— pinning、namespace、smoke 范围 ├── scripts/smoke.sh # 结构契约≥8 项检查 └── README.md # Compatibility Namespace coordination Verification ADR也就是说脚手架产出的不仅是“能跑”的插件而是一个自带契约文档、冒烟测试与兼容性说明的完整工程单元。ADR-0001 对这套结构的定位是“scaffold-the-canonical-contract”让新插件出生即带契约而不是事后修补。三、SKILL.md 的规范写法与 MCP 工具接线3.1 frontmatter 三要素Agent 文档要求每个 SKILL.md 具备name、description、allowed-tools三个 frontmatter 字段。create-plugin 技能 第 5 步给出了生成模板--- name: skill-name description: What this skill does allowed-tools: mcp__plugin_ruflo-core_ruflo__tool1 mcp__plugin_ruflo-core_ruflo__tool2 Bash ---仓库中真实的例子是create-plugin技能自身的 frontmatter--- name: create-plugin description: Scaffold a new Claude Code plugin with proper directory structure, plugin.json, skills, commands, and agents argument-hint: plugin-name allowed-tools: mcp__plugin_ruflo-core_ruflo__transfer_plugin-info mcp__plugin_ruflo-core_ruflo__transfer_plugin-search mcp__plugin_ruflo-core_ruflo__transfer_store-search Bash Read Write Edit ---可以看到它额外声明了argument-hint提示参数用法。其中mcp__plugin_ruflo-core_ruflo__transfer_plugin-info与mcp__plugin_ruflo-core_ruflo__transfer_plugin-search用于在生成前检查插件名是否已被占用create-plugin 技能第 2 步transfer_store-search用于冲突检测与检索。3.2 allowed-tools 的接线原则精确声明禁止通配符两条硬性要求每条 allowed-tools 必须列出实际使用的 MCP 工具不能省略禁止使用通配符如allowed-tools: *。validate-plugin技能与smoke.sh第 10 项检查grep -q ^allowed-tools:[[:space:]]*\*见 smoke.sh都会对这一点做校验。3.3 可接线的 MCP 工具分类create-plugin 技能 的 “Available MCP tools to wire” 一节列出了 ruflo MCP server 常见的工具族供插件作者在allowed-tools中声明工具族用途注意事项memory_*存储、搜索、检索按 namespace 路由需要传 namespaceagentdb_*15 个 controller-bridge 工具不要传namespace参数——按 tier 或 ReasoningBank 路由以agentdb_controllers运行时输出为准neural_*神经训练与预测—hooks_*生命周期钩子与智能—browser_*浏览器自动化—workflow_*工作流管理—aidefence_*安全扫描—embeddings_*10 个向量嵌入工具用embeddings_generate不存在embeddings_embed四、MCP 工具漂移陷阱四类高频 Bug 及其规避这是 create-plugin 技能 与 README 共同强调的重点章节——ruflo 家族多个插件曾上线后被自动化巡检发现上述接线错误因此脚手架会为每个新插件内置“MCP-tool drift to avoid”警告段落。四类必须规避的漂移embeddings_embed不存在。真实工具是embeddings_generate。任何allowed-tools行里引用embeddings_embed都会失效ruflo-knowledge-graph、ruflo-market-data曾修复此类引用现已成为脚手架的警告项。agentdb_hierarchical-*不按 namespace 路由它按 tierworking|episodic|semantic路由。必须传tier而不是namespace需要按 namespace 读写时改用memory_*。agentdb_pattern-*不按 namespace 路由它经由 ReasoningBank 路由。不要传namespace参数——回退写入会落到保留的patternnamespace经memory-store-fallback。pattern单数与patterns复数是两个不同的保留 namespace。ReasoningBank 回退写入patternhooks_pretrain写入patterns切勿混为一谈。此外还有一条“19 个 AgentDB controllers”的陈旧说法ADR-0001 记录create-plugin技能早期文案声称存在 19 个控制器而 ruflo-agentdb ADR-0001 证实真实数量为15 个agentdb_*MCP 工具、29 个ControllerName条目详见 ruflo-agentdb README 的控制器注册表。脚手架现在要求以agentdb_controllers运行时输出为准并在 smoke.sh 第 5 项检查 中做回归检测防止陈旧数字回潮。关于 namespace 路由语义的底层佐证可参考 ruflo-agentdb README 的 “Where namespace strings actually apply” 一节memory_*与embeddings_search按 namespace 路由agentdb_hierarchical-*、agentdb_pattern-*、agentdb_causal-edge均忽略 namespace 参数。向agentdb_pattern-store传namespace: browser-cookies期望做过滤是无效的参数会被静默丢弃。五、插件验证validate-plugin 的十项检查Agent 文档职责 4 是“Validate plugins against the official Claude Code plugin format”validate-plugin 技能 将其落实为 10 项具体检查#检查项判定要点1目录结构插件根目录存在.claude-plugin/plugin.json2plugin.json schemaname、description、version必填字段齐全3技能自动发现每个skills/name/SKILL.md是合法技能plugin.json不得列出skills数组4命令自动发现每个commands/name.md是合法命令plugin.json不得列出commands数组5Agent 自动发现每个agents/name.md是合法 Agentplugin.json不得列出agents数组6禁止遗留数组plugin.json中出现skills/commands/agents数组即校验错误7SKILL.md frontmatter每个技能有name、description、allowed-tools且无通配符8Agent frontmatter每个 Agent 有name、description、model9文件位置skills/commands/agents 不得位于.claude-plugin/内10MCP 工具引用allowed-tools中的工具必须是合法的mcp__plugin_ruflo-core_ruflo__*标识符执行步骤validate-plugin 技能 “Steps” 一节先读plugin.json断言无三大数组再 Globskills/*/SKILL.md、commands/*.md、agents/*.md逐个校验 frontmatter随后逐技能检查必填字段与通配符最后逐 Agent 检查 frontmatter并输出每项检查的 pass/fail 与可操作的修复建议。5.1 plugin.json schema 详解create-plugin 技能 的 “Plugin.json schema” 一节给出了字段分级必填namekebab-case 插件标识、description功能描述、versionsemver 版本号推荐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——本插件会产生的关系类型。仓库中 ruflo-plugin-creator 自身的 plugin.json 是上述 schema 的完整范例name: ruflo-plugin-creator、version: 0.2.1、author指向 ruvnet、license: MIT以及keywords数组含mcp、scaffolding、contract-bootstrap——这三个关键词正是 smoke.sh 第 1 项检查 要求存在的。六、测试与验证claude --plugin-dir与 smoke 契约6.1 本地加载测试Agent 文档给出的测试命令是claude --plugin-dir ./plugins/name通过--plugin-dir指向插件根目录即可在 Claude Code 中本地加载未发布的插件进行验证。/create-plugin命令create-plugin.md的第 4 步也提示用户“如何用claude --plugin-dir ./plugins/name测试”。6.2 smoke.sh契约即测试ruflo 插件家族的验证哲学是“smoke as contract”——冒烟脚本就是插件契约的权威定义。ADR-00010001-plugin-creator-contract.md为 ruflo-plugin-creator 自身定义了 10 项检查smoke.sh 将其逐条实现#检查内容源码位置1plugin.json 声明0.2.1且含mcp、scaffolding、contract-bootstrap关键词smoke.sh L10-L182create-plugin/validate-plugin两个技能、agent、command 均存在且 frontmatter 合法smoke.sh L20-L313create-plugin技能会脚手架 ADR、smoke、README 契约段落smoke.sh L33-L404create-plugin技能包含 MCP-tool 漂移警告smoke.sh L42-L495create-plugin不再声称 “19 AgentDB controllers”回归检查smoke.sh L51-L576README 将 CLI 锁定到claude-flow/cliv3.6smoke.sh L59-L617README 含 Architecture Decisions 章节smoke.sh L63-L658ADR-0001 存在且状态为Acceptedsmoke.sh L67-L709validate-plugin技能存在smoke.sh L72-L7310技能中无通配符工具授权smoke.sh L75-L80运行方式与预期输出bash plugins/ruflo-plugin-creator/scripts/smoke.sh # Expected: 10 passed, 0 failed脚本通过grep断言版本号、关键词、文件存在性与 frontmatter 字段并以PASS/FAIL计数FAIL非零时以退出码 1 结束——任何一项检查失败都意味着插件契约被破坏不得发布。对新脚手架出的插件契约要求 smoke.sh 至少包含8 项结构检查版本与关键词、skills/agents/commands 的存在性与 frontmatter、README 中的 v3.6 锁定、namespace 协调块、ADR 存在且状态为Proposed、技能无通配符工具。七、发布与市场登记Agent 文档职责 5 是“Update marketplace by adding new plugins to marketplace.json”。完整发布链路为create-plugin 技能 第 11 步与 README本地加载验证claude --plugin-dir ./plugins/name运行bash plugins/name/scripts/smoke.sh通过契约检查若加入 ruflo 市场将插件登记到marketplace.json用户侧安装方式ruflo-plugin-creator README/plugin marketplace add ruvnet/ruflo /plugin install ruflo-plugin-creatorruflo同时新插件的 README 必须包含四个契约段落由脚手架默认生成Compatibility—— 锁定claude-flow/cliv3.6 majorminorv3.6 内的 patch 升级视为 no-opNamespace coordination—— 认领一个 kebab-case 的plugin-stem-intentnamespace并遵循 ruflo-agentdb 的 namespace 约定Verification—— 提供bash plugins/name/scripts/smoke.sh验证命令Architecture Decisions—— 链接到本插件的 ADR-0001。八、记忆学习与神经学习沉淀插件开发模式Agent 文档的收尾部分给出了两条“学习回路”把插件开发经验转化为可检索的知识资产。8.1 Memory Learning记忆学习在完成任务后把成功的插件结构模式存入 ruflo 记忆供模板迭代复用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第一条命令把“某类型插件的结构与配置”写入plugin-patternsnamespace第二条通过语义检索在同类任务中召回历史模式。从 ruflo-agentdb README 的命名约定看plugin-patterns遵循plugin-stem-intent的 kebab-case 规范且memory_*家族工具按 namespace 路由——这里传入--namespace plugin-patterns是正确用法。8.2 Neural Learning神经学习任务完成后将成功模式送入神经训练管线并回查历史规律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 patternshooks post-task --train-neural会触发agentdb_pattern-storeReasoningBank写入——按照 ruflo-agentdb 的钩子集成约定见 ruflo-agentdb README 的 Hook integration convention该写入落到保留的patternnamespace若 controller 注册表不可用则经memory-store-fallback回退到memory_store响应中的controller: memory-store-fallback表示数据已持久化而非错误。第二条memory search --namespace patterns检索的是patterns复数——这正是前述“单复数陷阱”的现场训练写入走pattern检索语料走patterns二者并存且不同。8.3 底层支撑可用的记忆与智能基础设施这两条学习回路并非空壳ruflo 家族提供了完整的底层支撑。memory store/memory search由memory_*MCP 工具族实现默认 namespace 为default另有claude-memories等保留 namespace由 Claude Code 自动记忆桥在SessionStart/SessionEnd时自动填充神经训练路径涉及 SONA 模式蒸馏与hooks_*钩子系统。对于想要深入底层路由语义的插件作者可以# 查看控制器实时注册表真实的 controller 列表 mcp tool call agentdb_controllers --json # 查看当前桥接状态 mcp tool call memory_bridge_status --json九、从零到一的完整流程串讲把本文各章节串起来一个插件从无到有的完整生命周期是对话收集需求/create-plugin命令询问插件名、描述、期望的 skills/commands/agentscreate-plugin.md冲突检查调用transfer_plugin-search确认插件名未被占用脚手架生成create-plugin技能按 canonical contract 生成完整目录——.claude-plugin/plugin.json、skills/、commands/、agents/、docs/adrs/0001-name-contract.mdProposed、scripts/smoke.sh≥8 项检查、README 四段落MCP 接线按工具族清单填写各 SKILL.md 的allowed-tools内置四类漂移警告防止踩坑本地测试claude --plugin-dir ./plugins/name加载验证契约验证validate-plugin技能跑 10 项结构检查bash plugins/name/scripts/smoke.sh跑冒烟契约发布登记写入marketplace.json用户经/plugin marketplace add/plugin install安装经验沉淀memory store保存结构模式hooks post-task --train-neural训练神经模式。这套流程的价值在于每个新插件出生即带完整契约ADR smoke 兼容性说明 namespace 协调而非事后修补——这正是 ADR-0001 所定义的“scaffold-the-canonical-contract”原则的直接体现。十、快速参考核心文件索引用途仓库路径插件开发专家 Agent 定义plugins/ruflo-plugin-creator/agents/plugin-developer.md交互式脚手架命令plugins/ruflo-plugin-creator/commands/create-plugin.md脚手架技能含漂移警告与 schemaplugins/ruflo-plugin-creator/skills/create-plugin/SKILL.md验证技能10 项检查plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md插件契约 ADRplugins/ruflo-plugin-creator/docs/adrs/0001-plugin-creator-contract.md冒烟契约脚本plugins/ruflo-plugin-creator/scripts/smoke.sh插件清单示例plugins/ruflo-plugin-creator/.claude-plugin/plugin.jsonnamespace 约定与控制器注册表plugins/ruflo-agentdb/README.md【免费下载链接】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），仅供参考