utility-pm-skill-builder

PM スキルビルダー

このスキルは、pm-skills ライブラリ用の新しい PM スキルを作成します。ステージング領域にレビュー用の下書きファイルを含むスキル実装パケット（完全な設計ドキュメント）を作成し、正式な場所への反映前に確認できるようにします。

使用するタイミング

• 新しい PM スキルのアイデアがあるとき
• ドメインスキル（フェーズ固有）、基盤スキル（横断的）、またはユーティリティスキル（メタ／ツール関連）を pm-skills ライブラリに追加するとき
• リポジトリの規約に沿ったスキル作成を、コントリビューターにガイド付きで提供するとき

使用しないタイミング

• 既存のスキルを変更または改善するとき → utility-pm-skill-iterate を使用してください
• 既存のスキルが規約に準拠しているか監査するとき → utility-pm-skill-validate を使用してください
• pm-skills 以外のコンテキスト向けにスキルを作成するとき → 汎用エージェントスキルビルダーを使用してください
• ワークフローを作成するとき → ワークフローはこのビルダーではなく、直接作成します

手順

新しい PM スキルの作成を依頼されたら、次の手順に従います。

ステップ 1：アイデアを理解する

アイデアは、次のいずれかの形式で受け付けます。

• 問題優先：「このスキルは、どのような PM の問題を解決しますか？誰がこの問題に直面し、現在何を作成していますか（または何を作成できていませんか）？」
• スキル優先：「作成したいスキルについて説明してください。どのような成果物を作成しますか？どのような PM 活動を支援しますか？」

どちらの形式から始めても、以降の流れは同じです。ユーザーがどちらか一方の形式で情報を提供した場合、もう一方について質問せず、必要な情報を引き出して進めてください。

アイデアが曖昧な場合は、先に進む前に、成果物の種類と対象ユーザーを明確にするための追加質問を1つだけしてください。

ステップ 2：ギャップ分析

重複する可能性がある既存スキルをすべて確認します。以下の現在のライブラリ参照を使用し（skill-manifest.json または AGENTS.md から最新の一覧を導き出します）、skills/ ディレクトリもスキャンして最新の一覧を確認します。4つすべてのファミリー（ドメイン、基盤、ユーティリティ、ツール）を含めてください。ツールファミリーは、通常の会話で共通するフェーズプレフィックスのパターンを持たないため、見落としやすい点に注意してください。

具体的に調査結果を提示します。

• 重複する各スキルの名前と、その対象範囲を説明する
• 新しいスキルが埋める具体的なギャップを特定する
• 重複が大きい場合は、Why Gate（以下を参照）を実行する

Why Gate（重複が見つかった場合に実行）： ユーザーに次のように尋ねます。「既存のスキルでは必要な成果を得られない、具体的なプロンプトまたはシナリオを2～3個挙げてください。」

Kill Gate：ユーザーが説得力のあるギャップを説明できない場合は、代替案を推奨します。

• 「[既存のスキル]を修正して、このケースをカバーする」
• 「[スキル A] + [スキル B]を組み合わせるワークフローを作成する」
• 「新しいスキルではなく、コマンドのバリエーションを追加する」
• 「これは新しいスキルではなく、ドキュメントの改善です」

ギャップを示す説得力のある根拠、またはユーザーによる明示的な承認がない限り、Kill Gate を越えて先に進まないでください。

ステップ 3：スコープの確認

アイデアを1つのスキルにするべきか、複数のスキルにするべきかを評価します。

分割を示す兆候：

• アイデアから複数の異なる種類の成果物が生まれる
• Triple Diamond のフェーズをまたぐ（例：Discover + Deliver）
• 説明に、2つの活動をつなぐ「および」が自然に含まれる

分割が妥当な場合は、次のように推奨します。 「これは、2つの異なる PM 活動を対象としているようです。

1. [活動 A] → [成果物 A]を作成
2. [活動 B] → [成果物 B]を作成 これらは、ワークフローで連携できる別々のスキルにしたほうがうまく機能します。今回は[活動 A]のみで進めますか？」

ステップ 4：分類とリポジトリとの適合性

スキルの分類と命名方法を決定します。

ドメインスキル（フェーズごとの PM 活動）：

• フェーズ：discover | define | develop | deliver | measure | iterate
• ディレクトリ：{phase}-{skill-name}
• Frontmatter：phase: {phase}（必須）、classification フィールドは指定しません

基盤スキル（フェーズをまたいで使用）：

• フェーズなし
• ディレクトリ：foundation-{skill-name}
• Frontmatter：classification: foundation（必須）、phase フィールドは指定しません
• 使用するケース：スキルが複数のフェーズに等しく適用される場合

