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 セッションを調べるのは、ユーザーがその非公開情報源の使用を明示的に依頼または承認した場合に限ります。

その履歴情報源の使用が承認されている場合、各プロジェクトのセッションは次の場所にあります。 ~/.claude/projects/<escaped-cwd>/：

• トップレベルのファイル：<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 のフロントマターから次の項目を抽出します。

• 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 には、次の 3 つの独立したレベルがあります。

marketplace -> plugin -> skill

• マーケットプレイス名はインストール時の識別子として使われます：plugin@marketplace。
• プラグイン名はスラッシュ名前空間として使われます：/plugin-name:skill-name。
• スキルのパスが SKILL.md を直接含むディレクトリを指す場合、スキル名は SKILL.md のフロントマターから取得されます。

インストール、更新、キャッシュに関する意図に基づいて、各プラグインの境界を選びます。

• 単一スキルのプラグイン：スキルを個別にインストール、更新、ロールバックし、キャッシュを限定したい場合に使用します。
• スイートプラグイン：関連するスキルで名前空間とインストールコマンドを共有したい場合に使用します。例：/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**はマーケットプレイスカタログのバージョンであり、個々のプラグインのバージョンではありません。 リポジトリのVERSIONファイルと一致させてください（例："2.3.0"）。
4. **プラグインエントリのversion**は独立しています。初めてマーケットプレイスに登録する場合は、"1.0.0"を使用してください。
5. リポジトリにplugin.jsonがない場合は、**strict: false**が必要です。 strict: falseの場合、マーケットプレイスエントリがプラグイン定義のすべてとなります。 strict: falseとコンポーネントを含むplugin.jsonの両方が存在すると、読み込みに失敗します。
6. sourceはインストールされたプラグインのルートを定義します。単一スキルのプラグインでは、sourceをスキルディレクトリに直接指定し（例："./tunnel-doctor"）、skillsは省略してください。スイートプラグインでは、source: "./<suite>"を使用し、サブディレクトリを列挙したskills配列を明示的に指定してください。 source: "./"（リポジトリ全体がキャッシュとしてインストールされます）やskills: ["./"]（Claude Code 2.1.xのパスエスケープバリデーターで拒否されます）は避けてください。
7. 予約済みのマーケットプレイス名は使用できません：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>"]
    }
  ]
}

マーケットプレイスの名前を付ける

nameフィールドは、インストールコマンドで@の後にユーザーが入力する名前です： claude plugin install dbs@<marketplace-name>

次の条件を満たす名前を選んでください：

• 短く、覚えやすい
• kebab-case（小文字とハイフンのみ）
• 一般的な名前ではなく、プロジェクトのアイデンティティに関連している

説明のルール

• 各SKILL.mdのフロントマターにある元の説明を使用してください
• 説明を翻訳、脚色、「改善」しないでください
• リポジトリの対象読者が中国語話者の場合は、説明を中国語のままにしてください
• バイリンガルの場合は、SKILL.mdの説明フィールドに記載された最初の言語を使用してください
• マーケットプレイスレベルの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 配列に新しいメンバー（./skill-name）を記載します。ディスク上に SKILL.md を含むメンバーディレクトリが存在するのに、配列に記載されていない場合、check_marketplace.py は失敗します。
2. **metadata.version**を厳密に増加させます。新しいメンバーによってスイートのレイアウトシグネチャ（source + skills）が変わるため、check_version_progression.py はベースより上の metadata の更新がないレイアウト変更を拒否します。上記のルール 5（プラグインの version を更新すること）は必要ですが、これだけでは不十分です。
3. **README.md と README.zh-CN.md**のそれぞれに、### **skill-name** の詳細セクションを追加します。check_doc_skill_lists.py は必須チェックです。両方の README からすべての ### **name** 見出しを抽出し、マーケットプレイスのスキルが記載されていない場合は失敗します（逆の場合は 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 です。いずれの場合もリポジトリは判定されておらず、実行していない場合と同じです。どちらのコードも「チェッカーが問題を検出した」と解釈しないでください。この 2 つでは、終了コード 1 は validate_changed_skills.sh では使い方のエラーですが、check_version_progression.py では実際の指摘です。だからこそ、読むべきなのは番号ではなく、表示されたメッセージです。

post_edit_sync_check フックが検出するのは、「SKILL.md が編集されたのにプラグインのバージョンが更新されていない」場合だけです。項目 2〜4 にはフックがなく、CHANGELOG のエントリーにはフックもチェッカーもありません。CI の複数回の実行で初めて問題に気づくのではなく、プッシュ前にローカルで check_version_progression.py と check_doc_skill_lists.py を実行してください。--base <base-ref> --candidate HEAD を指定します。このスクリプトは --candidate-index も受け付けます。このオプションはgit indexからマニフェストの blob を読み取り、ステージングされたパスのみを差分比較します。何もステージングされていない場合、その blob は HEAD のコピーなので、すでにあるコミットを再検証し、実際には確認していない作業について「リグレッションなし」と報告します。その成功は index に対しては正しいものの、編集内容については何も示していません。

CI のバージョンゲートは、PR の head が更新された場合にのみ再実行され、実行時にベースを origin/$BASE_REF として解決します。そのため、ベースブランチがその後進んだ PR では、より古いベースに対して得た成功判定が維持される一方で、バージョン番号はすでに現在のベースに対するリグレッションになっている可能性があります。プッシュ前だけでなく、マージ直前にも現在の origin/main に対してゲートを再実行し、失敗した場合はリベースしてください。

フェーズ 3：検証

ステップ 1：一括事前チェック

同梱のバリデーターを実行します。次のチェックを実行し、必須チェックのいずれかに失敗すると 0 以外の終了コードを返します。

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

必須チェックに合格してください。逆方向同期の警告は実際の問題を示すものとして扱います。ディスク上にある未登録の 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 がケバブケースで、すべてのエントリー間で一意である
• 更新したプラグインごとに 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 を参照してください。これらは理論上の問題ではありません。すべて本番環境で発生し、デバッグされたものです。