utility-update-pm-skills

PM Skills アップデーター

このスキルは、ローカルの pm-skills インストールを最新の公開リリースに更新します。接続を確認し、バージョンを比較して、変更内容をプレビューし、更新内容と利用可能になった新機能を記録した構造化レポートを作成します。

使用する場面

• ローカルの pm-skills を最新リリースに更新したい場合
• 新しいバージョンが利用可能か確認したい場合
• pm-skills の新しいリリースが告知された後
• オンボーディング時に、最新バージョンがインストールされているか確認したい場合

使用しない場面

• 個別のスキルを作成または編集する場合 → utility-pm-skill-builder または utility-pm-skill-iterate を使用してください
• スキルが規約に準拠しているか検証する場合 → utility-pm-skill-validate を使用してください
• pm-skills リポジトリを直接操作するメンテナーの場合（git を使用してください）
• 特定の古いバージョンに固定する場合（このスキルは常に最新リリースを対象とします）

フラグ

フラグ	動作
(none)	更新の全手順：事前確認 → プレビュー → 確認 → 更新 → レポート
--report-only	事前確認 → プレビュー → レポート（ファイルは書き込みません）
--status	簡易バージョン確認：現在のバージョンと最新バージョンを表示して終了します

--status の動作

--status が指定された場合は、事前確認のみを実行して、次の内容を表示します。

pm-skills v{local} (installed, from {source})
pm-skills v{latest} (latest, released {date})
{Status: up to date | update available ({type})}

Run utility-update-pm-skills for details, or utility-update-pm-skills --report-only for a preview.

レポートファイルは生成されません。ファイルへの書き込みも行われません。

手順

--status を指定せずに pm-skills の更新を依頼された場合は、次の手順に従ってください。

ステップ 1：事前確認

続行する前に、次の 3 つを確認します。

1. ネットワークアクセス：GitHub API またはリポジトリ URL にアクセスできることを確認します （https://github.com/product-on-purpose/pm-skills）。利用可能な方法を使用してください：curl、wget、GitHub CLI（gh）、または MCP ツール。

2. 最新バージョン：次のフォールバック順に最新リリースを照会します （順番に試し、最初に成功した方法を使用してください）。

   1. GitHub API：GET /repos/product-on-purpose/pm-skills/releases/latest
   2. GitHub CLI：gh release list --repo product-on-purpose/pm-skills --limit 1
   3. Git：git ls-remote --tags https://github.com/product-on-purpose/pm-skills.git

   3 つすべてが失敗した場合（レート制限、404、不正な形式のレスポンス、ネットワーク接続なし）は、縮退モードに入ります（下記を参照）。

   次の情報を記録します：バージョン文字列、リリース日、リリースノートの URL、リリースノート本文。

3. ローカルバージョン：最初に見つかった情報源から読み取ります。

   • .claude-plugin/plugin.json → version フィールド
   • marketplace.json → plugins[0].version フィールド
   • CHANGELOG.md → 最新のバージョン見出し
   • Git タグ → 最新の v* タグ

   バージョンの解析： 任意の v プレフィックスを取り除き、前後の空白を削除して正規化します。情報源が存在するものの、値が空、semver 形式でない、または不正な形式の場合（無効な JSON、フィールドの欠落）は、警告を出してその情報源をスキップし、次の情報源を試します。4 つすべての情報源で取得できなかった場合のみ、0.0.0 にフォールバックします。

ネットワークアクセスに失敗した場合（縮退モード）：

• エラーの詳細とともに、失敗を報告します。
• 手動で更新する手順を案内します：

  https://github.com/product-on-purpose/pm-skills/releases にアクセスして、 最新リリースをダウンロードしてください。アーカイブを展開し、 skills/、commands/、_workflows/ およびその他のコンテンツディレクトリを ローカルの pm-skills インストール先にコピーしてください。

• 実行を終了します。

ステップ 2：バージョンの比較

semver を使用して、ローカルバージョンと最新リリースを比較します。