ユーティリティスキル（メタスキル、リポジトリのツール）：

• フェーズなし
• ディレクトリ：utility-{skill-name}
• Frontmatter：classification: utility（必須）、phase フィールドは指定しません
• 使用するケース：スキルがリポジトリ、ワークフロー、または他のスキルに作用する場合

方言と模範例の選定： まず、Skeleton Canon: The Three Sanctioned Dialects からスキルの方言（classic、contract-shaped、tool-family）を選びます。これにより、模範例を選ぶ前に必要な見出しのスケルトンが決まります。「最も近い模範例をそのまま踏襲する」ことを既定の方針にしないでください。模範例自体に逸脱（大文字・小文字の違い、セクションの過不足）が含まれている可能性があり、そのまま踏襲すると、その逸脱を新しいスキルにも引き継いでしまいます。

次に、同じ方言を使っている既存スキルから、構造的に最も近いものを 1〜2 個選びます。

• 同じフェーズ ＞ 同じカテゴリ ＞ 類似した成果物の種類
• SKILL.md を読み、指示のスタイル、出力契約の表現、品質チェックリストのパターンを確認します（必須の見出しは規範で定められており、模範例からはそれ以外の要素、つまりトーン、ステップの粒度、スキル固有の追加セクションを参考にします）。
• 模範例を明示します：「[スキル] をモデルにしています ― 同じフェーズ、[カテゴリ] カテゴリ、[方言] 方言」

分類、方言、模範例の選定を提示し、ユーザーの確認を求めます。

ステップ 4.5：評価の準備（評価の契約）

新しいスキルは、カバレッジが常に最新に保たれるよう、評価対応済みの状態でリリースする必要があります。ルーティングの健全性と出力品質を、初日からどちらも測定できるようにします。ここで評価の契約を決め、ステップ 5 でそのアセットを生成します。次の 4 項目です。

A. 最近傍（C-2）。 新しいスキルに最も近い既存スキルを 1～3 個挙げます。つまり、トリガーが最も重複する既存スキルです。ステップ 2 のギャップ分析に加え、同じフェーズ／カテゴリの兄弟スキルをもとに特定します。これらの最近傍は、境界ポインター（以下）、ニアミス・トリガー・フィクスチャ（ステップ 5）、衝突プローブ（ステップ 7）の基準となります。

B. 相互の境界ポインター（C-3）。 ドラフトの SKILL.md には、各最近傍を明記し、その最近傍を使うべき状況を示す ## When NOT to Use セクションを必ず含めてください。また、すべての最近傍について、相互のポインターも追加します。つまり、最近傍の SKILL.md に、新しいスキルを参照する「When NOT to Use」の箇条書きを追加してください。測定対象とする衝突ペアになるほど重複が強い場合は、そのペアを scripts/check-trigger-fixtures.mjs の COLLISION_PAIRS に追加し、相互性ゲート（check-reciprocal-boundary-pointers.mjs）と衝突プローブの両方で対象にします。相互ポインターにより、v2.26.0 の書き換えでは衝突を防げました。

C. 出力評価ファミリー（C-4）。 スキルを出力評価ファミリーのルーブリックに割り当て、成果物の品質を測定できるようにします。フェーズ／カテゴリに基づいて選んでください。

ファミリーのルーブリック	対象（フェーズ／種類）
framing	define-* の問題／仮説／jtbd／機会／優先順位付け ＋ foundation-okr-writer/persona/lean-canvas
specification	deliver-* の prd/acceptance-criteria/user-stories/edge-cases/launch-checklist
discovery	discover-* の interview-synthesis/competitive/market-sizing/journey/stakeholder
technical	develop-* の adr/design-rationale/solution-brief/spike-summary
measurement	measure-* の experiment-design/results/okr-grader/dashboard/instrumentation/survey
learning	iterate-* の retrospective/lessons-log/pivot-decision/refinement-notes
communication	対象者向け：deliver-release-notes、foundation-stakeholder-update

ファミリーのルーブリックは docs/internal/eval-rubrics/{family}.md にあります。スキルがルーブリックのあるファミリーに当てはまる場合は、その family の値をシナリオのフロントマターに使用します。新しいファミリーを開設する場合（ミーティング／ツール系スキルにはまだファミリーがありません）は、「ファミリーのルーブリックはまだありません。スキルが出力評価対象に加わる前に作成してください」と記し、ファミリーの値は省略します。

