agent-skill-deploy

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

目的

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

• Git の状態、スキルの一覧、配布先の準備状況を事前に検証します
• Conventional Commits を分析し、推奨するバージョン更新を提示します
• 検出されたすべての配布先設定ファイルのバージョンを更新します
• ドライラン機能を使って、配布先ごとにデプロイします
• 取り消せない操作の前に、ユーザーの承認を求めます

このスキルを使うタイミング

ユーザーが次のことを求めた場合に、このスキルを使います。

• スキルコレクションの「リリース」「デプロイ」「公開」または「出荷」
• 1 つ以上のマーケットプレイスに向けたバージョン更新とプッシュ
• スキルリポジトリの 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）で動作する 3 つの Node.js ヘルパースクリプトが scripts/ に含まれています。

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、マーケットプレイスファイル内の 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）
• ファイル変更の統計情報を表示する
• バージョンの更新推奨を表示する

バージョン更新の基準：

更新	条件
メジャー	破壊的変更 — type!: プレフィックス、または本文中の BREAKING CHANGE
マイナー	新機能 — feat: コミットがある場合
パッチ	その他すべて — 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. 各差分を分析し、スキルごとにユーザーに見える変更をまとめた簡潔な箇条書きを作成します。ガイドライン：
   • 各項目は、短く、動作を表す文にします（例：「X を追加」「Y を修正」「Z を削除」）。
   • スキルごとにレベル 2 の見出し（## skill-name）でまとめます。
   • 内部的な変更（空白、改行コードの統一）は、変更がそれしかない場合を除き、省略します。
   • スキルのメタデータ内のバージョン更新は、そのスキルに実質的な変更がほかにない場合にのみ記載します。
   • スキルごとに、おおよそ 5～7 項目を上限とします。必要に応じて軽微な項目をまとめてください。
4. ステップ 9 で使うため、作成した Markdown 形式の変更履歴を保存します。

出力例の形式：

## 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: "Recommended: {{RECOMMENDATION}}. Which version bump for v{{CURRENT}} → v{{NEXT}}?"
  header: "Version"
  options:
    - label: "Major (v{{MAJOR}})"
      description: "Breaking changes — skill removals, renames, config restructuring"
    - label: "Minor (v{{MINOR}})"
      description: "New features — new skills, significant enhancements"
    - label: "Patch (v{{PATCH}})"
      description: "Fixes, docs, refactoring, chore, CI, tests"
    - label: "Cancel"
      description: "Abort the deployment"

{{CURRENT}} を現在のバージョンに置き換え、該当するセグメントを増分して {{MAJOR}}、{{MINOR}}、{{PATCH}} を計算します（下位のセグメントは 0 にリセットします）。

ユーザーが Cancel を選択した場合は、ワークフローを停止します。

サーフェスについては AskUserQuestion ツールを使用します。

AskUserQuestion:
  question: "Detected surfaces: {{DETECTED_SURFACES}}. Which surfaces to deploy to?"
  header: "Surfaces"
  options:
    - label: "All detected ({{DETECTED_SURFACES}})"
      description: "Deploy to every surface that has config files"
    - label: "GitHub release only"
      description: "Create tag and GitHub release"
    - label: "Marketplaces only"
      description: "Update marketplace configs without GitHub release"
    - label: "Custom selection"
      description: "Specify exact surfaces"
    - label: "Cancel"
      description: "Abort the deployment"

ステップ 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 のメタデータ（name、description、version、author、repository、license、keywords）から自動的に作成されます。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: "Ready to push v{{VERSION}} and deploy to {{SURFACES}}?"
  header: "Deploy"
  options:
    - label: "Yes — push and deploy"
      description: "Push commits, tags, and run surface-specific deployments"
    - label: "Push only — skip surface deploys"
      description: "Push commits and tags but skip marketplace-specific actions"
    - label: "No — keep local"
      description: "Keep local commit and tag, do not push"

ユーザーが No を選択した場合は、次の内容を伝えてください。

• コミットとタグはローカルに残ります
• 元に戻すには、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 ディレクトリがない場合： リポジトリが想定されるスキルコレクションの構成に従っていないことを報告し、停止します。
• 不足しているツールがある場合： どのサーフェスにどのツールが不足しているかを報告します。インストールコマンドを提示します。ツールが利用可能なサーフェスへのデプロイは許可します。
• サーフェス間でバージョンが一致しない場合： 不一致を報告し、すべての設定ファイルを同期するためにバージョン更新の手順を実行するよう提案します。
• タグがすでに存在する場合： 競合を報告し、別のバージョンを選択するか、ユーザーの確認を得て既存のタグを削除するよう提案します。
• プッシュに失敗した場合： エラーを報告します。自動的に再試行しないでください。リモートへのアクセスと認証を確認するよう提案します。
• サーフェスへのデプロイに失敗した場合： いずれかのサーフェスで失敗しても、その旨を報告し、残りのサーフェスの処理を続行します。最後にサーフェスごとのステータス概要を提示します。
• ドライランと実行結果が異なる場合： 一時停止し、相違点をユーザーに報告します。