エージェント スキル コレクション デプロイ

目的

エージェント スキル コレクションの複数サーフェスへのデプロイを自動化します:

• Git状態、スキル インベントリ、サーフェス準備度の事前検証
• コンベンショナルコミット分析とバージョンバンプ推奨
• 検出されたすべてのサーフェス設定ファイル間でのバージョン同期
• ドライランカ機能を備えたサーフェス固有のデプロイ
• 不可逆的な操作前のユーザー承認ゲート

このスキルを使用する場面

ユーザーが以下の場合にこのスキルを使用します:

• スキル コレクションの「リリース」「デプロイ」「公開」「リリース」を要求する場合
• バージョンをバンプしてマーケットプレイスにプッシュしたい場合
• スキル リポジトリ用のGitHubリリースを作成する必要がある場合
• Claude Code、VS Code、またはCopilot CLIマーケットプレイスにスキルを公開したい場合
• デプロイ準備状況を確認またはドライランリリースを実行したい場合

使用しないでください NPMパッケージ、Dockerデプロイ、Azureリソース プロビジョニング、または /skills ディレクトリがないリポジトリに対して。

サポート対象サーフェス

サーフェス	設定ファイル	デプロイ アクション	必要なツール
github	Gitリモート URL	タグ作成 + GitHubリリース作成	gh
claude-code	.claude-plugin/plugin.json (必須)、.claude-plugin/marketplace.json (オプション)	プラグイン バージョンバンプ、コミット、プッシュ	git
vscode	package.json	バージョンバンプ、コミット、プッシュ	git
copilot-cli	package.json、.github/plugin/plugin.json、.github/plugin/marketplace.json (オプション)	プラグイン バージョンバンプ、コミット、プッシュ	git

バンドル スクリプト

このスキルには、クロスプラットフォーム対応(WindowsおよびmacOS)のための scripts/ ディレクトリ内に3つのNode.jsヘルパー スクリプトが含まれています:

1. deploy-preflight.mjs — Git状態を検証、サーフェス検出、ツール利用可能性確認、バージョン一貫性検証(Gitタグバージョンを含む)
2. deploy-analyze.mjs — スキル インベントリ、最後のタグ以降のコミット分析、バージョンバンプ推奨
3. deploy-execute.mjs — 検出されたすべての設定ファイル(選択したサーフェスに関係なく)でバージョンをバンプ、コミット、タグ、選択したサーフェスへデプロイ

スキル ディレクトリから スクリプトを実行します:

node scripts/deploy-preflight.mjs
node scripts/deploy-analyze.mjs
node scripts/deploy-execute.mjs 1.2.0 --surfaces github,claude-code --dry-run

バージョン処理ルール

Marketplace.jsonファイルには、異なるセマンティクスを持つ2つの異なるバージョン フィールドが含まれています:

• plugins[].version (プラグイン バージョン) — リストされている各プラグインのバージョンを追跡します。ローカル プラグイン(ここで source は ".")のリリース中にバンプされます。
• metadata.version (マーケットプレイス バージョン) — マーケットプレイス コレクション自体のバージョンを追跡します。スキル/プラグイン リリース中にはバンプされません。 独立して管理されます。

ファイル間の同期ルール:

• すべてのプラグイン バージョンは一貫性を保つ必要があります: plugin.json、package.json、marketplace.jsonファイル内の plugins[].version、およびGitタグ。
• marketplace.jsonファイル(.claude-plugin/marketplace.json および .github/plugin/marketplace.json)全体にわたるすべての metadata.version 値は互いに同期していなければなりません。

デプロイ ワークフロー

次のステップを順番に実行します。いずれかのステップが失敗した場合は直ちに停止します。

ステップ 1: 事前確認チェック

事前確認スクリプトを実行して準備状況を検証します:

node scripts/deploy-preflight.mjs

以下をチェックします:

• 現在のディレクトリはGitリポジトリ
• 現在のブランチは master または main
• ワーキング ツリーはクリーン(コミットされていない変更なし)
• /skills ディレクトリが存在し、少なくとも1つのスキルを含む
• 既存の設定ファイルに基づいて設定されているサーフェスを検出
• 各サーフェス用に必要なツールが利用可能であることを確認
• .claude-plugin/plugin.json と .github/plugin/plugin.json の両方が存在することを確認; どちらか一方が不足している場合は警告(デプロイ中に自動作成)
• すべてのサーフェス設定にわたるバージョン一貫性をレポート(Gitタグ バージョンを含む)

チェックが失敗した場合、問題をレポートして修正を提案します。続行しないでください。

ステップ 2: 変更を分析

分析スクリプトを実行して変更内容を理解します:

node scripts/deploy-analyze.mjs

以下を実行します:

