ruflo /create-plugin 命令实战指南：交互式脚手架一个符合契约的 Claude Code 插件

ruflo /create-plugin 命令实战指南交互式脚手架一个符合契约的 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/ruflocreate-plugin是 ruflo-plugin-creator 元插件提供的交互式命令用于从零生成一个结构完整、符合 ruflo 家族规范插件契约canonical plugin contract的 Claude Code 插件——包括plugin.json、skills、commands、agents、ADR-0001、smoke 脚本与 README 契约章节并自动完成 MCP 工具接线与已知坑位drift告警。读完本文你将掌握一条可复制的流水线交互采集需求 → 脚手架生成 → 契约校验 → 本地加载验证让新插件从诞生起就继承 ruflo 全家族统一的格式与质量基线而不是事后返工修补。一、命令定位它解决什么问题在 ruflo 仓库中插件是一等公民。plugins/目录下聚集了ruflo-agentdb、ruflo-cost-tracker、ruflo-knowledge-graph、ruflo-observability等大量插件每个插件都要遵守.claude-plugin/plugin.json的 schema、skills/name/SKILL.md的前置元数据frontmatter、MCP 工具的命名与参数约定。ruflo-plugin-creator 正是为此而生的元插件meta-plugin它的产物是别的插件因此它自身的质量直接决定了未来所有新插件的质量。这一点在其架构决策 ADR-0001plugin-creator-contract 中说得非常直白每个由该脚手架生成的新插件都会继承脚手架产出的契约所以 ADR-0001 必须同时做两件事——自身采用与家族其他插件相同的契约pinning、namespace 协调、smoke-as-contract并更新脚手架输出让新插件生来就带契约而不是事后补丁。create-plugin命令就位于该插件的 commands/create-plugin.md插件本体还包含create-plugin、validate-plugin两个 skill 和plugin-developer一个 agent见 plugin.json 的目录结构与 README.md。二、安装方式在 Claude Code 中通过 marketplace 安装该插件README.md/plugin marketplace add ruvnet/ruflo /plugin install ruflo-plugin-creatorruflo仓库根目录的 .claude-plugin/marketplace.json 维护着 marketplace 的分发清单新插件若要进入 ruflo marketplace需要在脚手架流程的最后一步同步更新它。三、核心工作流四步走原命令文档定义了完整的交互式创建流程下面按步骤展开并补充可执行的验证依据。步骤 1采集用户需求先向用户询问以下信息命令定义见 commands/create-plugin.md插件名称plugin name插件描述description期望包含的 skills期望包含的 commands期望包含的 agents步骤 2调用 create-plugin skill 生成完整目录结构create-pluginskillskills/create-plugin/SKILL.md是真正干活的引擎。其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。注意这里没有通配符授权这正是契约的一部分。生成动作包括冲突检查——调用mcp__plugin_ruflo-core_ruflo__transfer_plugin-search确认插件名未被占用创建目录结构详见第四节生成 plugin.jsonschema 详见第五节生成 SKILL.md带name、description、allowed-tools前置元数据生成 command 文件带name、description前置元数据生成 agent 文件带name、description与model: sonnet生成 README.md包含安装说明、功能、命令、skills以及契约四章节Compatibility钉住claude-flow/cliv3.6 大小版本、Namespace coordination声明 kebab-case 命名空间、Verification、Architecture Decisions生成 ADR-0001Proposed 状态记录 pinning、namespace 协调、MCP 工具面数量、smoke 契约范围生成 scripts/smoke.sh至少 8 项结构检查如需进入 ruflo marketplace更新 marketplace.json。步骤 3运行 validate-plugin skill 验证脚手架完成后validate-pluginskillskills/validate-plugin/SKILL.md负责对产物做 10 项结构检查具体清单见第六节。该 skill 的allowed-tools为mcp__plugin_ruflo-core_ruflo__transfer_plugin-info、Bash、Read、Glob、Grep同样遵循最小授权原则。步骤 4展示产物并本地测试向用户展示创建了什么并说明如何在 Claude Code 中本地加载测试claude --plugin-dir ./plugins/name这一步让开发者在不发布到 marketplace 的情况下先以本地插件目录方式验证行为是否符合预期。四、脚手架产出的目录结构规范插件契约create-pluginskill 生成的目录严格遵循 ruflo 家族通过各自 ADR-0001 沉淀下来的规范契约SKILL.mdplugins/name/ ├── .claude-plugin/ │ └── plugin.json # name、description、version、keywords不含 skills/commands/agents 数组 ├── skills/ │ └── skill-name/ │ └── SKILL.md # name description allowed-tools禁止通配符 ├── commands/ │ └── command-name.md # name description 分发逻辑 ├── agents/ │ └── agent-name.md # name description model ├── docs/ │ └── adrs/ │ └── 0001-name-contract.md # 插件级 ADR状态 Proposed ├── scripts/ │ └── smoke.sh # 结构契约至少 8 项检查 └── README.md # Compatibility Namespace coordination Verification ADR 章节几个关键规则值得强调skills 必须是目录格式skills/name/SKILL.md不是扁平文件见 agents/plugin-developer.md禁止把 skills/commands/agents 放进.claude-plugin/内agent 文件统一使用model: sonnet每个 SKILL.md 必须声明allowed-tools列出其实际使用的 MCP 工具。五、plugin.json schema 详解create-plugin SKILL.md 给出了完整的 schema 说明与 ruflo-plugin-creator 自身 plugin.json 互为印证后者即 v0.2.1、keywords 含mcp、scaffolding、contract-bootstrap必填字段字段说明name插件标识符kebab-casedescription插件功能描述versionsemver 版本号推荐字段author— 形如{ name: ..., url: ... }homepage、license、keywords可选字段graph_adapter— ADR-130 图智能契约生成时默认注释掉// graph_adapter: { // edgeRelations: [my-relation-type], // nodeTypes: [entity], // autoRegister: true // }当autoRegister: true时插件的边会被核心图graph层自动纳入graph_edges写入edgeRelations声明该插件会产生的边关系类型。最容易踩的坑plugin.json中严禁包含skills、commands、agents数组。Claude Code 会从目录结构自动发现这三类资产写入数组反而会导致校验失败——这正是 validate-plugin 检查点 6 专门盯防的遗留数组错误validate-plugin SKILL.md。六、validate-plugin 的 10 项检查清单发布前务必用validate-pluginskill 校验validate-plugin SKILL.md它逐项报告 pass/fail 并给出可操作的修复建议目录结构——插件根目录存在.claude-plugin/plugin.jsonplugin.json schema——必填字段name、description、version齐全Skills 自动发现——每个skills/name/SKILL.md是合法 skill自动发现plugin.json 不得声明skills数组Commands 自动发现——每个commands/name.md是合法 commandAgents 自动发现——每个agents/name.md是合法 agent无遗留数组——plugin.json 中出现skills/commands/agents数组即校验错误会导致 Claude Code 拒绝该插件SKILL.md 前置元数据——每个 skill 具备name、description、allowed-tools无通配符Agent 前置元数据——每个 agent 具备name、description、model文件位置正确——skills/commands/agents 不在.claude-plugin/内MCP 工具引用——allowed-tools中的工具是合法的mcp__plugin_ruflo-core_ruflo__*标识符。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 ---七、MCP 工具接线与避坑指南drift warnings脚手架会在生成的 skill 模板中内置一份MCP-tool drift to avoid告警段这是 ruflo 家族多个插件修复真实 bug 后沉淀的教训ADR-0001、create-plugin SKILL.md易犯错误正确做法把embeddings_embed当工具引用真实工具是embeddings_generate_embed这个名字不存在向agentdb_hierarchical-*传namespace参数它按tierworking/episodic/semantic路由应传tier需要命名空间读写请改用memory_*向agentdb_pattern-*传namespace参数不要传——它经 ReasoningBank 路由回退写入保留的pattern命名空间混淆pattern单数与patterns复数它们是不同的保留命名空间ReasoningBank 回退写patternhooks_pretrain写patterns硬编码19 个 AgentDB 控制器以agentdb_controllers运行时清单为准真实数量会变化约 15 个 MCP 工具、29 个控制器名可接线的 MCP 工具大类create-plugin SKILL.mdmemory_*— 存储、搜索、检索agentdb_*— 15 个控制器桥接工具不要传namespace参数neural_*— 神经训练与预测hooks_*— 生命周期钩子与智能browser_*— 浏览器自动化workflow_*— 工作流管理aidefence_*— 安全扫描embeddings_*— 10 个向量嵌入工具用embeddings_generate不是embeddings_embed。浏览可用工具调用mcp__plugin_ruflo-core_ruflo__transfer_plugin-info。八、smoke-as-contractscripts/smoke.sh 是质量的最终闸门脚手架生成的scripts/smoke.sh不只是测试脚本它就是契约本身smoke as contract。ruflo-plugin-creator 自身的 scripts/smoke.sh 是 10 项结构检查的权威范例核心检查点包括plugin.json 声明正确的 semver 版本且包含新 keywordsmcp、scaffolding、contract-bootstrap两个 skill agent command 齐全且 frontmatter 合法create-plugin skill 会脚手架 ADR、smoke、README 契约章节create-plugin skill 包含 MCP-tool drift 告警create-plugin skill 不再声称19 个 AgentDB 控制器回归检查防陈旧数字回潮README 钉住claude-flow/cliv3.6README 含 Architecture Decisions 章节ADR-0001 存在且状态为Proposed插件自身为Acceptedvalidate-plugin skill 存在无任何 skill 授予通配符工具权限。在插件根目录下运行bash plugins/name/scripts/smoke.sh # 预期输出类似10 passed, 0 failed对应到本插件自身README.mdbash plugins/ruflo-plugin-creator/scripts/smoke.sh九、配套的 plugin-developer agent 与记忆沉淀脚手架产物中的plugin-developeragentagents/plugin-developer.md承担插件开发专员的职责脚手架结构、编写 SKILL.md、接线 MCP 工具、按官方格式校验、更新 marketplace。它还内置了两条学习闭环Memory Learning把成功的插件模式存入记忆便于后续模板改进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-patternsNeural 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 patterns十、写在最后/create-plugin的价值不在于生成几个文件而在于把 ruflo 家族用多次返工换来的契约与教训固化进脚手架ADR-0001 保证每个新插件生来就有架构决策记录scripts/smoke.sh作为契约闸门让结构问题无法蒙混过关MCP-drift 告警段把embeddings_embed、namespace误传等真实 bug 消灭在源头。从采集需求到claude --plugin-dir ./plugins/name本地验证一条流水线即可产出符合家族标准的插件——这正是脚手架即契约scaffold-the-canonical-contract的工程价值所在。参考资源命令定义create-plugin skillvalidate-plugin skillADR-0001 插件契约smoke.sh 契约脚本plugin-developer agentruflo-plugin-creator README插件自身 plugin.jsonmarketplace 分发清单【免费下载链接】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），仅供参考