marketplace-dev

marketplace-dev

将 Claude Code 技能仓库转换为官方插件市场，让用户可以通过 claude plugin marketplace add 安装技能并自动更新。

输入：包含 skills/ 目录和 SKILL.md 文件的仓库。 输出：.claude-plugin/marketplace.json + 已验证 + 已通过安装测试 + 可直接提交 PR。

编辑前先判断任务应走的流程

用户意图	流程
为尚未支持市场的仓库创建市场支持	按照下方阶段 0–4 操作
添加或更新普通插件条目	按照“维护现有市场”操作，然后执行阶段 3
将独立技能整合为套件、基于现有技能创建套件、在套件之间移动技能，或在移动技能时重命名技能	完整阅读 references/suite_consolidation_workflow.md，并按其中流程操作，而非遵循通用阶段 4 的限制
合并套件迁移后协调已安装的缓存	调用 daymade-skill:skill-governance 并使用其迁移后工作流；不要在此处修改缓存状态
审查整个仓库的代码、文档、安全、PR、议题和清单完整性	仅当用户要求进行全面健康检查时，调用 marketplace-health-check:marketplace-health-check；针对性套件迁移不需要此步骤

阶段 0：证据收集

编辑现有市场之前，应收集证据，而非依赖默认模板：

1. 阅读当前的 .claude-plugin/marketplace.json。
2. 阅读此仓库的市场规则（CLAUDE.md、README 安装部分、变更日志）。
3. 阅读有关市场和插件路径语义的官方文档。
4. 将当前对话作为证据。仅当用户明确要求或批准使用这一私人来源时，才查阅之前本地 Claude Code 会话。

获准使用会话历史后，各项目的会话位于：

• 顶层文件：<session-id>.jsonl
• 子代理记录：<session-id>/subagents/agent-*.jsonl

实用的搜索模式（根据要排查的问题调整关键词）：

