ruflo 插件验证指南用 validate-plugin Skill 校验 Claude Code 插件结构、Frontmatter 与 MCP 工具引用【免费下载链接】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 仓库中 validate-plugin Skill 展开它用于在发布前校验一个 Claude Code 插件是否满足规范的结构、frontmatter 与 MCP 工具引用要求。读完本文你将掌握 10 项核心校验点的判定标准、逐项执行的实操步骤以及如何借助仓库内的 smoke 脚本与全仓审计脚本把校验固化为可重复的自动化契约。validate-plugin 是什么发布前的最后一道关卡在 ruflo 的插件体系中每个插件由.claude-plugin/plugin.json、skills/name/SKILL.md、commands/name.md、agents/name.md等部分组成。Claude Code 会按目录约定自动发现这些文件但结构、frontmatter 或工具引用一旦出错插件可能直接被拒绝加载或在使用时静默失效。validate-plugin正是为此设计的校验 Skill在创建或修改插件之后、发布之前运行它尽早发现结构性问题。它通过allowed-tools声明仅依赖 Bash、Read、Glob、Grep 以及mcp__plugin_ruflo-core_ruflo__transfer_plugin-info工具即可完成对目标插件目录的全面体检。从仓库结构看它和 create-plugin 是一对互补流程create-plugin负责按规范脚手架出插件validate-plugin负责复核产物是否符合规范。create-plugin 命令 的工作流也明确要求使用create-pluginskill 脚手架后运行validate-pluginskill 验证正确性最后再以claude --plugin-dir ./plugins/name做本地测试。十项校验点完整判定标准validate-plugin的核心是 10 项结构性与一致性检查覆盖目录、schema、自动发现、frontmatter 和 MCP 引用五个维度。逐条判定标准如下#检查项判定标准1目录结构插件根目录必须存在.claude-plugin/plugin.json2plugin.json schemaname、description、version三个必填字段齐全3Skills 自动发现每个skills/name/SKILL.md都是合法 skillplugin.json禁止声明skills数组4Commands 自动发现每个commands/name.md都是合法 commandplugin.json无commands数组5Agents 自动发现每个agents/name.md都是合法 agentplugin.json无agents数组6禁用遗留数组plugin.json中出现skills、commands或agents数组即校验失败会导致 Claude Code 拒绝该插件7SKILL.md frontmatter每个 skill 具备name、description、allowed-tools且allowed-tools不得使用通配符8Agent frontmatter每个 agent 具备name、description、model9文件位置skills/commands/agents 不得位于.claude-plugin/目录内10MCP 工具引用allowed-tools中的工具必须是合法的mcp__plugin_ruflo-core_ruflo__*标识符其中第 36 项是新手最容易踩坑的地方Claude Code 的自动发现机制意味着plugin.json里多余的声明数组反而是错误。仓库中实际存在的插件 manifest 印证了这一约定——例如 ruflo-plugin-creator 自身的 plugin.json 和 ruflo-agentdb 的 plugin.json 都只含name、description、version、author、homepage、license、keywords字段没有任何skills/commands/agents数组。执行步骤从读取 manifest 到输出修复建议SKILL 文档给出了五步执行流程读取plugin.json并断言无skills/commands/agents数组——这是自动发现契约的根基任何残留数组都应立即报错。Glob 扫描skills/*/SKILL.md、commands/*.md、agents/*.md逐文件校验 frontmatter。对每个 SKILL.md确认必填字段齐全且allowed-tools不含通配符。对每个 agent .md确认必填字段齐全name、description、model。逐项输出 pass/fail 报告并对失败项给出可执行的修复建议。关于 allowed-tools 通配符的深层原因第 7 项禁止allowed-tools: *并非形式主义而是一条安全边界。仓库根目录下的全仓审计脚本 audit-skill-frontmatter.mjs 对此有明确注释allowed-tools字段的存在是安全要求——不允许隐式授予全部工具security — no implicit all tools。该脚本还额外做了一条 SKILL 文档未提及的漂移检查frontmatter 中的name值必须与所在目录名一致name matches directory防止 skill 被移动或改名后出现目录与声明不符的情况。从源码结构可以推断这个全仓审计与 validate-plugin 是分层防御单个插件的 smoke 脚本负责捕获自身 skills的问题而audit-skill-frontmatter.mjs捕获的是逃逸出单插件覆盖的违规——例如新插件没有 smoke 契约、在已有插件里新增 skill 后忘记补检查、或 smoke 编写后被删除了必填字段。它的 CLI 用法如下node scripts/audit-skill-frontmatter.mjs # 扫描全部 skills node scripts/audit-skill-frontmatter.mjs --format json # 输出机器可读 JSON node scripts/audit-skill-frontmatter.mjs --only ruflo-cost-tracker # 只查单个插件退出码约定0无违规、1存在违规、2扫描出错找不到 plugins 目录。MCP 工具引用的合法性判定第 10 项要求allowed-tools中的工具必须是mcp__plugin_ruflo-core_ruflo__*前缀的合法标识符。校验时除了前缀匹配还应结合 ruflo 家族踩过的真实坑检查工具名是否真实存在embeddings_embed不存在真实工具是embeddings_generate参见 create-plugin skill 的 drift 警告ruflo-knowledge-graph、ruflo-market-data 曾因此修复。agentdb_hierarchical-*不按 namespace 路由而是按 tierworking|episodic|semantic路由带 namespace 的读写应使用memory_*。agentdb_pattern-*不按 namespace 路由而是经由 ReasoningBank 路由传namespace参数无效fallback 写入保留的pattern命名空间。pattern单数与patterns复数是两个不同的保留命名空间不可混用。不要硬编码19 个 AgentDB 控制器——真实数量以agentdb_controllers运行时为准约 15 个agentdb_*MCP 工具、29 个控制器名ruflo-agentdb 的 plugin.json 中即声明了15 agentdb_* MCP tools。这些 drift 警告同时被 ADR-0001 插件契约 记录为脚手架产物的一部分也就是说用 create-plugin 新生成的插件会自带这些警告而 validate-plugin 负责确认已有插件没有踩中它们。把校验固化为自动化smoke.sh 与契约思想validate-pluginSkill 是人工/交互式校验的入口而仓库把它进一步固化为可重复执行的脚本契约。运行 smoke.shbash plugins/ruflo-plugin-creator/scripts/smoke.sh # 期望输出: 10 passed, 0 failed从脚本源码看它用set -u严格模式执行 10 项检查逐条step输出PASS/FAIL并统计FAIL非零时以退出码 1 结束。10 项检查中与 validate-plugin 直接呼应的有plugin.json声明正确版本0.2.1且包含mcp、scaffolding、contract-bootstrap关键词两个 skill agent command 存在且 frontmatter 含name:/description:/allowed-tools:create-pluginskill 会脚手架出 ADR、smoke、README 契约段create-pluginskill 包含 MCP-tool drift 警告embeddings_embed、agentdb_hierarchical、agentdb_pattern、单复数 pattern回归检查create-plugin不再声称19 个 AgentDB 控制器README 将 CLI 锁定在claude-flow/cliv3.6majorminorREADME 含 Architecture Decisions 章节ADR-0001 存在且状态为Acceptedvalidate-pluginskill 存在没有任何 skill 授予通配符工具权限。这套smoke 即契约smoke-as-contract的思想在 ADR-0001 中被正式确立每一个新脚手架出的插件都应自带docs/adrs/0001-name-contract.md、scripts/smoke.sh至少 8 项结构检查、README 的 Compatibility / Namespace coordination / Verification / Architecture Decisions 四个契约段。validate-plugin 因此成为整个插件生产流水线的质量闸门——先由 create-plugin 生成再由 validate-plugin 复核最后以 smoke.sh 形成可回归的自动化防线。典型失败模式与修复建议结合仓库中的契约约束与历史修复记录运行 validate-plugin 时最可能遇到的失败及修复方向如下失败现象原因修复建议plugin.json 含 skills/commands/agents 数组误解了自动发现机制删除数组确认文件按skills/name/SKILL.md等目录约定放置SKILL.md 缺 frontmatter 字段手写文件遗漏补齐name/description/allowed-tools三件套allowed-tools: *偷懒授予全部工具显式列出用到的mcp__plugin_ruflo-core_ruflo__*工具与 Bash 等基础工具agent 缺model字段复用 skill 模板写 agent补充model: sonnet参见 plugin-developer agentskills/commands/agents 放进.claude-plugin/目录规划错误移到插件根目录下与.claude-plugin/平级引用了不存在的 MCP 工具命名漂移如embeddings_embed对照 ruflo-core MCP 工具清单修正优先embeddings_generate修复后建议在发布前跑一遍 smoke 契约确认无回归bash plugins/ruflo-plugin-creator/scripts/smoke.sh总结validate-plugin用 10 项结构化检查覆盖了 Claude Code 插件的目录结构、plugin.jsonschema、自动发现契约、frontmatter 完整性与 MCP 工具引用合法性是 ruflo 插件从能跑到可发布之间的必经关卡。它与 create-plugin 组成脚手架—校验闭环与 smoke.sh 及 audit-skill-frontmatter.mjs 构成单插件—全仓的分层防线最终通过 ADR-0001 将整套契约固化进每个新插件的出生模板——这也是 ruflo 插件家族能保持结构一致性与低漂移率的关键机制。【免费下载链接】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），仅供参考