ローカルバージョン >= 最新バージョンの場合：

• 次のように報告します：「pm-skills は最新の状態です（v{local}）。」
• 必要に応じてレポートのみを生成するかどうかを確認します。
• 実行を終了します。

ローカルバージョン < 最新バージョンの場合：

• バージョンの差分を表示します：

  Local version:  v{local}
  Latest version: v{latest}
  Update type:    {major | minor | patch}
  

• メジャーバージョンの警告：メジャーバージョンが上がる更新の場合（例：v2.x から v3.x）、目立つ警告を表示します：

  これはメジャーバージョンの更新です。スキルの契約に破壊的変更が含まれる可能性があります。 続行する前にリリースノートを確認してください。

• ステップ 3 に進みます。

ステップ 3：プレビュー

更新内容をユーザーに提示します。

1. バージョン差分：ローカルのバージョン、最新バージョン、更新の種類。

2. 価値の概要：2つのバージョン間の CHANGELOG エントリー、GitHub リリースノート、ディレクトリの差分（新しい skills/、新しい _workflows/ ファイル）から導きます。

   • 新しいスキルと、それによって可能になること
   • 更新されたスキルと、その改善点
   • 新しいワークフローと、それらが連携するもの
   • その他の注目すべき変更

3. ファイル一覧：書き込まれるファイルとフォルダーを、ディレクトリごとに件数とともにまとめて一覧表示します。

   Files to be written:
     skills/       31 files (2 new, 29 updated)
     commands/     38 files (2 new, 36 updated)
     _workflows/    9 files (1 new, 8 updated)
     other          7 files
     Total:        85 files
   

--report-only の場合： references/TEMPLATE.md を使用して、バナー「レポートのみ - 更新は適用されません。」を含むレポートを生成します。_pm-skills/updates/update-report_v{latest}_report-only_{YYYY-MM-DD_HHMMSS}.md に保存します。実行を停止します。

ステップ 4：確認

ユーザーに2つの判断を求めます。

1. 更新の確認： 「これらのファイルは上書きされます。続行しますか？ [yes / no]」

   • メジャーバージョンが上がる場合は、明示的に「yes」と入力する必要があります。
   • ユーザーが拒否した場合は、レポートのみを保存して停止します。

2. バックアップの提案： 「更新前に現在のファイルをバックアップしますか？ [yes（推奨） / no]」

   • yes の場合：対象範囲内のすべてのファイルを _pm-skills/backups/v{current}_{YYYY-MM-DD_HHMMSS}/ にコピーします。
   • _pm-skills/ ディレクトリが存在しない場合は作成します。

ステップ 5：更新

バックアップを作成し、検証してからコピーする手順で更新を実行します。

1. ダウンロード：GitHub リリースページからリリース ZIP アセット（pm-skills-vX.Y.Z.zip）を一時ディレクトリに取得します。これは build-release.sh が生成する厳選されたビルド成果物で、ユーザー向けコンテンツのみが含まれ、docs/internal/ は除外されています。

2. 検証：展開したアーカイブに skills/、commands/、AGENTS.md、.claude-plugin/plugin.json が含まれていることを確認します。検証に失敗した場合は、エラーを報告し、ファイルを書き込まずに停止します。

3. コピー：展開したアーカイブから対象範囲内のファイルをインストール先のルートに上書きコピーします。ディレクトリごとに進捗を表示します。

   Updating pm-skills v2.9.0 -> v2.10.0...
     skills/       31/31 ████████████████████  done
     commands/     38/38 ████████████████████  done
     _workflows/    9/9  ████████████████████  done
     other files    7/7  ████████████████████  done
   

4. クリーンアップ：一時ディレクトリを削除します。

ステップ 6：更新後