• /skills 内のすべてのスキルを名前とともにインベントリ化
• 最後のリリース タグを検索(またはファーストリリースを処理)
• そのタグ以降のすべてのコミットをリスト化
• アンカー付き正規表現を使用してコンベンショナル タイプ別にコミットをカウント
• 重大な変更を検出(type!: サフィックスまたは本文の BREAKING CHANGE)
• ファイル変更統計を表示
• バージョン バンプ推奨を出力

バージョン バンプ基準:

バンプ	条件
Major	重大な変更 — type!: プレフィックスまたは本文の BREAKING CHANGE
Minor	新機能 — 任意の feat: コミット
Patch	その他すべて — fix:、docs:、refactor:、chore: など

ステップ 2b: スキルごとのチェンジログをビルド

github サーフェスが選択されている場合、スキルでグループ化された簡潔でユーザーが読める形のチェンジログをビルドします。これはGitHubの自動生成ノートに置き換わります。

手順:

1. deploy-analyze.mjs の出力から前回のリリース タグを特定します(Last release tag 行)。これが最初のリリースの場合、ルート コミットと比較します。
2. Skills Changed 出力にリストされている各スキルについて、以下を実行します:

   git diff v{{PREVIOUS}}..HEAD -- skills/{{SKILL_NAME}}/
   