D. フィクスチャとシナリオの計画（C-1、C-4）。 ステップ 5 で生成する 2 つの評価アセットファイルを計画します。ルーティング用の trigger-fixtures.json と、出力品質用の output-scenarios/<id>.md です。それぞれの形式は、ステップ 5 の項目 13～14 で指定されています。

パケットを生成する前に、最近傍、ファミリー、相互ポインターの計画を提示し、ユーザーの確認を得てください。

ステップ 5：スキル実装パケットを生成する

フォーマットには references/TEMPLATE.md を使用して、完全なパケットを作成します。 パケットには次の項目を含めます。

1. 判断 - 推奨事項と Why Gate の根拠（該当する場合）
2. 分類 - タイプ、フェーズ（ドメインの場合）、カテゴリ、ディレクトリ名
3. 重複分析 - 見つかった内容と、このスキルがなお必要な理由
4. 模範スキル - モデルとして使用した既存スキルと、その理由
5. ドラフトのフロントマター - 完全で有効な YAML ブロック。フロントマターはファイルのバイト 0 から --- で始まらなければなりません（HTML コメント、BOM、空白など、前にいかなる内容も置かないでください）。帰属コメントを入れる場合は、必ず終了の --- フェンスの後に置いてください。参照：library/skill-output-samples/SAMPLE_CREATION.md のセクション 5。
6. ドラフトの SKILL.md - 概要ではなく全文を記載し、ステップ 4 の方言で定められた見出しの骨格と、選んだ模範スキルの指示スタイルに従います。
7. ドラフトの TEMPLATE.md - セクション見出しとガイダンスコメント
8. ドラフトの EXAMPLE.md - 具体的な PM シナリオを含む、現実的で完全な例（150～300 行）。すべてのセクションを記入し、任意セクションは記入した場合と省略した場合の両方を示します。
9. ドラフトのコマンド - コマンドのフロントマター
10. AGENTS.md エントリー - 追加する正確なテキスト
11. 検証チェックリスト - ドラフトに対してすべての CI ルールを確認
12. 次のステップ - ローカル CI、テスト、コントリビューションのワークフロー
13. ドラフトの trigger-fixtures.json（C-1、ルーティング評価） - evals/trigger-fixtures.json： JSON オブジェクト { "schema": 1, "skill": "{name}", "runs_per_query": 3, "trigger_threshold": 0.5, "queries": [...] }。queries 配列には合計 16 件以上、"expect": "trigger" が 8 件以上（スキルの実際の意図に基づくものとし、成果物のキーワードだけにしないでください。意図のみを示す依頼も含めます）、"expect": "no-trigger" が 8 件以上必要です。後者のうち 2 件以上はステップ 4.5 の隣接スキルを対象としたニアミスとし、"near_miss_of": "{neighbor}" を付けます。各クラスの "split": "train" と "split": "validation" の比率は約 60/40 にします。これは B-4 のフィクスチャー契約（scripts/check-trigger-fixtures.mjs）です。
14. ドラフトの出力シナリオ（C-4、出力品質評価） - evals/output-scenarios/{id}.md： フロントマターは scenario: {id} / skill: {name} / family: {family from Step 4.5} / created: {date} とし、その後に現実的な入力ブリーフを記載します（本文は 100 文字以上）。スキルを使うケースと、自由記述で対応するコントロール側に、同じ生の素材を与えてください。これは B-7 のアセット契約（scripts/check-output-eval-assets.mjs）です。ステップ 4.5 でルーブリックが見つからなかった場合に限り、family を省略します。
15. ドラフトの HISTORY.md - サマリーテーブルと、スキルの初回バージョンを示すベースライン行（Type は baseline）を含む HISTORY.md を作成し、さらに、そのバージョンで確立される契約を記述した ## 1.0.0 セクションを追加します。1.0.0 以降のすべてのスキルは初回バージョンからこのファイルを同梱するため、リリースが行われるたびに Release 列へ各バージョンを記録します（docs/internal/skill-versioning.md の「Skill History」）。対象のリリースが決まっている場合は Release 列に記載し、未定の場合は - とします。

ステップ 6：ステージング領域に書き込む

生成したすべてのファイルをステージング領域に書き込みます。

_staging/pm-skill-builder/{skill-name}/
├── SKILL.md               ← draft skill file
├── HISTORY.md             ← draft version history (baseline row)
├── references/
│   ├── TEMPLATE.md        ← draft template
│   └── EXAMPLE.md         ← draft example
├── evals/
│   ├── trigger-fixtures.json        ← draft routing fixtures (C-1)
│   └── output-scenarios/{id}.md     ← draft output-quality scenario (C-4)
└── command.md             ← draft command