1. スモークテスト：

   • バージョンの整合性：plugin.json、marketplace.json、CHANGELOG.md がすべて新しいバージョンを示していること。（注：ステップ 1 のバージョン検出では最初に一致したものを使用します。スモークテストではすべてのソースが一致することを確認します。ここで不一致があれば、リリースのパッケージングに問題がある可能性があります。）
   • ファイルの整合性：AGENTS.md、skills/、commands/、_workflows/ がすべて存在すること。
   • スキル数の差分：更新前後のスキル数を数え、増減を報告します。
   • いずれかのチェックに失敗した場合：具体的な詳細とともにユーザーに警告します。自動ロールバックは行わないでください。復旧手順を案内します。
     • バージョンの不一致：「更新を再実行するか、{file} を手動で編集してバージョンを {expected} に設定してください。」
     • ファイルの不足：「再ダウンロードするには utility-update-pm-skills を再実行するか、バックアップから復元してください：cp -r _pm-skills/backups/{dir}/* .」
     • バックアップがある場合：バックアップの場所と復元コマンドを必ずユーザーに伝えます。

2. 概要行：ひと目で確認できる簡潔な確認メッセージを1行で表示します。

   Updated v{old} -> v{new} | +{n} skills, +{n} workflows | Report: _pm-skills/updates/{file}
   

3. 完了レポート：references/TEMPLATE.md を使用して生成し、_pm-skills/updates/update-report_v{from}-to-v{to}_{YYYY-MM-DD_HHMMSS}.md に保存します。

4. MCP に関する案内：../pm-skills-mcp/ が存在する場合は、pm-skills-source.json の読み込みを試みます。ファイルが見つからないか、形式が不正な場合は、次のように表示します。 「pm-skills-mcp が検出されましたが、pm-skills-source.json が見つからないか、読み取れません。MCP リポジトリを手動で確認してください。」 読み込み可能な場合は、次の内容を表示します。

   pm-skills-mcp detected at ../pm-skills-mcp/
     Embedded skills version: v{embedded}
     Updated pm-skills version: v{new}
   
     To update the MCP server's embedded skills:
       cd ../pm-skills-mcp && npm run embed-skills && npm run build
   

5. 次のステップ：

   Next Steps:
   - Review the update report at _pm-skills/updates/{report-file}
   - Run utility-pm-skill-validate --all to verify skill integrity
   - Run local CI: bash scripts/lint-skills-frontmatter.sh
   - Check release notes: {release-url}
   

ファイルの対象範囲

アップデーターが書き込むのは、リリース ZIP アセット （pm-skills-vX.Y.Z.zip）に含まれるファイルのみです。これは build-release.sh が生成する厳選済みビルドです。v2.30.0 以降、ZIP には agents/ のサブエージェント定義と hooks/ のアクティベーションフックも含まれるため、 ZIP からインストールすれば、ディスパッチスキルが参照する実行時ファイルも揃います。ZIP には docs/internal/ やその他のユーザー向けではないコンテンツは含まれないため、コピー時に除外ロジックは 必要ありません。

リリース ZIP に含まれるファイル（更新対象）：

パス	理由
skills/	コアスキルファイル
commands/	スラッシュコマンド定義
_workflows/	ワークフローチェーン
agents/	utility-pm-* ディスパッチスキルが実行時に読み込むサブエージェント定義
hooks/	hooks.json を含むアクティベーションフック（ガードレール＋フェーズルーター）
library/	サンプルライブラリとスキル出力サンプル（注：ユーザーが追加したサンプルは上書きされることがあります）
AGENTS.md	IDE 向けスキル検出
.claude-plugin/plugin.json	バージョン＋プラグインのメタデータ
marketplace.json	マーケットプレイスのメタデータ
CHANGELOG.md	リリース履歴
README.md	公開ドキュメント
docs/（公開ガイド、リファレンス、ワークフロー）	ユーザー向けドキュメント
scripts/	CI／検証スクリプト
mkdocs.yml	ドキュメントサイトの設定

リリース ZIP に含まれないファイル（上書きされません）：

パス	理由
docs/internal/	build-release.sh により ZIP から除外
_NOTES/	ローカル専用、gitignore 対象、ZIP には含まれない
_pm-skills/	ローカル状態（レポート、バックアップ）、ZIP には含まれない
.github/	CI ワークフロー、ZIP には含まれない
CONTRIBUTING.md、LICENSE	ZIP には含まれない（リポジトリレベルのファイル）

出力要件

このスキルは必ず次を行います：

• リモート操作の前にネットワークアクセスを検証する
• ファイルを書き込む前にプレビューを表示する
• 上書きする前にユーザーの明示的な確認を求める
• 上書きする前にバックアップを提案する
• 検証後にコピーする（ダウンロードして一時保存し、検証してからコピーする。コピー途中で失敗した場合の復旧手段はバックアップです）
• どちらのモードでも（レポートのみ、完了）レポートを生成する
• 更新後のスモークテストを実行する
• 同階層のリポジトリが検出された場合、MCP に関する注意事項を表示する

このスキルは次を行ってはなりません：

• ユーザーの確認なしにファイルを書き込む
• ネットワークアクセスの確認なしに処理を進める
• pm-skills ディレクトリ外のファイルを変更する
• docs/internal/、_NOTES/、_pm-skills/ をアップストリームの内容で変更する
• スモークテスト失敗時に自動ロールバックする（代わりにユーザーに知らせる）
• アップストリームのリリースに存在しないローカルファイルを削除する

品質チェックリスト

更新の完了とする前に、次を確認してください：

• 事前チェックに合格：ネットワーク、検出されたバージョン
• ファイルを書き込む前にプレビューがユーザーに表示された
• 更新を進める前にユーザーの明示的な確認を得た
• バックアップを提案した（承諾された場合は作成した）
• アーカイブを一時保存先にダウンロードし、コピー前に検証した
• 対象範囲内のすべてのファイルが正常に書き込まれた
• バージョンの整合性：plugin.json、marketplace.json、CHANGELOG が一致する
• ファイルの整合性：AGENTS.md、skills/、commands/、_workflows/ が存在する
• スキル数の増減が報告された（更新前 -> 更新後）
• レポートが生成され、_pm-skills/updates/ に保存された
• 同階層のリポジトリが検出された場合、MCP に関する注意事項が表示された
• 次の手順が提示された
• 要約行が表示された

よくある質問

リポジトリをクローンしたコントリビューターですが、このスキルを使うべきですか？ いいえ。代わりに git pull または git fetch && git merge を使用してください。このスキルは、pm-skills をプラグインとしてインストールしたユーザー、またはリリースをダウンロードしたユーザー向けです。

最新バージョンではなく、特定のバージョンに更新できますか？ v1 ではできません。このスキルは常に最新リリースを対象とします。特定のバージョンをインストールするには、リリースページから手動でダウンロードしてください。

ローカルのメモや計画ドキュメントはどうなりますか？ 一切変更されません。このスキルは更新対象から docs/internal/、_NOTES/、_pm-skills/ を明示的に除外しています。「ファイルの対象範囲」表を参照してください。

上流リリースに含まれていない、自分が追加したファイルはどうなりますか？ 変更されません。このスキルは新しいリリースに存在するファイルのみを上書きし、ローカルファイルを削除することはありません。

更新を元に戻すにはどうすればよいですか？ バックアップを作成した場合（デフォルトで提案されます）は、次のコマンドで復元してください： cp -r _pm-skills/backups/v{version}_{timestamp}/* . バックアップを作成していないものの、git を使用している場合は、git checkout . を実行して、追跡対象ファイルを最後にコミットした状態に復元してください。

更新が途中で失敗しました。どうすればよいですか？ このスキルはコピー前に検証を行うため（一時領域にダウンロードして確認してから書き込みます）、部分的な失敗はまれです。発生した場合は、利用可能であればバックアップから復元するか、utility-update-pm-skills を再実行して再試行してください。

関連情報

手順を視覚的に確認できるガイドと詳しい背景については、 PM Skills の更新ガイドを参照してください。