grep -lc "marketplace.json\|claude plugin validate\|claude plugin install" \
  ~/.claude/projects/<escaped-cwd>/*.jsonl
grep -lc "Unrecognized key\|Plugin not found\|No manifest found\|Duplicate plugin" \
  ~/.claude/projects/<escaped-cwd>/*.jsonl \
  ~/.claude/projects/<escaped-cwd>/*/subagents/*.jsonl

将经验提炼为有证据支持的规则：尝试过的命令、观察到的输出、根本原因、最终可用的命令或配置。不要将凭记忆猜测的内容写入规则。

阶段 1：分析目标仓库

步骤 1：发现所有技能

# Find every SKILL.md
find <repo-path>/skills -name "SKILL.md" -type f 2>/dev/null

对于每项技能，从 SKILL.md 的 frontmatter 中提取：

• name — 技能标识符
• description — 原始文本，切勿改写或翻译

步骤 2：读取仓库元数据

• VERSION 文件（如果存在）— 将作为 metadata.version
• README.md — 了解项目、作者信息和类别
• LICENSE — 记录许可证类型
• Git 远程仓库 — 确定上游仓库与分支仓库（git remote -v）

步骤 3：确定类别

按功能对技能分组。类别可以是任意字符串。常见模式：

• business-diagnostics、content-creation、thinking-tools、utilities
• developer-tools、productivity、documentation、security

如果分组方式不明确，请用户确认类别。

步骤 4：选择插件边界

Claude Code 有三个不同的层级：

marketplace -> plugin -> skill

• 市场名称用于安装标识：plugin@marketplace。
• 插件名称是斜杠命名空间：/plugin-name:skill-name。
• 当技能路径指向一个直接包含 SKILL.md 的目录时，技能名称取自 SKILL.md frontmatter。

根据安装、更新和缓存需求选择各插件边界：

• 单技能插件：当技能需要独立安装、更新和回滚，并使用范围较小的缓存时采用。
• 套件插件：当相关技能需要共享一个命名空间和一条安装命令时采用，例如 /daymade-docs:mermaid-tools。

更改 source 或 skills 前，请阅读 references/cache_and_source_patterns.md，了解详细的来源和缓存模式及相关注意事项。

阶段 2：创建 marketplace.json

官方架构（请牢记）

阅读 references/marketplace_schema.md，了解完整的字段参考。 文档中不明显的关键规则：

1. $schema 字段会被 claude plugin validate 拒绝。请勿包含此字段。
2. 使用有效的 metadata 字段：description、version、pluginRoot。 metadata.homepage 不存在——验证器会静默接受，但它不在规范中。
3. metadata.version 是 marketplace 目录版本，而非单个插件的版本。 它应与仓库的 VERSION 文件一致（例如 "2.3.0"）。
4. 插件条目中的 version 是独立的。首次注册到 marketplace 时，请使用 "1.0.0"。
5. 仓库中没有 plugin.json 时，必须设置 strict: false。 设置 strict: false 后，marketplace 条目就是完整的插件定义。 同时存在 strict: false 和包含组件的 plugin.json 会导致加载失败。
6. source 定义已安装插件的根目录。对于单技能插件，将 source 直接指向技能目录（例如 "./tunnel-doctor"），并完全省略 skills。 对于套件插件，使用 source: "./<suite>"，并通过显式的 skills 数组列出子目录。 避免使用 source: "./"（会将整个仓库安装为缓存）和 skills: ["./"] （会被 Claude Code 2.1.x 的路径逃逸验证器拒绝）。
7. 保留的 marketplace 名称，不可使用：claude-code-marketplace、 claude-code-plugins、claude-plugins-official、anthropic-marketplace、 anthropic-plugins、agent-skills、knowledge-work-plugins、life-sciences。
8. tags 与 keywords：两者都是可选的。在当前 Claude Code 源码中， keywords 虽有定义，但从未用于搜索。tags 仅在值为 "community-managed" 时 影响 UI（显示标签）。两者都不会影响发现功能。 Discover 选项卡仅搜索 name、description 和 marketplaceName。 可添加 keywords 以便面向未来，但不必过度投入。

生成 marketplace.json

使用此模板，根据分析结果填写：

{
  "name": "<marketplace-name>",
  "owner": {
    "name": "<github-org-or-username>"
  },
  "metadata": {
    "description": "<one-line description of the marketplace>",
    "version": "<from-VERSION-file-or-1.0.0>"
  },
  "plugins": [
    {
      "name": "<skill-name>",
      "description": "<EXACT text from SKILL.md frontmatter, do NOT rewrite>",
      "source": "./<skill-name>",
      "strict": false,
      "version": "1.0.0",
      "category": "<category>",
      "keywords": ["<relevant>", "<keywords>"]
    }
  ]
}

为 marketplace 命名

name 字段是用户在安装命令中 @ 后输入的名称： claude plugin install dbs@<marketplace-name>

名称应符合以下要求：

• 简短且易记
• 使用 kebab-case（仅限小写字母和连字符）
• 与项目身份相关，而非泛泛的名称

描述规则

• 使用每个 SKILL.md frontmatter 中的原始描述
• 不要翻译、润色或“改进”描述
• 如果仓库面向中文用户，描述应保留为中文
• 如果是双语内容，使用 SKILL.md 描述字段中的第一种语言
• marketplace 层级的 metadata.description 可以是新的摘要

维护现有市场

本节适用于常规条目新增或元数据更新。对于套件整合、源位置迁移、套件成员转移或从独立条目迁移到套件，请使用路由表中链接的专用工作流；与常规条目新增相比，这些操作涉及更广泛的破坏性变更和文档调整。

向现有 marketplace.json 添加新插件时：

1. 递增 metadata.version — 这是市场目录版本。 遵循语义化版本规范：新增插件 = 次版本递增，破坏性变更 = 主版本递增。
2. 更新 metadata.description — 附加新技能的摘要。
3. 将新插件的 version 设为 "1.0.0" — 这是该插件首次进入市场。
4. 当现有插件的 SKILL.md 内容变更时，递增其 version。 Claude Code 使用版本检测更新 — 版本相同 = 跳过更新。 递增版本时，须在同一提交中添加 CHANGELOG 条目；没有任何机制会替你检查此项，而且只有 Pre-flight Checklist 中的这一项会要求添加该条目。
5. 当现有插件的 source 或 skills 发生变更时，递增其 version。 即使 SKILL.md 未变更，已安装缓存路径和组件解析也已发生变化。
6. 检查 metadata 是否包含无效字段 — metadata.homepage 是常见错误（规范中未定义，会被静默忽略）。如果发现，请将其移除。

向现有套件添加成员技能

向现有套件添加成员时，请同时更新以下内容：

1. 套件的 skills 数组在 marketplace.json 中列出新成员 （./skill-name）。如果磁盘上存在包含 SKILL.md 的成员目录，但它未列入数组， check_marketplace.py 就会失败。
2. metadata.version 必须严格递增。新成员会改变套件的 布局签名（source + skills）；如果布局发生变化，但 metadata 没有高于基准版本， check_version_progression.py 就会拒绝通过——上文规则 5（递增插件的 version）是必要条件，但并不足够。
3. README.md 和 README.zh-CN.md 都要新增一个 ### **skill-name** 详情 小节。check_doc_skill_lists.py 是必需的检查项；它会提取两个 README 中所有的 ### **name** 标题，如果 marketplace 中的技能缺失，就会失败（反向多出的项目则会 标记为 GHOST）。
4. 套件的调用列表（/suite:skill-name）要在两个 README 中都更新。

每个新文件也必须避免使用绝对用户路径（/Users/<name>/…）——PII 防护会阻止推送。请使用相对 ~/ 的路径，并通过重新运行实际检测器来验证，而不是只靠目测。

发布记录和审查请遵循 Skill Creator 的版本管理约定 以及发布就绪要求。 递增版本时，请一并添加 CHANGELOG 条目；结构检查通过并不代表发布已记录在案。

各检查器采用的基准不同，使用错误不代表检查结论：

命令	基准参数	使用错误时的结果
check_version_progression.py	--base <ref> --candidate HEAD（见下文）	退出码 2 — argparse 报错、没有暂存内容时拒绝 --candidate-index，或无法读取基准/清单
validate_changed_skills.sh	位置参数 <base-ref>（默认为 origin/main）	退出码 1，并打印 base ref '<x>' is unknown here
check_marketplace.py	无	不适用

因此，表示“我的调用方式有误”的代码因脚本而异：check_version_progression.py 的退出码为 2， validate_changed_skills.sh 的退出码为 1。这两种情况下，仓库都尚未经过评判——就像根本没有运行检查一样。 不要把任一退出码都解读为“检查器发现了问题”：这两个脚本中，validate_changed_skills.sh 的退出码 1 表示使用错误，而 check_version_progression.py 的退出码 1 则表示实际发现问题——这正是为什么 应该看打印的消息，而不是退出码。

post_edit_sync_check 钩子只会捕获“编辑了 SKILL.md，但没有递增插件版本”的情况。第 2–4 项没有钩子， CHANGELOG 条目也既没有钩子也没有检查器——请在本地运行 check_version_progression.py 和 check_doc_skill_lists.py，再推送，而不是等到 CI 轮次中才发现问题。传入 --base <base-ref> --candidate HEAD。脚本也接受 --candidate-index，该参数会从 git index 读取清单 blob，并且只比较已暂存的路径； 如果没有暂存内容，该 blob 就是 HEAD 中的副本，因此它会重新验证你已有的提交，并对从未看到的工作报告“无回归”。 这个绿色结果确实反映了索引状态，却对你的编辑保持沉默。

CI 中的版本门禁仅会在 PR head 发生变化时重新运行，并会在运行时将基准解析为 origin/$BASE_REF。因此，如果 PR 的基准分支后来已前进，PR 仍会保留它针对旧基准获得的绿色结果， 而其版本号相对于当前基准可能已经构成回归。合并前请针对当前的 origin/main 重新运行门禁，而不只是推送前运行；如果失败，请执行 rebase。

阶段 3：验证

步骤 1：一次性预检

运行随附的验证器。它会运行以下检查，并在任何必需检查失败时以非零状态码退出：

bash scripts/check_marketplace.sh          # validates current repo
bash scripts/check_marketplace.sh /path    # validates a target repo

检查内容：

#	检查	失败意味着
1	.claude-plugin/marketplace.json 的 JSON 语法	文件不是可解析的 JSON
2	claude plugin validate .（如果缺少 claude CLI，则跳过）	架构级拒绝（例如 Unrecognized key: "$schema"、名称重复）
3	解析每个插件条目的 source + skills	插件条目指向磁盘上不存在的 SKILL.md
4	反向同步（磁盘 → 清单）	仅警告：磁盘上的 SKILL.md 未在任何插件条目中注册

常见的架构错误及修复方法：

• Unrecognized key: "$schema" → 移除 $schema 字段
• Duplicate plugin name → 确保所有名称唯一
• Path contains ".." → 仅使用 ./ 相对路径
• 验证已安装的缓存路径时出现 No manifest found in directory → 验证市场清单或插件源，而不是 strict: false 缓存目录。

步骤 2：安装测试

# Add as local marketplace
claude plugin marketplace add .

# Install a plugin
claude plugin install <plugin-name>@<marketplace-name>

# Verify it appears
claude plugin list | grep <plugin-name>

# Check for updates (should say "already at latest")
claude plugin update <plugin-name>@<marketplace-name>

# Clean up
claude plugin uninstall <plugin-name>@<marketplace-name>
claude plugin marketplace remove <marketplace-name>

步骤 3：缓存占用检查

安装或更新后，检查实际缓存。这是确认 source 生成了预期快照的唯一方法：

PLUGIN=<plugin-name>
MARKET=<marketplace-name>
CACHE=$(jq -r --arg id "$PLUGIN@$MARKET" '.plugins[$id][0].installPath' ~/.claude/plugins/installed_plugins.json)
find "$CACHE" -maxdepth 1 -mindepth 1 -exec basename {} \; | sort

预期结果：

• 单技能插件缓存：包含 SKILL.md，以及适用时该技能自己的 scripts/、references/、assets/。
• 套件插件缓存：仅包含套件成员技能目录和套件范围内的资源。
• 如果出现无关的技能目录，说明 source 范围过宽。
• 如果缓存条目是符号链接，则插件不是自包含的；请使用规范的源目录，而不是符号链接集合。

步骤 4：GitHub 安装测试（如果已推送）

# Test from GitHub (requires the branch to be pushed)
claude plugin marketplace add <github-user>/<repo>
claude plugin install <plugin-name>@<marketplace-name>

# Verify
claude plugin list | grep <plugin-name>

# Clean up
claude plugin uninstall <plugin-name>@<marketplace-name>
claude plugin marketplace remove <marketplace-name>

预检清单（继续创建 PR 前必须通过）

每次更改 marketplace.json 后都要运行此清单。请勿跳过任何项目。

自动化检查

bash scripts/check_marketplace.sh

通过所有必需检查。将反向同步 WARN 视为重要信号：磁盘上未注册的 SKILL.md 几乎总是意外遗漏、忘记注册的技能，或应予移除的死代码。

元数据检查

阅读 marketplace.json 并确认以下内容：

• metadata.version 已从上一版本递增
• metadata.description 提及所有技能类别
• 不包含 metadata.homepage（不在规范中，会被静默忽略）
• 不包含 $schema 字段（验证器会拒绝）

每个插件的检查

对每个插件条目：

• description 与 SKILL.md 前置元数据中的内容完全一致（不得改写）
• 新插件的 version 为 "1.0.0"；有更改的插件则递增版本号
• source 直接指向技能目录（例如 "./skill-name"）
• 单技能插件省略 skills 字段（从 source 自动发现）
• 套件插件列出的 skills 路径相对于 source
• strict 为 false（仓库中没有 plugin.json）
• name 使用 kebab-case，且所有条目之间唯一
• 每个递增版本的插件都添加了 CHANGELOG 条目，箭头的起始/目标版本与该次递增一致——没有钩子或 CI 检查要求此项，因此这是最常被跳过的项目

最终验证

bash scripts/check_marketplace.sh

创建 PR 前必须打印 RESULT: PASSED。只有在你有意决定不注册某个 SKILL.md 时，WARN [4/4] 才可接受。

阶段 4：创建 PR

原则

• 仅在为上游仓库添加市场支持时，应用这些纯增量约束。经用户批准的套件整合必然会移动现有技能目录并更新仓库的安装文档；采用该方案时，请遵循专门的整合工作流。
• 纯增量（仅适用于新增市场方案）：不要修改现有技能文件；仅在需要展示新的安装路径时更新 README
• 压缩提交：避免迭代更改导致 git 历史中出现大量二进制文件
• 仅添加：.claude-plugin/marketplace.json，可选添加 scripts/，可选更新 README

README 更新（如适用）

在现有安装说明上方添加市场安装方式：

## Install

![demo](demo.gif)  

**Claude Code plugin marketplace (one-click install, auto-update):**

\`\`\`bash
claude plugin marketplace add <owner>/<repo>
claude plugin install <skill>@<marketplace-name>
\`\`\`

PR 描述模板

包括：

• 添加了哪些市场支持
• 合并后用户将使用的安装命令
• 设计决策（纯增量、原始描述等）
• 验证证据（claude plugin validate . 已通过）
• 测试计划（用于验证的安装命令）

捆绑钩子（可选，自动启用）

使用 hooks/ 下捆绑的 PostToolUse 钩子：

• hooks/post_edit_validate.sh — 每当写入或编辑 marketplace.json 文件时，运行 claude plugin validate。
• hooks/post_edit_sync_check.sh — 编辑 SKILL.md 时，如果 marketplace.json 中对应的插件条目未更新 version，则发出警告。

这两个钩子都在此插件自身的清单条目（plugins[].hooks）中声明，因此在 Claude Code 会话中启用该插件后，它们会自动激活。无需手动编辑 settings.json。如需禁用，可从用户已安装副本中的此插件条目移除 hooks 块，或使用 /plugin disable marketplace-dev（仅在启用该插件时生效）。

这些钩子是编辑器中的防护措施，不能替代 scripts/check_marketplace.sh — PR 前务必运行预检。

反模式（出现的问题及其解决方法）

阅读 references/anti_patterns.md，查看在实际市场开发中发现的完整问题列表。这些并非理论上的问题——每一个都曾在生产环境中遇到并排查解决。