utility-pm-skill-validate

PM スキルの検証

このスキルは、既存の pm-skills スキルがリポジトリの構造上の規約と品質基準を満たしているかを監査します。人が確認でき、utility-pm-skill-iterate が入力として利用できる検証レポートを作成します。

バリデーターは、次の 2 つの段階を確認します。

• Tier 1（構造） - CI と同様の決定論的なチェックです。フロントマター、命名、ファイルの有無、説明の単語数を確認します。
• Tier 2（品質） - LLM が評価する一貫性のチェックです。出力の仕様でテンプレートを参照しているか、例が完全か、チェックリストの項目をテスト可能かを確認します。

使用するタイミング

• utility-pm-skill-builder でスキルを作成した後、リリースする前
• スキルを手動で編集した後、引き続き規約に準拠しているか確認するとき
• utility-pm-skill-iterate を実行する前に、改善が必要な点を特定するとき
• 規約が変更されたときに、更新が必要なスキルを監査するとき（一括モード）
• 投稿されたスキルの品質と完全性をレビューするとき

使用しないタイミング

• 新しいスキルを一から作成するとき → utility-pm-skill-builder を使用してください
• スキルを修正または改善するとき → utility-pm-skill-iterate を使用してください（このレポートを入力として渡します）
• パイプラインで CI チェックを実行するとき → scripts/lint-skills-frontmatter.sh を使用してください（このスキルは、対話形式で CI より詳しく検証するためのものです）
• 1 つのスキルではなく、カタログ全体を監査するとき → utility-pm-skill-auditor を使用してください。このスキルは 1 つのスキルを詳しく調べ、監査ツールはリポジトリ全体を広く調べて、横断的な指摘事項を集約します。

手順

スキルの検証を依頼されたら、次の手順に従います。

ステップ 1：対象を特定する

次のいずれの形式でもスキル名を受け付けます。

• ディレクトリ名：deliver-prd
• フルパス：skills/deliver-prd/SKILL.md
• スラッシュコマンド：deliver-prd

正規のディレクトリパス skills/{name}/ に解決します。

スキルのディレクトリが存在しない場合は、直ちに報告します。

# Validation Report: {input}
Result: FAIL
Skill directory `skills/{input}/` does not exist.

一括モード： 入力が --all の場合は、すべてのスキルに対して Tier 1 の構造チェックを実行し、概要表を作成します（ステップ 5 を参照）。一括モードでは Tier 2 を実行しないでください。

ステップ 2：スキルファイルを読む

スキルのディレクトリにあるすべてのファイルを読みます。

