confluent-skill-reviewer

confluent-skill-reviewer — Confluent エージェントスキルを監査する

このリポジトリのすべてのスキルが満たすべき3つの基準：

1. Agent Skills 仕様 — フロントマターの形式、命名規則、ディレクトリ構成、トークン予算（https://agentskills.io/specification）。
2. Confluent の規約 — 遅延読み込みされる参照、誤起動防止条項、モードテーブルによる分岐、90％以上の評価、SME + DTX/DevRel の承認（CLAUDE.md、.github/pull_request_template.md）。
3. 評価を契約として扱う — 具体的で検証可能な期待事項を定めた evals/evals.json と、常に同期されたフィクスチャ。

このスキルは、構造化された監査をエージェントに案内し、単一の Markdown レポートを返します。デフォルトでは読み取り専用であり、レビュー対象のスキルを変更することはありません。

事前確認ゲート

指摘事項を提示する前に、次の3点を簡潔に、必ず明示してください。

1. 対象範囲：どのモードで作業していますか？モードの判定を参照してください。不明な場合は、ユーザーに一度だけ確認します。
2. 対象パスの存在：監査する skills/<name>/ ディレクトリを列挙します。該当するものがなければ停止します。
3. ツールの利用可否：リポジトリのルートから bash skills/confluent-skill-reviewer/scripts/run_skill_validator.sh --probe を実行し、外部の skill-validator バイナリがインストールされているか確認します。なければレポートに記載して、ネイティブチェックを続行します。処理を止めてはいけません。

これらのゲートを省略することは、レビューの品質を損なう最も一般的な原因です。早い段階でユーザーが対象範囲を修正できるよう、対象を明確にすることが重要です。

モードの判定

