SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场marketplace-audit

marketplace-audit

测试与质量

查看项目

更新于 10-15 09:52

技能介绍

用途

marketplace-audit 用于对任意 Claude Code 插件市场执行全面的结构校验。它适用于遵循标准布局的项目，即 .claude-plugin/marketplace.json 加上 plugins/<name>/ 目录结构。该技能建议在任何修改插件文件或 marketplace.json 的提交之前主动运行。

主要能力

审计脚本会检查以下内容：

  • 文件存在性：marketplace.json 中 agents、skills、commands 数组里的每个路径都能解析到真实文件或目录。
  • 孤立文件：磁盘上存在但未在任何插件中注册的 agent .md 文件、skill 目录或 command .md 文件。
  • Frontmatter 校验：agents 必须包含 name、description、model、color；skills 必须包含 name、description；commands 必须包含 description。
  • 颜色一致性与和谐度：同一插件内的所有 agents 应使用相同颜色；单一颜色在过多插件中过度使用时发出警告（阈值可配置）；报告所有插件的颜色分布。有效颜色为 red、blue、green、yellow、purple、orange、pink、cyan。使用 --fix 可自动修正无效或缺失的颜色。
  • 命名规范：所有名称使用 kebab-case；agent 文件名与 frontmatter 的 name 字段一致；插件目录名与 marketplace.json 的 name 字段一致；skill 目录名与 frontmatter 的 name 字段一致；工作流命令输出目录与命令文件名匹配（例如 feature-e2e.md 通常写入 .feature-e2e/）；不同插件中的命令之间无命名冲突；任何位置都不出现 em dash 字符（应使用连字符 - 或双连字符 --）。
  • 交叉引用一致性（项目特定，尽力而为）：若配置了 git remote，建议市场名称与仓库名对齐（仅警告）；若项目根目录存在 CLAUDE.md，建议其项目标题与市场名称匹配（仅警告）。这些为建议性质，不同维护者有不同约定。
  • marketplace.json 模式：每个插件都有 name、source、description、version、author、license、keywords、category、strict；无重复插件名；跨插件重复 keywords（仅警告，可能是有意为之）。
  • 版本合理性：所有版本为合法 semver（MAJOR.MINOR.PATCH）；根级存在 metadata.version。
  • 依赖解析与无环性：未限定的 dependencies 条目必须指向本市场中的插件；跨市场条目必须使用限定形式 name@marketplace，仅检查其形状，因为从本地无法解析。裸名称会静默解析到本地市场并导致整个插件加载失败，因此限定形式是强制要求而非风格问题。硬依赖图必须无环。可选依赖被有意排除在环遍历之外，因为它们正是用来表达否则会闭环的边。外部市场以 info 形式报告，按需要它们的插件分组。
  • 文档计数漂移：docs/README.md 索引表和 README.md 插件表中按插件重述的 agent、skill、command 数量必须与 marketplace.json 声明一致。命名了未注册插件的行，以及已注册插件在已列出其他插件的表中缺失，都会被标记。README.md、docs/README.md、CLAUDE.md 和 marketplace metadata.description 中的 Every N plugins 短语必须与真实插件数量匹配。这是捕获最常见静默衰减的检查：增删一个文件会让所有统计它的表过期，而其他检查不会失败。当文件或表缺失时，每个子检查会被跳过，因此对不同文档布局的市场仍然有效。

使用方式

第一步：运行校验脚本。仅校验：

python "${CLAUDE_PLUGIN_ROOT}/skills/marketplace-audit/scripts/audit_marketplace.py"

校验并自动修复颜色问题（无效、缺失、不和谐）：

python "${CLAUDE_PLUGIN_ROOT}/skills/marketplace-audit/scripts/audit_marketplace.py" --fix

脚本通过从脚本位置向上查找来解析目标项目根目录，或者当从与插件安装位置不同的市场调用时，遵循 --project-root <path> 标志。

第二步：审查发现的问题。

第三步：按严重程度修复问题：

  • CRITICAL：缺失被引用的文件、损坏的路径、缺失必需的 frontmatter 字段、重复插件名。
  • WARNING：孤立文件、命名不匹配、重叠 keywords、颜色不一致、git/CLAUDE.md 对齐。
  • INFO：改进建议、合并机会。

第四步：评估颜色和谐度。脚本通过后，审查颜色分布并评估语义和谐度：读取每个插件的 description 和 category；考虑领域，相似领域应有视觉相关的颜色，不同领域应形成对比。指导原则：暖色（red、orange、yellow、pink）用于创意/对外插件；冷色（blue、cyan、purple）用于分析/开发插件；中性色（green）用于工具/基础设施。若颜色感觉不和谐，提出新的分配方案并说明理由，经用户确认后应用。

第五步：重新校验。修复后再次运行脚本以确认审计干净。

适用场景

适用于维护 Claude Code 插件市场的项目，尤其是遵循标准 .claude-plugin/marketplace.json 加 plugins/<name>/ 布局的市场。在提交任何修改插件文件或 marketplace.json 之前使用。

限制

该技能与市场无关，假设标准 Claude Code 插件布局，但不假设哪些插件、作者或上游来源特定于你的市场。插件类别、默认作者、上游来源及任何项目特定约定应记录在项目根目录的 CLAUDE.md 中。脚本和本技能尊重这些约定，但不强制特定分类法。

来源配置预检：在运行本流程前需加载 marketplace-ops:kernel-marketplace。从清单和说明中检测目标的来源模型。对于 daodan/v1 中性内核，遵循该技能的操作特定流程并在那里结束。生成的导出和目录条目作为输出检查，绝不作为源编写。以下流程仅适用于具有手工编写的 agents/ 和 commands/ 的旧式 Claude 市场，不得应用于中性内核检出。