注：_staging/ は gitignore の対象です。ドラフト成果物はリリースに含まれません。 昇格後、ステージングフォルダーは破棄されます。

書き込んだ内容と場所を報告します。

ステップ 7：昇格（確認後）

次のように尋ねます：「上記のパケットを確認してください。準備ができたら、ファイルを正式な配置先に昇格します。続行しますか？［yes/no］」

yes の場合、ステージングから正式なパスへ各ファイルをコピーして昇格します。

ステージングファイル	正式な配置先
_staging/pm-skill-builder/{skill-name}/SKILL.md	skills/{dir-name}/SKILL.md
_staging/pm-skill-builder/{skill-name}/HISTORY.md	skills/{dir-name}/HISTORY.md
_staging/pm-skill-builder/{skill-name}/references/TEMPLATE.md	skills/{dir-name}/references/TEMPLATE.md
_staging/pm-skill-builder/{skill-name}/references/EXAMPLE.md	skills/{dir-name}/references/EXAMPLE.md
_staging/pm-skill-builder/{skill-name}/evals/trigger-fixtures.json	skills/{dir-name}/evals/trigger-fixtures.json
_staging/pm-skill-builder/{skill-name}/evals/output-scenarios/{id}.md	skills/{dir-name}/evals/output-scenarios/{id}.md
_staging/pm-skill-builder/{skill-name}/command.md	commands/{command-name}.md

{dir-name} は分類プレフィックス付きのディレクトリです（例：deliver-change-communication）。

次の手順を実行します。

1. 対象ディレクトリを作成します：skills/{dir-name}/references/ と skills/{dir-name}/evals/output-scenarios/
2. 各ファイルを正式な配置先にコピーします
3. パケットに含まれる AGENTS.md のエントリーを追記します。ステップ 4.5 で衝突ペアが宣言されている場合は、scripts/check-trigger-fixtures.mjs の COLLISION_PAIRS に追加し、隣接する各スキルの SKILL.md に相互の「使用しない場合」の箇条書きを追加します
4. CI 検証を実行します：bash scripts/lint-skills-frontmatter.sh && bash scripts/validate-agents-md.sh && bash scripts/validate-commands.sh。続いて評価アセットのゲート node scripts/check-trigger-fixtures.mjs、node scripts/check-output-eval-assets.mjs、node scripts/check-reciprocal-boundary-pointers.mjs と、衝突プローブ node scripts/check-new-skill-collision.mjs --skill={name} を実行します（C-2 — 新しいスキルが独自のトリガーを想起し、隣接するスキルのトリガーを奪わないことを確認します）。カタログの各種情報を再生成します：node scripts/gen-skill-manifest.mjs && node scripts/gen-skill-manifest.mjs --agents
5. 検証に合格したら、ステージングフォルダー _staging/pm-skill-builder/{skill-name}/ を削除します
6. 検証に失敗したら、エラーを報告し、修正できるようステージングをそのまま残します

設計の根拠は GitHub の issue、PR、または取り組みの概要に記載します。永続的なパケットファイルには含めません。

昇格後の案内を提示します。

• 「CI をローカルで実行します：bash scripts/lint-skills-frontmatter.sh」
• 「スキルをテストします：現実的なシナリオで /{command-name} を試します」
• 「コントリビュートする場合：スキル提案テンプレートを使って GitHub issue を作成し、その後 PR を作成します」

現在のライブラリリファレンス

このファイルでスキル一覧を手作業で管理しないでください。 以前、この静的な表は実際のカタログとのずれが生じていました（直近では、ファミリー全体が未記載で、別のファミリーでは項目が1つ欠けていました）。新しいスキルを追加したり削除したりするたびに、ここも手作業で編集する必要があるためです。代わりに、実行時に毎回、次のいずれかから最新の一覧を取得してください。

• skill-manifest.json（リポジトリのルート）- 生成される機械可読形式。各スキルの名前、分類、フェーズ（該当する場合）、カテゴリ、説明が記載されています。
• AGENTS.md - 生成される人間が読みやすい形式。同じカタログがファミリーごとに分類され、各スキルの短い説明が付いています。

どちらも、スキルが追加、変更、削除されるたびに node scripts/gen-skill-manifest.mjs（および --agents）によって再生成されるため、手書きの表のようにずれることなく、ディスク上の skills/ と正確に一致します。

参考としてファミリーを以下に示します（ここでは意図的に件数を記載していません。現在の合計数はマニフェストを参照してください）。