3. 各diffを分析し、スキルごとの ユーザーが見える変更 をまとめた簡潔なビュレット リストを作成します。ガイドライン:
   • 各ビュレットを短く、アクション指向のステートメントで記述します(例: 「Xを追加」「Yを修正」「Zを削除」)。
   • スキルごとにレベル2の見出し(## skill-name)でグループ化します。
   • 内部のみの変更(空白、改行の正規化)は省略します(それが唯一の変更の場合を除く)。
   • スキルのメタデータ内のバージョン バンプは、そのスキルに他の実質的な変更がない場合のみメンションします。
   • スキルあたり約5～7個のビュレットに制限; 必要に応じて軽微な項目を統合します。
4. 組み立てたMarkdownチェンジログ テキストをステップ 9 で使用するために保存します。

出力形式の例:

## agent-package-manager
- Added subdirectory path and pinned tag dependency examples to template
- Expanded manifest reference with Azure DevOps and GitLab guidance
- Added "APM not installed" troubleshooting section

## agent-skill-deploy
- Made marketplace.json optional for Claude Code surface detection
- Simplified version bump recommendation logic

## github-agentic-workflows
- Added install.md URL reference for agent-assisted setup

変更があったスキルが1つだけの場合、見出しを省略してフラットなビュレット リストを使用します。

ステップ 3: バージョンとサーフェスをユーザーで確認

分析サマリーを提示し、ユーザーにバージョンとターゲット サーフェスの選択を促します。

AskUserQuestion ツールをバージョンに使用:

AskUserQuestion:
  question: "推奨: {{RECOMMENDATION}}。v{{CURRENT}} → v{{NEXT}} のバージョン バンプはどれですか?"
  header: "バージョン"
  options:
    - label: "Major (v{{MAJOR}})"
      description: "重大な変更 — スキル削除、名前変更、設定再構築"
    - label: "Minor (v{{MINOR}})"
      description: "新機能 — 新しいスキル、大幅な改善"
    - label: "Patch (v{{PATCH}})"
      description: "修正、ドキュメント、リファクタリング、chore、CI、テスト"
    - label: "キャンセル"
      description: "デプロイを中止"

{{CURRENT}} を現在のバージョンに置き換え、関連するセグメントをインクリメントして {{MAJOR}}、{{MINOR}}、{{PATCH}} を計算します(下位セグメントを0にリセット)。

ユーザーがキャンセルを選択した場合、ワークフローを停止します。

AskUserQuestion ツールをサーフェスに使用:

AskUserQuestion:
  question: "検出されたサーフェス: {{DETECTED_SURFACES}}。デプロイするサーフェスはどれですか?"
  header: "サーフェス"
  options:
    - label: "すべて検出({{DETECTED_SURFACES}})"
      description: "設定ファイルがあるすべてのサーフェスにデプロイ"
    - label: "GitHubリリースのみ"
      description: "タグとGitHubリリースを作成"
    - label: "マーケットプレイスのみ"
      description: "GitHubリリースなしでマーケットプレイス設定を更新"
    - label: "カスタム選択"
      description: "具体的なサーフェスを指定"
    - label: "キャンセル"
      description: "デプロイを中止"

ステップ 4: ドライラン(推奨)

変更を加える前に、ドライランを実行して何が起こるかを検証します:

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --dry-run

ドライラン出力をユーザーに提示します。ドライランは以下を表示します:

• 変更されるファイルとその方法
• 実行されるGit操作
• 実行されるサーフェス固有のデプロイ コマンド
• ファイルは変更されず、Git操作は実行されません

ドライランで問題が明らかになった場合、続行前に対処します。

ステップ 5: バージョンをバンプ

すべての検出されたサーフェス設定全体でバージョン バンプを実行します:

node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --bump-only

重要 — バージョン同期の不変性: スクリプトは常に --surfaces 経由で選択されたサーフェスに関係なく、すべての検出された設定ファイル(plugin.json、marketplace.json、package.json)をバンプします。これにより、サーフェス間のバージョン ドリフトを防ぎます。--surfaces フラグは、--push モードで実行されるデプロイ アクションのみを制御します。

不足しているplugin.jsonの自動作成: バンプ前に、スクリプトは .claude-plugin/plugin.json(claude-codeサーフェス)と .github/plugin/plugin.json(copilot-cliサーフェス)の両方が存在することを確認します。どちらかのファイルが不足している場合、兄弟のplugin.json(優先)または package.json メタデータ(名前、説明、バージョン、作者、リポジトリ、ライセンス、キーワード)からフォールバックとして自動作成されます。copilot-cliバリアントは "skills": "skills/" も取得します。

これにより、以下のバージョン フィールドが更新されます:

• .claude-plugin/plugin.json → .version(claude-codeサーフェス)
• .claude-plugin/marketplace.json → .plugins[0].version(claude-codeサーフェス、ファイルが存在する場合のみ)
• package.json → .version(vscodeおよびcopilot-cliサーフェス)
• .github/plugin/plugin.json → .version(copilot-cliサーフェス、ファイルが存在する場合のみ)
• .github/plugin/marketplace.json → .plugins[0].version および .metadata.version(copilot-cliサーフェス、ファイルが存在する場合のみ)

marketplace.json が存在しない場合、プラグインは別のリポジトリで定義されたマーケットプレイスにリストされていると想定されます。plugin.json のみがバンプされます。

すべてのファイルが正しく更新されたことを確認するため、ファイルを読み直します。

ステップ 6: バージョン バンプをコミット

変更されたすべての設定ファイルをステージング してコミットします:

git add -A
git commit -m "Release v{{VERSION}}"

ステップ 7: Gitタグを作成

リリース コミットにタグを付けます:

git tag v{{VERSION}}

ステップ 8: プッシュ前のユーザー承認

重要: ここで必ずユーザー承認のために一時停止してください。

サマリーを提示し、確認を求めます。

AskUserQuestion ツールを使用:

AskUserQuestion:
  question: "v{{VERSION}} をプッシュして {{SURFACES}} にデプロイする準備ができました?"
  header: "デプロイ"
  options:
    - label: "はい — プッシュしてデプロイ"
      description: "コミット、タグをプッシュしてサーフェス固有のデプロイを実行"
    - label: "プッシュのみ — サーフェス デプロイをスキップ"
      description: "コミットとタグをプッシュするがマーケットプレイス固有のアクションをスキップ"
    - label: "いいえ — ローカルに保持"
      description: "ローカル コミットとタグを保持、プッシュしない"

ユーザーがいいえを選択した場合、以下を通知します:

• コミットとタグはローカルに残る
• 元に戻す場合: git reset --hard HEAD~1 && git tag -d v{{VERSION}}

ステップ 9: プッシュとデプロイ

ユーザーが承認した後のみ:

1. ステップ 2b からのスキルごとのチェンジログを一時ファイルに保存します:

   echo '{{CHANGELOG}}' > /tmp/release-notes.md
   

2. プッシュとデプロイを実行します:

   node scripts/deploy-execute.mjs {{VERSION}} --surfaces {{SURFACES}} --push --notes-file /tmp/release-notes.md
   

以下を実行します:

1. すべてのサーフェス用に git push && git push --tags を実行
2. github サーフェス: ステップ 2b からのスキルごとのチェンジログを使用してリリースを作成:

   gh release create v{{VERSION}} --title "v{{VERSION}}" --notes-file /tmp/release-notes.md
   

   --notes-file が指定されない場合、スクリプトは --generate-notes にフォールバックします。常にスキルごとのチェンジログ提供を優先します。

プッシュ後、リモートURLと関連するマーケットプレイス リンクを出力します。

エラー ハンドリング

• /skills ディレクトリがない: リポジトリが予想されるスキル コレクション レイアウトに従っていないことをレポートして停止します。
• ツールが不足: どのサーフェスにどのツールが不足しているかをレポート。インストール コマンドを提案。ツールが利用可能なサーフェスへのデプロイを許可します。
• サーフェス間のバージョン不一致: 不一致をレポートし、すべての設定ファイルを同期するためにバンプ ステップを実行することを提案します。
• タグが既に存在: 競合をレポートし、別のバージョンを選択するか、ユーザー確認でタグを削除することを提案します。
• プッシュ失敗: エラーをレポート。自動的に再試行しません。リモート アクセスと認証を確認することを提案します。
• サーフェス デプロイ失敗: 1つのサーフェスが失敗してもレポートして残りを続行します。終了時にサーフェスごとのステータス サマリーを提供します。
• ドライラン ダイバージェンス: 実際の実行がドライランと異なる場合、一時停止して発散をユーザーにレポートします。