ユーザーの意図／シグナル	モード	実施内容
「この PR をレビューして」「自分のブランチを監査して」、skills/ 以下に未コミットの変更がある、または PR 番号が指定されている	PR-diff	git diff main...HEAD -- skills/ または gh pr diff <N> を実行し、変更されたスキルのみをレビューします。フェーズ E を含む5つのフェーズすべてを実行します
「skills/<name> をレビューして」、単一のスキルパスが指定されている、または単一スキルのディレクトリ内から呼び出されている	Single-skill	1つのスキルを最初から最後まで監査し、フェーズ A～D を実行します
「すべてのスキルをレビューして」、対象範囲の指定がない	Repo-wide	skills/*/ を順に確認し、スキルごとにフェーズ A～D を実行して、指摘事項を重大度別にまとめます

判定できない場合は、ユーザーに一度だけ確認します。"PR の差分、単一のスキル、リポジトリ全体のどれをレビューしますか？" その後、作業を進めます。

チェックフェーズ

フェーズを順番に実行します。指摘事項が発生した場合にのみ、各フェーズの参照資料を読み込みます。重大度タグを付けて、指摘事項をメモリ上の1つのリストにまとめます。

• Blocking — 仕様、CLAUDE.md、または PR テンプレートのゲートに違反しています。マージ前に修正が必要です。
• Warning — 規約に違反していますが、ツールの動作には影響しません。レビュー担当者が判断します。
• Nit — スタイルや明瞭さに関する指摘で、機能への影響はありません。

Phase A — 構造と仕様への準拠

リポジトリのルートから bash skills/confluent-skill-reviewer/scripts/run_skill_validator.sh <skill-path> を実行します。結果は次の3通りです。

• バイナリがインストール済み → スクリプトが出力する skill-validator の JSON を解析します。results[].level == "error" は Blocking、"warning" は Warning に分類します。各指摘の file と line をレポートに記載します。
• バイナリが見つからない → スクリプトは標準エラー出力にインストール方法を表示して、終了コード 0 で終了します。「skill-validator がインストールされていないため、仕様チェックをスキップしました」とレポートに Warning として記載し、ネイティブチェックで仕様を確認します（ルール一覧は references/spec-conformance.md を読み、順に確認します）。
• バイナリが存在するが、スキルが複数含まれている（パスに SKILL.md がない） → スクリプトはスキルごとの JSON を出力します。各エントリを個別に扱います。

その後、バリデーターのチェックが不十分な、このリポジトリ固有のネイティブチェックを行います。

• スキルのディレクトリ名が name: フロントマターフィールドと完全に一致していること。
• evals/ が孤立ファイルとして指摘されないこと（このリポジトリでは evals が必要です。バリデーターを直接実行する場合は --allow-dirs=evals を指定します）。

見慣れない指摘コードの解釈が必要な場合に限り、references/spec-conformance.md を読みます。

フェーズ B — Confluent の規約

CLAUDE.md の § Skill anatomy と § Evals のルールに照らして、SKILL.md を確認します。重要度の高いチェック項目は次のとおりです。

1. 遅延読み込み：SKILL.md に references/ 配下のファイルの内容がインラインで含まれていませんか？References 内にもある見出しや、Reference の内容と重複する長いフェンス付きコードブロックがないか、Grep で確認します。Reference の内容がインライン化されている場合は ブロッキング です。
2. 非トリガー条項：description: に Do NOT trigger for… 条項がありますか？近隣の説明文に共通のキーワードがある場合、その不在は ブロッキング です（フェーズ C で確認）。それ以外の場合は 警告 です。
3. モードテーブルによる分岐：SKILL.md が約 200 行を超える場合、または複数の異なるワークフロー（例：ビルドとデバッグの両方）を扱う場合は、冒頭付近にモード検出テーブルが必要です。不在の場合は 警告 です。
4. Reference の階層：スキルのルートから 1 階層を超える深さにネストされた References は ブロッキング です（仕様で制限されています）。
5. 出所メタデータ：このリポジトリで作成されたスキルでは、metadata.author: confluent、metadata.version（semver）、metadata.last_updated（YYYY-MM-DD）を宣言します。フィールドの欠落は 警告 です。スキルが特定のパッケージ、CLI ツール、または環境へのアクセスを必要とする場合は、compatibility フィールドも必要です。環境要件が明らかなスキルでこのフィールドが欠落している場合は 軽微な指摘 です。
6. プラットフォームのスコープ：name にプラットフォームトークン（confluent-cloud-*、confluent-platform-*、warpstream-*、apache-kafka-*）が含まれる場合、本文の手順はそのプラットフォームに限定する必要があります。すべてのプラットフォームを汎用的に扱っている場合は ブロッキング です。逆に、name にプラットフォームトークンがない一方で、本文にプラットフォームによって異なる操作（Cloud API キー、WarpStream オブジェクトストレージの設定、オンプレミスの SASL）が含まれる場合は、プラットフォーム検出ステップと、プラットフォームごとの Reference ファイル（references/confluent-cloud.md、references/warpstream.md など）が必要です。どちらかが欠けている場合は 警告 です。
7. 実行前の計画提示：リソース（Kafka トピック、スキーマ、Flink ステートメント、コネクター、Terraform の状態）を作成、変更、または削除するスキルでは、リソースを変更する呼び出しを行う前に、「計画を提示し、ユーザーの確認を待つ」手順を明記する必要があります。CRUD が可能なスキルでこの手順がない場合は ブロッキング です。
8. 認証情報の取り扱い：認証情報を読み取るスキルでは、.env ファイルを直接 cat、Read、head、または grep してはいけません。変数名（$BOOTSTRAP_SERVERS）を参照し、test -n "$VAR" で値の有無を確認する必要があります。.env の内容を読み取る SKILL.md または同梱スクリプトは ブロッキング です。認証情報を使用するスキルにガードレールの記述がまったくない場合は 警告 です。
9. 合成データのみを使用：リポジトリのルートから python3 skills/confluent-skill-reviewer/scripts/scan_pii.py <skill-path> を実行して、スキルにコミットされた実在の顧客データやシークレットを検出します。SKILL.md、references/、評価プロンプト、ディスク上のフィクスチャ、同梱スクリプトでは、合成データのみを使用する必要があります。このスクリプトは JSON を出力します。各検出結果をレポートに反映してください。severity: "blocking"（米国の SSN、Luhn 検証を通過する決済カード、AWS キー ID、秘密鍵ブロック）→ ブロッキング、severity: "warning"（example 以外のドメインのメールアドレス、電話番号）→ 警告。CI でも skills/ 全体に対して同じスキャナーを実行するため、ここで問題がなければ CI のゲートも通過できます。

ルールの完全な一覧と PR テンプレートのゲートについては、references/confluent-conventions.md を読んでください。

Phase C — トリガーの重複

（リポジトリのルートから）python3 skills/confluent-skill-reviewer/scripts/check_trigger_overlap.py <root> を実行します。このスクリプトは、リポジトリのルート（<root>/skills/*/SKILL.md をスキャン）または「skills ルート」ディレクトリ（<root>/*/SKILL.md をスキャン）のどちらも受け付けます。evals/mock-skills/ を実行する場合は、後者を使用します。各 SKILL.md のフロントマターを解析し、description: フィールドをトークン化して（confluent、kafka、schema、producer、consumer、topic、stream などのストップワードや分野全般に関わる語句を除外）、キーワードの衝突を報告します。衝突ごとの判定は次のとおりです。

• 相互に相手を名指しするアンチトリガーがない状態で、重複する分野全般に関わる語句以外のキーワードが3個以上（例：「topology」、「rebalancing」、「windowing」） → Blocking
• 相互に相手を名指しするアンチトリガーがない状態で、重複する分野全般に関わる語句以外のキーワードが2個 → Warning
• 分野全般に関わる語句以外のキーワードが1個だけ重複 → Nit
• フィルタリング対象の分野全般に関わる語句だけが重複 → スクリプトは何も報告せずに終了します（これらは衝突ではなく、偶然の一致です）。

アンチトリガー修正の文言を提案する場合に限り、references/trigger-overlap.md を読んでください。このリポジトリ内の既存スキルをもとにした、実例が記載されています。

Phase D — Evals の契約

（リポジトリのルートから）python3 skills/confluent-skill-reviewer/scripts/check_eval_schema.py <skill-path>/evals/evals.json を実行します。このスクリプトは次の項目を検証します。

• トップレベルに skill_name（文字列）と evals（配列）のキーがあること。
• 各 eval に id、prompt、expected_output、files があり、チェック項目が assertions キーの下にあること。このリポジトリでは、assertions に文字列のリストを格納する形式に統一されています。2つの逸脱は現在 Blocking です。旧形式の expectations キー（assertions に名前を変更する必要があります）と、オブジェクト形式のエントリ [{id, type, description, …}]（文字列にフラット化する必要があります）です。
• prompt が抽象的な表現ではなく、現実的なユーザーの言い回しであること（ヒューリスティック：40文字以上で、「Build me an X」だけのような文ではないこと）。短いプロンプトは Warning です。
• assertions[] が具体的であること（ヒューリスティック：動詞と名詞に加え、少なくとも1つの具体的な識別子（ファイルパス、クラス名、設定キー、または「NOT」節）を含むこと）。曖昧なアサーションは Warning です。CLAUDE.md の § Evals are the contract を引用してください。「expectations は、苦労して得た正確性を反映するものです。希望事項ではなく、回帰テストとして扱ってください」。

フィクスチャの同期も照合してください。files: [...] の各エントリは、ディスク上のパス（スキルのルートからの相対パス。スキルに evals/mock-repos/ または evals/mock-skills/ ディレクトリがある場合は、解決できる必要があります。フィクスチャがない場合は Blocking）か、eval 自体にファイル本体を含むインラインのフィクスチャオブジェクト {path, content} のいずれかです（ディスク上では解決されません）。

JSON スキーマ、2種類の expectation 形式、弱い expectation と強い expectation の実例については、references/evals-contract.md を読んでください。

Phase E — PR テンプレートのゲート（PR 差分モードのみ）

単一スキルモードとリポジトリ全体モードではスキップしてください。

現在のチェックリストを確認するため、.github/pull_request_template.md を一度読みます。現在の PR について、各項目を確認します。

PR テンプレートのゲート	確認方法
新しいスキルを反映するようドキュメントを更新	git diff main...HEAD -- README.md docs/。スキルが追加されているのに README のスキル一覧が変更されていない場合は Blocking とします
Evals が90%以上のしきい値で合格	CI ログまたは PR コメントで eval 実行結果を確認します。見つからない場合は、作成者にスコアの貼り付けを依頼します。確認できるまで Blocking です
SME レビュアーを特定	gh pr view --json reviewRequests,assignees を実行します。該当分野（Kafka Streams、Schema Registry など）の SME が少なくとも1名必要です。新しいスキルで指定されていない場合は Blocking です
DTX/DevRel レビュアーを割り当て	同じコマンドを実行します。@confluentinc/dtx または @confluentinc/developer-advocates のレビュアーが少なくとも1名必要です。指定されていない場合は Blocking です

実際のテンプレートでゲートの文言が変更されている場合は、references/confluent-conventions.md の § PR template を読んでください。

レポート形式

Markdown レポートを1つ出力します。重大度ごとに指摘事項をまとめ、フェーズごとにはまとめません。レビュアーは上から順に確認するためです。

# Skill review: <skill name or PR title>

**Mode:** PR-diff | Single-skill | Repo-wide
**Validator:** installed (v1.5.6) | not installed (spec checks done natively)
**Scope:** <list of skills audited>

## Blocking (N)

- `skills/<name>/SKILL.md:14` — Inlined contents of `references/build-templates.md` into the SKILL.md body. CLAUDE.md § Skill anatomy (lazy-load references bullet) requires lazy-loaded references. Move the content back and route to it from a decision point.
- `skills/<name>/evals/evals.json:42` — Eval id 3 references `evals/mock-repos/missing/` which does not exist on disk. Add the fixture or update the path.

## PR-template checklist (PR-diff mode only)

- [x] Docs updated
- [ ] Evals at 90%+ — author has not pasted score
- [x] SME reviewer assigned (@alice)
- [ ] DTX/DevRel reviewer — none assigned

## Summary

Recommend: **request changes** | **approve with nits** | **approve**.

Blocking と Warning の指摘事項がどちらも0件の場合、推奨判定は approve です。Blocking が1件以上の場合は request changes です。

このスキルで行わないこと

• レビュー対象のスキルは編集しません。指摘事項のみです。
• スキル独自の評価は実行しません（ハーネスは ~/.claude/skills/skill-creator/ にあります。90%のスコアを希望する場合は、エージェントが別途実行してください）。
• 実行時やログの挙動は分析しません。これは tools/skill_review_dashboard.py の担当です。
• skills/ 外のファイルはレビューしません（ビルドシステム、Makefile、service.yml、.claude-plugin/ は対象外です。変更された場合は、人間のレビュアーに確認するよう伝えてください）。