ファミリー	フェーズ限定？	ディレクトリの接頭辞	対象
Domain	はい（discover/define/develop/deliver/measure/iterate）	{phase}-	1つのTriple Diamondフェーズに限定されたPM活動
Foundation	いいえ	foundation-	複数のフェーズで使われる横断的な成果物（キャンバス、ペルソナ、OKR、会議資料、ステークホルダーとのコミュニケーション、ビルド前のリスクレビュー）
Utility	いいえ	utility-	リポジトリ、ワークフロー、または他のスキルを操作するメタ／ツール系スキル（このスキルもその1つ）
Tool	いいえ	tool-	ワークショップのファシリテーション形式（Foundation Sprintファミリー、Design Sprintファミリー、単独のファシリテーション形式）

ギャップ分析（ステップ2）では、重複を判定する前に、skill-manifest.json または AGENTS.md をすべて読んでください。ドメインとファウンデーションだけでなく、4つすべてのファミリーを確認してください。提案されたアイデアとフェーズ名を共有するスキルが1つもないため、見落としやすいのはToolファミリーです。

出力要件

ビルダーは、新しいスキルのドラフトファイルを作成する必要があります。

• SKILL.md - スキルの指示一式（近接するスキル名を記載したWhen NOT to Useセクションを含む、C-3）
• HISTORY.md - 最初のバージョンのベースライン行を含むバージョン履歴
• references/TEMPLATE.md - ガイダンスコメント付きの出力テンプレート
• references/EXAMPLE.md - 完全な作成例（150～300行）
• evals/trigger-fixtures.json - ルーティング評価フィクスチャ（C-1、B-4要件）
• evals/output-scenarios/{id}.md - 出力品質シナリオとファミリー別ルーブリック（C-4、B-7要件）
• command.md - スラッシュコマンドファイル

すべてのドラフトは _staging/pm-skill-builder/{skill-name}/（gitignore対象）に書き込みます。

昇格時には、ファイルを正規の場所にコピーし、AGENTS.mdを更新して、ステージングフォルダーを破棄します。

品質チェックリスト

パケットを最終確定する前に、次の両方の段階にあるすべての項目を確認してください。

CI検証（必須）

• name がディレクトリ名と一致している
• 説明が20～100語である（1行で、複数行のYAMLではない）
• license がトップレベルにあり、version と updated が metadata: の下にある。トップレベルには置かない（lint-skills-frontmatter.sh はトップレベルの version、updated、phase、classification を拒否します）
• metadata: の下で分類が正しい（domain → phase:、foundation/utility/tool → classification:。両方を指定しない）
• ディレクトリ名が規則に従っている：{phase/classification}-{skill-name}
• TEMPLATE.mdに##見出しが3つ以上ある
• コマンドファイルが正しいスキルパスを参照している
• AGENTS.mdの項目が#### + **Path:**形式になっている

品質チェック（合格が望ましい）

• ギャップ分析で既存スキルをすべて確認している（同じフェーズだけでなく）
• Why Gateの根拠が具体的である（曖昧な表現ではなく、プロンプト／シナリオを明記している）
• EXAMPLE.mdが概要ではなく、完全な成果物になっている（150～300行）
• HISTORY.mdに最初のバージョンのベースライン行と、それに対応する ## 1.0.0 セクションがある
• 出力要件がドラフトのSKILL.mdに記載されている
• 品質チェックリストがドラフトのSKILL.mdに記載されている

Eval 契約 (C-1..C-4、eval 対応で出荷)

• 最近傍が明示されている (C-2)。When NOT to Use セクションがそれぞれを指している
• 各最近傍から相互の「When NOT to Use」ポインターが追加されている (C-3)。強い重複がある場合は衝突ペアを COLLISION_PAIRS に追加
• evals/trigger-fixtures.json が存在し、B-4 契約を満たしている (16 件以上のクエリ、クラスごとに 8 件以上、ニアミス 2 件以上、train/validation 分割)
• evals/output-scenarios/{id}.md が存在し、既存のルーブリックに対応する scenario/skill/family フロントマターを持つ (または理由を明記して family を延期)
• 衝突プローブをキーなしで実行: check-new-skill-collision.mjs --skill={name} --emit-tasks、その後 pm-skill-router サブエージェント (Haiku) を出力されたクエリに対してディスパッチし、判定を適用する。新しいスキルは自身のトリガーを想起し、最近傍のトリガーを一切奪わない。(無人 CI では代わりに ANTHROPIC_API_KEY を用いた Messages API パスを使用してもよい。)

例

完成した Skill Implementation Packet については references/EXAMPLE.md を参照してください。 現実的なドメインスキル作成を示しています。