add-checkpoints

スキルにチェックポイントを追加する

スキルを分析し、自動評価フレームワーク用の適切な checkpoints.yaml を生成します。

コマンド

/add-checkpoints                    # Analyze current skill directory
/add-checkpoints typo3-docs         # Analyze a specific installed skill
/add-checkpoints --dry-run          # Show what would be generated, don't write

ワークフロー

1. スキルを特定する — SKILL.md、references/、scripts/、assets/ を探します
2. 適合性を分析する — チェックポイントが適切かどうかを判断します（以下の基準を参照）
3. 要件を抽出する — SKILL.md を解析し、検証可能なルールやパターンを特定します
4. チェックポイントを生成する — 機械的なチェックと LLM によるレビューを含む checkpoints.yaml を作成します
5. 前提条件を追加する — このスキルが適用されるプロジェクトの種類を判断します
6. 検証する — ${CLAUDE_PLUGIN_ROOT}/skills/automated-assessment/scripts/validate-checkpoints.sh を実行し、続いてサンプルプロジェクトで ${CLAUDE_PLUGIN_ROOT}/skills/automated-assessment/scripts/run-checkpoints.sh を実行します。警告は検出事項として扱います。警告には、以下に示す欠陥の種類が記載されています。blocked という結果は、ランナーがコマンドの実行を拒否したことを意味します。チェックポイントは実行されていないため、サンプルプロジェクトではなく YAML に欠陥があります。
7. 報告する — 生成した内容とその理由、またはチェックポイントが適さない理由を説明します

適合性の基準

次の内容が定義されているスキルは、チェックポイントに適しています。

• ファイル構成の要件（ディレクトリ、設定ファイル、マニフェスト）
• コンテンツのパターン（含める必要があるもの、含めてはならないもの）
• 命名規則（接頭辞、接尾辞、大文字・小文字のルール）
• ツール設定（PHPStan のレベル、リンターのルール、CI の手順）
• メタデータ標準（ライセンス、作成者、バージョン形式）

次の内容のみを提供するスキルは、チェックポイントに適していません。

• 検証可能な成果物を伴わない概念的なガイダンス
• 永続的な成果物を生成しない対話型ワークフロー
• 実行時の動作パターン（パフォーマンス、キャッシュ戦略）

適合性を、その理由とともに報告します。

チェックポイント生成ルール

機械的なチェック

SKILL.md から、次のようなパターンを抽出します。

• 「存在する必要がある」／「必須」→ file_exists
• 「してはならない」／「決して」／「避ける」→ file_not_exists または not_contains
• 「含める必要がある」／「含めるべき」→ contains または regex
• バージョン／形式の制約 → json_path または command

前提条件

スキルの対象範囲から導きます。

• TYPO3 拡張機能 → file_exists: ext_emconf.php
• Docker プロジェクト → file_exists: Dockerfile
• Go プロジェクト → file_exists: go.mod
• スキルリポジトリ → file_exists: .claude-plugin/plugin.json
• 汎用（任意のプロジェクト）→ 前提条件なし

ID の規則

../automated-assessment/references/migration-guide.md で定められているスキルの接頭辞を使用するか、スキル名から 2 文字の接頭辞を導きます。

重大度の割り当て

• error：「必須」、「必要」、「決して」→ リリースをブロックします
• warning：「すべき」、「推奨」→ 提案です
• info：「検討する」、「あるとよい」→ 任意です

3 種類の欠陥クラス — 生成したすべてのチェックポイントで確認してください

誤った内容を報告するチェックポイントは、チェックポイントがないよりも悪質です。その原因となる形は 3 種類あり、いずれもリリース済みの環境で見つかっていますが、YAML を見ただけでは間違いに気づけません。詳しい根拠と正しい記述例は、次を参照してください。 ../automated-assessment/references/checkpoints-schema.md → 「チェックポイントの誤報につながる 3 種類の欠陥クラス」

1. ベンダーの混入 — vendor/、node_modules/、.Build/ を除外しない find、file_exists の glob、または事前条件です。ランナーの自動除外が適用されるのは、コンテンツチェックの glob ターゲットのみです。それ以外では、除外条件を自分で記述する必要があります。ある事前条件が除外漏れを起こし、RTE コードがない拡張に対して、typo3-ckeditor5 の 14 個すべてのチェックを実行しました。
2. スキル相対のスクリプトパス — bash scripts/check-foo.sh。チェックポイントはテスト対象のリポジトリを起点に実行されますが、そこにはスキルの scripts/ は存在しません。また、許可リストではパス付きのコマンドも拒否されます。ロジックをインライン化してください（複雑な処理には php -r '...' を使用します）。同梱スクリプトは人間が実行するためのエントリーポイントとして残してください。
3. パイプから head への終了コードの罠 — ... | head -1 && echo ... && exit 1 || exit 0 は、すべてのプロジェクトで失敗を報告します。入力が空でも head は 0 で終了するためです。終了ステータスは一致判定に基づくようにしてください（grep -q を使うか、コマンドを使わずに regex_not を指定します）。

キャリブレーションアンカー

各チェックポイントには、予測される欠陥クラスと廃止条件が YAML コメントとして記録されます。記載がない場合、上限は info になります。automated-assessment/references/calibration.md を参照してください。

LLM レビュー

コマンドでは判断できない内容にのみ使用します。行頭がコマンドのプロンプトは mechanical に属します。両方の判定を残す場合は、# mechanical-counterpart: <ID> を付けてください。

• コード品質の判断 → domain: code-quality
• ドキュメントの完全性 → domain: documentation
• アーキテクチャの判断 → domain: architecture

出力

スキルのディレクトリに checkpoints.yaml を生成します（スキーマ：../automated-assessment/references/checkpoints-schema.md）。さらに、assets ディレクトリにもコピーを作成します。

参考資料

• スキーマ：../automated-assessment/references/checkpoints-schema.md
• 移行ガイド：../automated-assessment/references/migration-guide.md
• 既存のチェックポイント：assets/*-checkpoints.yaml（例として）