ファイル	必須	目的
SKILL.md	はい	フロントマターと手順
references/TEMPLATE.md	はい	出力テンプレート
references/EXAMPLE.md	はい	作成例
HISTORY.md	いいえ	バージョン履歴（存在する場合）
evals/trigger-fixtures.json	いいえ	ルーティング評価用フィクスチャ（B-4）。ロスタースキルに存在します
evals/output-scenarios/*.md	いいえ	出力品質シナリオ（B-7）。評価対象スキルに存在します

次のファイルも読みます。

• 対応するコマンドファイル：commands/{command-name}.md
• このスキルの AGENTS.md エントリー

ファイルを読み取れない場合（MCP／埋め込み環境）は、続行する前に各ファイルの内容をユーザーに貼り付けてもらいます（「縮退モード」を参照）。

ステップ 3：ティア 1 を実行 — 構造チェック

以下の決定論的なチェックを実行します。それぞれ PASS または FAIL の行が出力されます。

チェック ID	チェック内容	合格条件
frontmatter-at-byte-zero	SKILL.md、references/TEMPLATE.md、references/EXAMPLE.md の1行目が正確に --- であること	1行目が開始を示す --- フェンスであり、その前に HTML コメント、BOM、空白がないこと。重大度：FAIL。参照：library/skill-output-samples/SAMPLE_CREATION.md セクション 5。
name-match	フロントマターの name がディレクトリ名と一致すること	文字列が完全に一致すること
description-present	フロントマターに description が存在すること	値が空でないこと
description-length	説明の単語数	20～100語
version-present	フロントマターに version が存在すること	値が空でなく、有効な SemVer であること
updated-present	フロントマターに updated が存在すること	値が空でなく、ISO 形式の日付であること
license-present	フロントマターに license が存在すること	値が空でないこと
phase-classification	フェーズと分類の整合性	domain には phase:、foundation/utility には classification: があり、両方が記載されていないこと
template-exists	references/TEMPLATE.md が存在すること	ファイルが存在すること
template-sections	TEMPLATE.md に十分な構成があること	## レベル 2 の見出しが3つ以上あること
example-exists	references/EXAMPLE.md が存在すること	ファイルが存在すること
command-exists	commands/ にコマンドファイルが存在すること	ファイルが存在し、正しいスキルパスを参照していること
agents-entry	AGENTS.md にこのスキルのエントリがあること	対応する **Path:** を含むエントリが存在すること
eval-trigger-fixtures	ルーティング用フィクスチャが存在し、形式が正しいこと（B-4）	evals/trigger-fixtures.json が存在する場合：schema:1、skill がディレクトリ名と一致し、クエリが16件以上、各クラス（trigger / no-trigger）が8件以上、near-miss が2件以上あること。存在しない場合：INFO（トリガー評価の対象外、またはフィクスチャが未作成）。正式なゲート：scripts/check-trigger-fixtures.mjs。
eval-output-scenarios	出力シナリオが存在し、形式が正しいこと（B-7）	evals/output-scenarios/*.md が存在する場合：各ファイルに scenario/skill/family のフロントマターがあり、skill がディレクトリ名と一致し、family が既存の docs/internal/eval-rubrics/{family}.md に対応し、本文が100文字以上であること。存在しない場合：INFO（出力評価は未実施）。正式なゲート：scripts/check-output-eval-assets.mjs。
reciprocal-boundary-pointers	宣言された衝突ペアが相互に参照し合っていること（C-5）	このスキルが COLLISION_PAIRS（scripts/check-trigger-fixtures.mjs）に含まれる場合、「When NOT to Use」に各パートナーを記載し、各パートナーの「When NOT to Use」にもこのスキルを記載すること。宣言されたペアの参照が一方向のみの場合は FAIL。どのペアにも含まれない場合は PASS。正式なゲート：scripts/check-reciprocal-boundary-pointers.mjs。

ステップ 4：Tier 2 — 品質チェックを実行する

LLM による評価で、次のチェックを実行します。それぞれ PASS、WARN、または INFO の行が出力されます。客観的な根拠がある場合を除き、Tier 2 の検出結果は WARN が上限です（プレースホルダーの漏れは例外で、FAIL になることがあります）。

チェック ID	評価対象	評価方法	最大重大度
output-contract-coverage	SKILL.md がテンプレートを参照している	Output セクションに references/TEMPLATE.md への明示的な参照、または "use the template" があるか確認します。どちらのパターンも有効として扱います。テンプレートがまったく参照されていない場合にのみ WARN とします。	WARN
checklist-verifiability	品質チェックリストの項目が検証可能である	各チェックリスト項目を確認します。「品質が良い」のような曖昧な項目と、「指標が測定可能である」のような具体的な項目を判別します。曖昧な項目が 2 つ以上ある場合は WARN とします。	WARN
example-completeness	EXAMPLE.md がテンプレートの全セクションを埋めている	TEMPLATE.md の ## 見出しと EXAMPLE.md の ## 見出しを比較します。EXAMPLE.md にテンプレート内のセクションが欠けている場合は WARN とします。未解決のプレースホルダーも確認します。行数は情報提供のみを目的として報告し、判定条件にはしません。	WARN
template-example-alignment	EXAMPLE.md が TEMPLATE.md の構成に沿っている	セクション見出しの順序を比較します。EXAMPLE.md のセクションの順序が異なる場合、または異なる見出し名を使っている場合は WARN とします。	WARN
description-actionability	Description にスキルをいつ使うかが記されている	frontmatter の description に "Use when..." や "Use for..." のようなトリガー句があるか確認します。description がスキルの機能だけを説明し、いつ使うかを示していない場合は WARN とします。	WARN
instruction-clarity	手順に番号が付いており、命令形になっている	Instructions セクションに ### Step 見出し、または番号付きリストのパターンがあるか確認します。手順が明確なステップ構成のない文章段落になっている場合は WARN とします。	WARN
placeholder-leakage	出荷されるファイルに不要なひな形が残っていない	SKILL.md、TEMPLATE.md、EXAMPLE.md をスキャンし、次の項目がないか確認します：[Placeholder] または [Feature Name] のパターン、`` HTML コメント（ライセンスヘッダーを除く）、削除すべきテンプレート用ガイダンスの引用ブロック、「TODO」や「FIXME」などの作成者向けメモ。いずれかが見つかった場合、客観的な根拠に基づき FAIL とします。	FAIL
when-not-to-use	「When NOT to Use」セクションがあり、類似スキルを挙げている	スキルの最も近い類似スキルを挙げている（代わりにどのスキルを使うべきかを示す）When NOT to Use セクションがあるか確認します。セクションがない場合、または存在しても一般的な説明だけで類似スキルが挙げられていない場合は WARN とします。これは v2.26.0 の書き直しで慣例となり、相互参照ゲートを支えています。reciprocal-boundary-pointers（Tier 1）は、明示された競合ペアに対する決定論的なバックストップです。	WARN

品質基準の位置づけ： これらのチェックでは、現行ライブラリの規約、つまり現在出荷されているライブラリの実態に照らして検証します。WARN または INFO と判定された検出結果は、utility-pm-skill-builder を使って構築された新しいスキルが満たしている v2.8 品質基準を示します。古いスキルは、ライフサイクルを通じて更新されるまでは、これらの検出結果を受けることがあります。

見出しと方言の規約： 方言（classic、contract-shaped、tool-family）ごとの正式なセクション構成、および正式な見出しの正確な表記については、スキル作成ガイドの Skeleton Canon: The Three Sanctioned Dialects を参照してください。見出しまたはセクション構成がその方言の規範から逸脱しているスキルは、上記の Tier 1 チェックでカバーされていない場合でも、Recommendations で指摘してください。scripts/check-heading-canon.mjs は、最終的に決定論的なバックストップとなる予定です。カタログ全体の標準化が完了するまでは、助言目的で出荷されます。

ステップ 5：検証レポートを作成する

次の正確な構成でレポートをまとめます。F-11（utility-pm-skill-iterate）は、セクション見出しとパイプ区切りのフィールドでこのレポートを解析します。

# Validation Report: {skill-name}
Date: {YYYY-MM-DD}
Skill version: {version from frontmatter}
Validator version: 1.0.0
Report schema: v1
Result: {PASS | WARN | FAIL}

## Summary
{1-2 sentence overall assessment.}
Errors: {n} | Warnings: {n} | Info: {n}

> Tier 2 findings are heuristic quality assessments and may require human review.

## Structural Checks
- {STATUS} | structural | {check-id} | {message}
- {STATUS} | structural | {check-id} | {message}
...

## Quality Checks
- {STATUS} | quality | {check-id} | {message}
- {STATUS} | quality | {check-id} | {message}
...

## Recommendations
1. {STATUS} | {check-id} | Target: {file-path}
   Action: {what to do}
2. {STATUS} | {check-id} | Target: {file-path}
   Action: {what to do}
...

レポートのルール：

• Result = 検出された最も重大な重大度：FAIL が1つでもあれば FAIL、そうでなければ WARN が1つでもあれば WARN、それ以外は PASS。
• Structural Checks：Tier 1 のチェックごとに1行記載します。STATUS は PASS または FAIL です。
• Quality Checks：Tier 2 のチェックごとに1行記載します。STATUS は PASS、WARN、または INFO です。
• Recommendations：合格しなかったチェックのみ記載します。各推奨事項には、チェック ID、対象ファイルのパス、具体的な対応を含めます。
• すべてのチェックに合格した場合、Recommendations セクションには「問題は見つかりませんでした。」と記載します。
• 合格したチェックは Recommendations から省き、対応が必要な指摘事項のみ列挙します。

バッチモードの出力（入力が --all の場合）：

すべてのスキルを対象に、Tier 1 の構造チェックのみを実行します。次の概要テーブルを作成します。

# Batch Validation Summary
Date: {YYYY-MM-DD}
Validator version: 1.0.0
Report schema: v1
Skills checked: {n}

| Skill | Result | Errors | Warnings |
|-------|--------|--------|----------|
| deliver-prd | PASS | 0 | 0 |
| define-hypothesis | WARN | 0 | 1 |
| foundation-persona | FAIL | 1 | 0 |
...

Skills passing: {n}/{total}
Run `utility-pm-skill-validate {skill}` for a detailed report.

制限モード

スキルファイルを直接読み取れない場合（例：MCP 経由で実行している場合や、ファイルシステムにアクセスできない組み込み環境の場合）：

1. 必要な各ファイルの内容をユーザーに提供してもらいます。
   • skills/{name}/SKILL.md
   • skills/{name}/references/TEMPLATE.md
   • skills/{name}/references/EXAMPLE.md
2. 提供された内容に基づいて、すべてのチェックを実行します。
3. レポートに「ユーザー提供の内容に基づいて検証しました（ファイルシステムを利用できません）。」と記載します。
4. 制限モードではバッチモードを利用できません。単一のスキルのみを対象とします。

出力仕様

バリデーターは、ステップ 5 の形式に従った検証レポートを必ず作成する必要があります。

レポート：

• 正確なセクション見出し ## Summary、## Structural Checks、 ## Quality Checks、## Recommendations を使用します。
• パイプ区切りのチェック行 STATUS | TIER | CHECK-ID | message を使用します。
• パイプ区切りの推奨事項 STATUS | CHECK-ID | Target: path を使用し、 次の行に Action: description を記載します。
• F-11 との互換性のため、ヘッダーに Report schema: v1 を含めます。
• Summary セクションに Tier 2 の注意書きを含めます。

品質チェックリスト

レポートを提出する前に、次の項目を確認します。

• eval アセットのチェック（eval-trigger-fixtures、eval-output-scenarios、reciprocal-boundary-pointers）を含む、すべての Tier 1 構造チェックが実行されている（省略されていない）。eval アセットが存在しない場合は FAIL ではなく INFO とする。ただし、衝突ペアが一方向のみ宣言されている場合は FAIL とする。
• すべての Tier 2 品質チェックが実行されている（省略されていない）。ただし、単一スキルモードのみ。
• レポートがステップ 5 の正確なセクション形式と行形式に従っている。
• 合格しなかったすべてのチェックが、対象ファイルのパスとともに Recommendations に記載されている。
• Result フィールドが、検出された最も重大な重大度を反映している。
• Tier 2 の指摘事項は WARN 以下に制限されている（placeholder-leakage は FAIL になる場合があります）。
• 客観的な根拠がない限り、Tier 2 のチェックが FAIL と判定されていない。

例

実際に公開済みのスキルに対して Tier 1 と Tier 2 の両方のチェックを実施した検証レポートの例については、references/EXAMPLE.md を参照してください。