k8s-yaml-validator

Kubernetes YAML バリデーター

概要

このスキルは、構文のリント、スキーマ検証、クラスターのドライランテスト、CRD ドキュメントのインテリジェントな検索を組み合わせた、Kubernetes YAML リソースの包括的な検証ワークフローを提供します。クラスターに適用する前に、あらゆる Kubernetes マニフェストを安心して検証できます。

重要：このツールは検証結果の報告のみを行います。 ファイルを変更したり、Edit ツールを使用したり、修正案を提示するために AskUserQuestion を使用したりしないでください。修正案を変更前／変更後のコードブロックで示した、包括的な検証レポートを生成し、次に何をするかはユーザーに委ねてください。

トリガーフレーズ

次のようなプロンプトがあった場合に、このスキルを使用してください。

• 「デプロイ前にこの Kubernetes YAML を検証してください。」
• 「これらのマニフェストをリントして、問題点を報告してください。」
• 「この CRD マニフェストを確認して、スキーマの問題を説明してください。」
• 「このマニフェストにドライランチェックを実行してください。」
• 「複数ドキュメントの YAML で、行単位のエラーを見つけてください。」

このスキルを使用する場面

次の場合に、このスキルを呼び出してください。

• クラスターに適用する前に Kubernetes YAML ファイルを検証する場合
• YAML の構文またはフォーマットのエラーをデバッグする場合
• Custom Resource Definitions（CRD）を扱い、ドキュメントが必要な場合
• Admission Controller のエラーを検出するためにドライランテストを実施する場合
• YAML が Kubernetes のベストプラクティスに従っていることを確認する場合
• マニフェストにある検証エラーを把握する場合（報告のみ。修正はユーザーが手動で行います）
• ユーザーが Kubernetes YAML ファイルの「検証」、「リント」、「確認」、「テスト」を依頼した場合

読み取り専用の境界（必須）

このスキルは、厳密に検証結果の報告のみを行います。

• ユーザーファイルを変更しないでください。
• 修正のために Edit を実行しないでください。
• 修正を適用する許可を求めないでください。
• レポート内で、提案として変更前／変更後のスニペットを提示してください。

決定論的なパスの設定

コマンドを繰り返し実行できるよう、明示的なパスを指定して実行してください。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
SKILL_DIR="$REPO_ROOT/devops-skills-plugin/skills/k8s-yaml-validator"
TARGET_FILE="$REPO_ROOT/<relative/path/to/file.yaml>"

パスの確認：

• REPO_ROOT が空の場合は停止し、リポジトリのルートを尋ねてください。
• SKILL_DIR が存在しない場合は停止し、パスの不一致を報告してください。
• TARGET_FILE が存在しない場合は停止し、正しいファイルを尋ねてください。

検証ワークフロー

次の順序で検証ワークフローを実施してください。各ステージで異なる種類の問題を検出します。

ステージ 0：検証前のセットアップ（リソース数の決定論的な確認）

バリデーターを実行する前に、同梱のスクリプトを使ってドキュメント数を数えてください。

python3 "$SKILL_DIR/scripts/count_yaml_documents.py" "$TARGET_FILE"

出力例：

{
  "file": ".../manifests.yaml",
  "documents": 3,
  "separators": 2
}

ゲートのルール：

• documents >= 3 の場合は、ステージ 1 の前に references/validation_workflow.md を読み込んでください。
• 最終レポートの概要には、必ずドキュメント数を含めてください。
• python3 を使用できない場合は、次の代替手段を使用してください。

awk 'BEGIN{d=0;seen=0} /^[[:space:]]*---[[:space:]]*$/ {if(seen){d++;seen=0}; next} /^[[:space:]]*#/ {next} NF{seen=1} END{if(seen)d++; print d}' "$TARGET_FILE"

また、レポートでは数を estimated として記載してください。

ステージ 1：ツールの確認

検証を開始する前に、必要なツールがインストールされていることを確認してください。

bash "$SKILL_DIR/scripts/setup_tools.sh"

必要なツール：

• yamllint：YAML の構文とスタイルのリント
• kubeconform：CRD に対応した Kubernetes スキーマ検証
• kubectl：クラスターのドライランテスト（任意ですが、推奨）

ツールが不足している場合は、スクリプトの出力にあるインストール方法を表示し、利用可能なツールで処理を続けてください。不足しているツールとスキップしたステージをレポートに記載してください。

ステージ 2：YAML 構文の検証

yamllint を使って、YAML の構文とフォーマットを検証してください。

yamllint -c "$SKILL_DIR/assets/.yamllint" "$TARGET_FILE"

検出できる一般的な問題：

• インデントエラー（タブとスペースの混在）
• 末尾の空白
• 行の長さの違反
• 構文エラー
• キーの重複

報告方法：

• 構文上の問題をすべて、ファイル名と行番号を示して報告してください。
• 修正可能な問題については、提案する変更前／変更後のコードブロックを示してください。
• すべての問題を収集してから報告できるよう、次の検証ステージに進んでください。

ステージ 3：CRD の検出とドキュメントの検索

スキーマ検証の前に、YAML にカスタムリソース定義が含まれているか検出します。

bash "$SKILL_DIR/scripts/detect_crd_wrapper.sh" "$TARGET_FILE"

PyYAML が利用できない場合、ラッパースクリプトは一時的な仮想環境を作成し、Python の依存関係を自動的に処理します。

堅牢な解析： スクリプトは、個々のドキュメントの構文エラーに対して堅牢です。複数ドキュメントを含む YAML ファイルに有効なドキュメントと無効なドキュメントが混在している場合、スクリプトは次の処理を行います。

• 有効なドキュメントを解析し、その CRD を検出する
• 無効なドキュメントのエラーを報告しながら、処理を続行する
• これは、1/3 のリソースに構文エラーがあっても 2/3 のリソースを検証する kubeconform の動作と一致します

スクリプトは、リソース情報と解析ステータスを含む JSON を出力します。

{
  "resources": [
    {
      "kind": "Certificate",
      "apiVersion": "cert-manager.io/v1",
      "group": "cert-manager.io",
      "version": "v1",
      "isCRD": true,
      "name": "example-cert"
    }
  ],
  "parseErrors": [
    {
      "document": 1,
      "start_line": 2,
      "error_line": 6,
      "error": "mapping values are not allowed in this context"
    }
  ],
  "summary": {
    "totalDocuments": 3,
    "parsedSuccessfully": 2,
    "parseErrors": 1,
    "crdsDetected": 1
  }
}

検出された CRD ごとに、次の手順を実行します。

1. まず Context7 MCP を試します（推奨）：

   • ライブラリを解決します。
     • ツール：mcp__context7__resolve-library-id
     • libraryName：CRD プロジェクト名（例：cert-manager.io の場合は cert-manager）
   • ドキュメントを検索します。
     • ツール：mcp__context7__query-docs
     • libraryId：前の手順で解決したライブラリ ID
     • query：CRD の kind、グループ、バージョンを含めます（例：Certificate cert-manager.io v1 required fields in spec）

2. Context7 が失敗するか、詳細が不十分な場合は web.search_query にフォールバックします。

   Search query pattern:
   "<kind>" "<group>" kubernetes CRD "<version>" documentation spec
   
   Example:
   "Certificate" "cert-manager.io" kubernetes CRD "v1" documentation spec
   

3. 重要な情報を抽出します。

   • spec 内の必須フィールド
   • フィールドの型と検証ルール
   • ドキュメントに記載された例
   • バージョン固有の変更や非推奨化

kubeconform による二次 CRD 検出： detect_crd_wrapper.sh で CRD を特定できない場合（たとえば、すべてのドキュメントに構文エラーがある場合）でも、kubeconform が CRD リソースを検証するなら、その CRD のドキュメントを検索してください。kubeconform の出力を解析して検証された CRD を特定し、Context7／web.search_query で検索します。

これが重要な理由： CRD には、標準の Kubernetes 検証ツールでは利用できないカスタムスキーマがあります。CRD の spec 要件を把握することで、検証エラーを防ぎ、リソースを正しく設定できます。

ステージ 4：スキーマ検証

kubeconform を使用して Kubernetes スキーマに対する検証を行います。

kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -strict \
  -ignore-missing-schemas \
  -summary \
  -verbose \
  "$TARGET_FILE"

オプションの説明：

• -strict：不明なフィールドを拒否します（本番環境では推奨。タイプミスを検出できます）
• -ignore-missing-schemas：利用可能なスキーマがない CRD の検証をスキップします
• -kubernetes-version 1.30.0：指定した K8s バージョンに対して検証します

検出される一般的な問題：

• 無効な apiVersion または kind
• 必須フィールドの欠落
• フィールド型の誤り
• 無効な列挙値
• 不明なフィールド（-strict を指定した場合）

CRD の場合： kubeconform が「no schema found」と報告しても、これは想定どおりです。ステージ 3 のドキュメントを使って、spec フィールドを手動で検証してください。

kubeconform の行番号の動作 — 明確に異なる 2 つのケース：

kubeconform はファイル全体を基準とした行番号を報告しません。次のように変換する必要があります。

1. 解析エラー（例：error converting YAML to JSON: yaml: line N）：

   • N はドキュメント相対（そのドキュメントの内容内での行番号）です。
   • ファイル全体を基準とした行番号に変換します：file_line = doc_start_line + N - 1
   • doc_start_line は detect_crd_wrapper.sh の出力にある start_line フィールドから取得します。
   • 例：ドキュメントがファイルの 4 行目から始まり、kubeconform が yaml: line 5 と報告した場合 → ファイル全体を基準とした行番号 = 4 + 5 − 1 = 8 行目（yamllint の出力と一致します）。

2. スキーマ検証エラー（例：got string, want integer）：

   • kubeconform が報告するのは JSON パスのみで、行番号はありません。
   • 例：at '/spec/template/spec/containers/0/ports/0/containerPort': got string, want integer
   • 行番号を特定するには、周辺のコンテキストからファイル全体を基準とした行番号を使い、該当するドキュメントのセクション内でフィールド名（例：containerPort）を YAML ファイルから検索します。

kubeconform のドキュメント相対の出力から変換する場合も、検証レポートでは常にファイル全体を基準とした行番号を提示してください。

ステージ 5：クラスターのドライラン（利用可能な場合）

重要：必ず最初にサーバーサイドのドライランを試してください。 サーバーサイドの検証では、アドミッションコントローラーと Webhook を経由して実行されるため、クライアントサイドよりも多くの問題を検出できます。

判断フロー：

1. Try server-side dry-run first:
   kubectl apply --dry-run=server -f "$TARGET_FILE"

   └─ If SUCCESS → Use results, continue to Stage 6

   └─ If FAILS with connection error (e.g., "connection refused",
      "unable to connect", "no configuration"):
      │
      ├─ 2. Attempt client-side dry-run (parse-only fallback):
      │     kubectl apply --dry-run=client --validate=false -f "$TARGET_FILE"
      │
      │     ├─ If SUCCESS:
      │     │    Document in report: "Server-side validation skipped (no cluster access); client fallback ran in parse-only mode"
      │     │
      │     └─ If FAILS with discovery/openapi error (e.g., "unable to recognize",
      │        "failed to download openapi", "couldn't get current server API group list"):
      │        Document in report: "Dry-run skipped (cluster discovery unavailable)"
      │        Continue to Stage 6
      │
      └─ If FAILS with validation error (e.g., "admission webhook denied",
         "resource quota exceeded", "invalid value"):
         └─ Record the error, continue to Stage 6

   └─ If FAILS with parse error (e.g., "error converting YAML to JSON",
      "yaml: line X: mapping values are not allowed"):
      └─ Record the error, skip client-side dry-run (same error will occur)
         Document in report: "Dry-run blocked by YAML syntax errors - fix syntax first"
         Continue to Stage 6

注： 前のステージ（yamllint、kubeconform）で発生した解析エラーも、ドライランを失敗させます。解析エラーのフォールバックとして、クライアントサイドのドライランを試してはいけません。同じエラーが発生します。ドライラン検証を進める前に、解析エラーを修正する必要があります。

サーバーサイドのドライランで検出できる問題：

• アドミッションコントローラーによる拒否
• ポリシー違反（PSP、OPA、Kyverno など）
• リソースクォータ違反
• ネームスペースの不足
• 無効な ConfigMap／Secret 参照
• Webhook による検証

--validate=false を指定したクライアントサイドのドライランで検出できる問題（フォールバック、コマンドが成功した場合）：

• YAML／JSON の変換およびリクエスト構築の問題
• クライアントモードで kubectl がマニフェストの形式を処理し、送信できるかどうか
• 注： --validate=false はスキーマ、型、必須フィールドの検証を無効にします。また、アドミッションコントローラーやポリシーに関する問題は検出できません。

レポートには、使用したモードを記載してください：

• サーバーサイドの場合：「クラスターの完全な検証を実施」
• --validate=false を指定したクライアントサイドの場合：「限定的な解析のみの検証（クラスターにアクセスせず）— スキーマとアドミッションポリシーは未確認」
• スキップした場合：「ドライランをスキップ — kubectl が利用できません」
• クライアントサイドのフォールバックを試した後にスキップした場合：「ドライランをスキップ（クラスターの検出ができません）」

既存のリソースを更新する場合：

kubectl diff -f "$TARGET_FILE"

これにより、変更内容を確認でき、意図しない変更を見つけやすくなります。

ステージ 6：詳細な検証レポートの生成（レポートのみ）

すべての検証ステージを完了した後、包括的なレポートを生成します。このステージではレポートのみを作成します。

次のことは絶対に行わないでください：

• Edit ツールを使用してファイルを変更しないでください
• AskUserQuestion を使用して問題の修正を提案しないでください
• 修正を適用するかどうか、ユーザーに尋ねないでください
• YAML ファイルを変更しないでください

必ず次のことを行ってください：

• 包括的な検証レポートを生成してください
• 修正案としてのみ、変更前と変更後のコードブロックを示してください
• レポートを確認した後の対応はユーザーに委ねてください
• ユーザーが手動で実行する「Next Steps」で締めくくってください

1. すべてのステージで見つかった問題を表形式で要約します：

   | Severity | Stage | Location | Issue | Suggested Fix |
   |----------|-------|----------|-------|---------------|
   | Error | Syntax | file.yaml:5 | Indentation error | Use 2 spaces |
   | Error | Schema | file.yaml:21 | Wrong type | Change to integer |
   | Warning | Best Practice | file.yaml:30 | Missing labels | Add app label |
   

2. 重要度別に分類します：

   • エラー（修正必須）：構文エラー、必須フィールドの欠落、ドライランの失敗
   • 警告（修正推奨）：スタイル上の問題、ベストプラクティスへの違反
   • 情報（任意）：改善案

3. 各問題について、変更前と変更後のコードブロックを示します：

   各問題について、修正案を示す変更前と変更後の YAML スニペットを明示してください：

   **Issue 1: deployment.yaml:21 - Wrong field type (Error)**
   
   Current:
   ```yaml
           - containerPort: "80"
   

   Suggested Fix:

           - containerPort: 80
   

   理由： containerPort は文字列ではなく整数である必要があります。Kubernetes は文字列の値を拒否します。 参照：k8s_best_practices.md の「Invalid Values」セクションを参照してください。

4. Provide validation summary:

   ## 検証レポートの概要
   
   ファイル：deployment.yaml
   解析したリソース：3（Deployment、Service、Certificate）
   
   | ステージ | ステータス | 見つかった問題 |
   |-------|--------|--------------|
   | YAML 構文 | ❌ 失敗 | エラー 2 件 |
   | CRD の検出 | ✅ 合格 | CRD を 1 件検出（Certificate） |
   | スキーマ検証 | ❌ 失敗 | エラー 1 件 |
   | ドライラン | ❌ 失敗 | エラー 1 件 |
   
   問題の合計：エラー 4 件、警告 2 件
   
   ## 詳細な指摘事項
   
   [上記のように、各問題について変更前と変更後のコードブロックを示します]
   
   ## Next Steps
   
   1. 上記のエラー 4 件を修正します（これらを修正しないとデプロイに失敗します）
   2. ベストプラクティスに沿うため、警告 2 件への対応を検討します
   3. 修正後に検証を再実行し、解決したことを確認します
   

5. Do NOT modify files - this is a reporting tool only

   • Present all findings clearly
   • Let the user decide which fixes to apply
   • User can request fixes after reviewing the report

Objective Stage Gates (Repeatable)

Use this table to keep stage decisions deterministic:

Stage	Required	Command	Pass/Fail Criteria	Fallback
0 Resource Count	Yes	python3 "$SKILL_DIR/scripts/count_yaml_documents.py" "$TARGET_FILE"	Pass when count output is produced and documents is recorded.	Use AWK estimator and mark estimated.
1 Tool Check	Yes	bash "$SKILL_DIR/scripts/setup_tools.sh"	Pass when command runs and tool availability is known.	Continue with available tools and log skips.
2 YAML Syntax	If yamllint available	yamllint -c "$SKILL_DIR/assets/.yamllint" "$TARGET_FILE"	Pass on exit code 0; fail on lint errors.	Skip with explicit reason if missing binary.
3 CRD Detection	If python3 available	bash "$SKILL_DIR/scripts/detect_crd_wrapper.sh" "$TARGET_FILE"	Pass when JSON output includes summary.	Skip CRD extraction and rely on kubeconform clues.
4 Schema	If kubeconform available	kubeconform command from Stage 4	Pass when kubeconform reports valid resources.	Skip and record as coverage gap if missing binary.
5 Dry-Run	If kubectl available	kubectl apply --dry-run=server -f "$TARGET_FILE"	Pass on successful server dry-run.	Attempt parse-only client fallback with --dry-run=client --validate=false; if discovery still fails, mark stage skipped.
6 Report	Yes	Report generation	Pass when summary + per-issue snippets + next steps are provided.	No fallback; this stage is mandatory.

Fallback Matrix

Constraint	Action	Report Language
python3 unavailable	Skip count_yaml_documents.py and CRD parser scripts. Use AWK count only.	Python runtime unavailable; CRD parser skipped, resource count is estimated.
yamllint unavailable	Skip Stage 2; continue with schema/dry-run stages if available.	YAML lint skipped because yamllint is not installed.
kubeconform unavailable	Skip Stage 4; run lint and dry-run only.	Schema validation skipped because kubeconform is not installed.
kubectl unavailable	Skip Stage 5 entirely.	Dry-run skipped because kubectl is not installed.
No cluster connectivity	Run server-side first, then attempt parse-only client fallback with --dry-run=client --validate=false; if it still fails, skip dry-run and continue.	Server-side dry-run unavailable due cluster access; parse-only client-side dry-run attempted (schema checks disabled).
Client dry-run still requires discovery	Treat dry-run as unavailable and rely on lint + schema stages.	Dry-run skipped (cluster discovery unavailable); lint and schema results used.
External docs unavailable	Continue local validation and state documentation gap.	CRD documentation lookup deferred due tooling/network limitation.

Best Practices Reference

For detailed Kubernetes YAML best practices, load the reference:

Read "$SKILL_DIR/references/k8s_best_practices.md"

This reference includes:

• Metadata and label conventions
• Resource limits and requests
• Security context guidelines
• Probe configurations
• Common validation issues and fixes

When to load (ALWAYS load in these cases):

• Schema validation fails with type errors (e.g., string vs integer, invalid values)
• Schema validation reports missing required fields
• kubeconform reports invalid field values or unknown fields
• Dry-run fails with validation errors related to resources, probes, or security
• When explaining why a fix is needed (to provide context from best practices)

Detailed Validation Workflow Reference

For in-depth workflow details and error handling strategies, load the reference:

Read "$SKILL_DIR/references/validation_workflow.md"

This reference includes:

• Detailed command options for each tool
• Error handling strategies
• Multi-resource file handling
• Complete workflow diagram
• Troubleshooting guide

When to load (ALWAYS load in these cases):

• File contains 3 or more resources (multi-document YAML)
• Validation produces errors you haven't seen before or can't immediately diagnose
• Need to understand the complete workflow for debugging
• Errors span multiple validation stages

Working with Multiple Resources

When a YAML file contains multiple resources (separated by ---):

1. Validate the entire file first with yamllint and kubeconform
2. If errors occur, identify which resource has issues by checking line numbers
3. For dry-run, the file is tested as a unit (Kubernetes processes in order)
4. Track issues per-resource when presenting findings to the user

Partial Parsing Behavior

When a multi-document YAML file has some valid and some invalid documents:

Expected behavior:

• The CRD detection script (detect_crd.py) will parse valid documents and skip invalid ones
• kubeconform will validate resources it can parse and report errors for unparseable ones
• The validation report should clearly show which documents parsed and which failed

Example scenario: A file with 3 documents where document 1 has a syntax error:

• Document 1 (Deployment): Syntax error at line 8
• Document 2 (Service): Valid
• Document 3 (Certificate CRD): Valid

Expected output:

• CRD detection: Finds Certificate CRD from document 3
• kubeconform: Reports error for document 1, validates documents 2 and 3
• Report: Shows syntax error for document 1, validation results for documents 2 and 3

In your report:

| ドキュメント | リソース | 解析 | 検証 |
|----------|----------|---------|------------|
| 1 | Deployment | ❌ 構文エラー（8 行目） | スキップ |
| 2 | Service | ✅ 解析済み | ✅ 有効 |
| 3 | Certificate | ✅ 解析済み | ✅ 有効 |

Line Number Reference Style:

• Always use file-absolute line numbers (line numbers relative to the start of the entire file)
• This matches what yamllint, kubeconform, and kubectl report
• Example: If a file has 3 documents and the error is in document 2 which starts at line 35, report as "line 42" (the absolute line in the file), not "line 7" (relative to document start)
• This consistency makes it easy for users to navigate directly to the error in their editor

This ensures users get maximum validation feedback even when some documents have issues.

Error Handling Strategies

Tool Not Available

• Run bash "$SKILL_DIR/scripts/setup_tools.sh" to check availability
• Provide installation instructions
• Skip optional stages but document what was skipped
• Continue with available tools

Cluster Access Issues

• Attempt parse-only client-side dry-run with --dry-run=client --validate=false
• Treat this fallback as transport/parsing signal only (--validate=false disables schema/type/required-field checks)
• If client dry-run still fails with API discovery/openapi errors, skip dry-run and rely on lint/schema stages
• Document limitations in validation report

CRD Documentation Not Found

• Document that documentation lookup failed
• Attempt validation with kubeconform CRD schemas
• Suggest manual CRD inspection:

  kubectl get crd <crd-name>.group -o yaml
  kubectl explain <kind>
  

検証ステージの失敗

• 1 つのステージが失敗しても、次のステージに進んでください
• ユーザーに提示する前に、すべてのエラーを収集してください
• 先行するステージのエラーを優先して修正してください

コミュニケーションのガイドライン

検証結果を提示するときは、次の点に従ってください。

1. 見つかった内容を明確かつ簡潔に伝える

2. 問題が重要な理由を説明する（例：「これにより Pod の作成に失敗します」）

3. 関連する場合は、ベストプラクティスの背景を示す

4. 関連する問題をまとめる（例：ラベルの欠落に関する問題をすべてまとめる）

5. すべての問題について、ファイル名と行番号を示す

6. 修正の複雑さを示す — 問題の見出しに複雑さの指標を含めてください。

   • [Simple]：インデント、誤字、値の変更など、1 行で完了する修正
   • [Medium]：複数行の変更、またはフィールド／セクションの追加
   • [Complex]：ロジックの変更、構成の再編、または複数のリソースに影響する変更

   問題の見出しの形式例：

   **Issue 1: deployment.yaml:8 - Wrong indentation (Error) [Simple]**
   **Issue 2: deployment.yaml:15-25 - Missing security context (Warning) [Medium]**
   **Issue 3: deployment.yaml - Selector mismatch with Service (Error) [Complex]**
   

7. 次の項目を含む包括的なレポートを必ず提示してください。

   • ステージごとの問題をまとめた概要表
   • 各問題の変更前と変更後のコードブロック
   • エラーと警告の合計件数
   • ユーザーが実行する明確な次の手順

8. 修正の適用を提案しないでください — このツールはレポート専用です

   • 「修正しましょうか？」と尋ねないでください
   • 修正の確認に AskUserQuestion を使用しないでください
   • レポートを提示し、対応はユーザーに委ねてください

パフォーマンスの最適化

並列ツール実行

検証を高速化するため、一部のステージは並列で実行できます。

並列で実行可能（依存関係なし）：

• yamllint（ステージ 2）と detect_crd_wrapper.sh（ステージ 3）は同時に実行できます
• 両方のツールは入力ファイルに対して独立して動作します
• スキーマ検証に進む前に、両方のツールの結果が必要です

並列実行の例：

# Run these in parallel (using & and wait, or parallel tool calls):
yamllint -c "$SKILL_DIR/assets/.yamllint" "$TARGET_FILE"
bash "$SKILL_DIR/scripts/detect_crd_wrapper.sh" "$TARGET_FILE"

順番に実行する必要があります：

• ステージ 0（リソース数チェック）→ 他のすべてのステージより前
• ステージ 1（ツールチェック）→ ツールを使用する前
• ステージ 4（スキーマ検証）→ CRD 検出の後（コンテキストに CRD 情報が必要）
• ステージ 5（ドライラン）→ スキーマ検証の後
• ステージ 6（レポート）→ すべての検証ステージの完了後

並列化するタイミング：

• リソースが 5 個を超えるファイルでは、並列実行の効果が最も高くなります
• 小規模なファイル（リソースが 1～2 個）の場合は、順次実行で問題ありません

バージョンの考慮

Kubernetes のバージョン互換性を常に考慮してください。

• 非推奨の API を確認します（例：extensions/v1beta1 → apps/v1）
• CRD の場合、apiVersion がクラスター内のものと一致していることを確認します
• kubectl api-versions を使用して、クラスターで利用可能な API バージョンを一覧表示します
• バージョン固有のドキュメントがある場合は参照します

テストカバレッジのガイダンス

test/ ディレクトリには、すべての検証パスを実行するためのサンプルファイルが含まれています。これらを使用してスキルの動作を検証してください。

テストファイル

テストファイル	目的	期待される動作
deployment-test.yaml	有効な標準 K8s リソース	すべてのステージが成功し、エラーなし
certificate-crd-test.yaml	有効な CRD リソース	CRD が検出され、Context7 の検索が実行され、エラーなし
comprehensive-test.yaml	意図的な YAML 構文エラーを含む複数リソース	構文エラーが検出され、部分的な解析が成功し、CRD が見つかる
schema-errors-test.yaml	意図的なスキーマ型エラーを含む有効な YAML	yamllint は成功し、kubeconform は JSON パスのエラーを 2 件（replicas、containerPort）報告して失敗

テストする検証パス

1. 正常系（すべて有効）
   • ファイル：deployment-test.yaml
   • 期待値：すべてのステージが成功し、レポートに「0 errors, 0 warnings」と表示される
   • コマンド：

cd "$SKILL_DIR"
python3 scripts/count_yaml_documents.py test/deployment-test.yaml
yamllint -c assets/.yamllint test/deployment-test.yaml
bash scripts/detect_crd_wrapper.sh test/deployment-test.yaml
kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -strict -ignore-missing-schemas -summary -verbose \
  test/deployment-test.yaml
kubectl apply --dry-run=server -f test/deployment-test.yaml

2. CRD 検出パス
   • ファイル：certificate-crd-test.yaml
   • 期待値：CRD が検出され、mcp__context7__resolve-library-id と mcp__context7__query-docs が使用される
   • コマンド：

cd "$SKILL_DIR"
python3 scripts/count_yaml_documents.py test/certificate-crd-test.yaml
bash scripts/detect_crd_wrapper.sh test/certificate-crd-test.yaml
kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -strict -ignore-missing-schemas -summary -verbose \
  test/certificate-crd-test.yaml

3. 構文エラーパス
   • ファイル：comprehensive-test.yaml
   • 期待値：yamllint がエラーを検出し、kubeconform が部分的な検証を報告し、ドライランがブロックされる
   • コマンド：

cd "$SKILL_DIR"
python3 scripts/count_yaml_documents.py test/comprehensive-test.yaml
yamllint -c assets/.yamllint test/comprehensive-test.yaml
bash scripts/detect_crd_wrapper.sh test/comprehensive-test.yaml
kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -strict -ignore-missing-schemas -summary -verbose \
  test/comprehensive-test.yaml
kubectl apply --dry-run=server -f test/comprehensive-test.yaml

4. 複数リソースの部分解析
   • ファイル：comprehensive-test.yaml（3 個のリソースがあり、そのうち 1 個に構文エラーがある）
   • 期待値：3 個中 2 個のリソースが検証され、ドキュメント 1 の解析エラーが報告される
   • コマンド：

cd "$SKILL_DIR"
python3 scripts/count_yaml_documents.py test/comprehensive-test.yaml
bash scripts/detect_crd_wrapper.sh test/comprehensive-test.yaml

5. スキーマ検証エラーパス（型の不一致）
   • ファイル：schema-errors-test.yaml
   • 期待値：yamllint は成功し（有効な YAML）、kubeconform は JSON パスのスキーマエラーを 2 件報告して失敗する
   • 注：kubeconform は行番号ではなく JSON パスを報告します。YAML 内でフィールドを手動で確認してください
   • コマンド：

cd "$SKILL_DIR"
python3 scripts/count_yaml_documents.py test/schema-errors-test.yaml
yamllint -c assets/.yamllint test/schema-errors-test.yaml
bash scripts/detect_crd_wrapper.sh test/schema-errors-test.yaml
kubeconform \
  -schema-location default \
  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
  -strict -ignore-missing-schemas -summary -verbose \
  test/schema-errors-test.yaml

6. クラスターにアクセスできないパス
   • kubectl クラスターが設定されていない状態での任意の有効なファイル
   • 期待値：サーバーサイドのドライランが失敗し、解析のみのクライアントサイドフォールバックが試行されます（スキーマは保証されません）。API 検出を利用できない場合は、こちらも失敗することがあります
   • コマンド：

cd "$SKILL_DIR"
KUBECONFIG=/tmp/nonexistent-kubeconfig kubectl apply --dry-run=server -f test/deployment-test.yaml
KUBECONFIG=/tmp/nonexistent-kubeconfig kubectl apply --dry-run=client --validate=false -f test/deployment-test.yaml

7. ツール不足パス
   • PATH からツールを一時的に削除してテストします
   • 期待値：setup_tools.sh が不足しているツールを報告してインストール手順を表示し、利用可能なツールで検証を続行する
   • コマンド：

cd "$SKILL_DIR"
PATH="/usr/bin:/bin" bash scripts/setup_tools.sh

新しいテストファイルの作成

テストファイルを追加する場合：

1. 内容がわかるファイル名を付けます：<scenario>-test.yaml
2. ファイルの先頭にコメントで期待される動作を記載します
3. エラーパステストには意図的なエラーを含めます
4. 標準 K8s リソースと CRD の両方をテストします

想定されるレポートの構成

あらゆる検証において、レポートには以下を含めてください。

• 重要度別の問題件数をまとめたサマリーテーブル
• ステージごとのステータステーブル（合格／不合格／スキップ）
• ドキュメント解析テーブル（複数リソースのファイルの場合）
• 各問題の修正前／修正後のコードブロック
• 修正の複雑さを示す指標（[Simple]、[Medium]、[Complex]）
• ファイル先頭からの行番号
• 「次のステップ」セクション

完了条件

以下の条件がすべて満たされた場合にのみ、検証は完了です。

• ステージゲートが順番に評価され、スキップされた各ステージに理由が記載されている。
• リソース数は count_yaml_documents.py（または記録された AWK の代替手段）から取得されている。
• CRD の検索では mcp__context7__resolve-library-id と mcp__context7__query-docs が使用され、必要な場合にのみ web.search_query が代替手段として使用されている。
• レポートのみという制約が守られている（編集や修正適用のプロンプトがない）。
• 実行した正確なコマンド、重要度別の検出結果、手動で行う次の手順が出力に含まれている。

リソース

scripts/

detect_crd_wrapper.sh

• Python の依存関係を管理するラッパースクリプトです
• PyYAML が利用できない場合、一時的な仮想環境を自動的に作成します
• YAML ファイルを解析するために detect_crd.py を呼び出します
• 使用方法：bash "$SKILL_DIR/scripts/detect_crd_wrapper.sh" "$TARGET_FILE"

detect_crd.py

• YAML ファイルを解析して Custom Resource Definition を特定します
• kind、apiVersion、group、version の情報を抽出します
• プログラムで処理できる JSON を出力します
• PyYAML が必要です（ラッパースクリプトが自動的に処理します）
• 直接呼び出すこともできます：python3 "$SKILL_DIR/scripts/detect_crd.py" "$TARGET_FILE"

count_yaml_documents.py

• 複数ドキュメント形式のファイルに含まれる空でない YAML ドキュメントの数を決定論的に数えます
• ドキュメント数と区切り文字を含む JSON を返します
• ステージ 1 の前に使用して、詳細なワークフローのリファレンスを読み込むかどうかを判断します
• 使用方法：python3 "$SKILL_DIR/scripts/count_yaml_documents.py" "$TARGET_FILE"

setup_tools.sh

• 必要な検証ツールがあるか確認します
• 不足しているツールのインストール手順を提示します
• インストール済みツールのバージョンを確認します
• 使用方法：bash "$SKILL_DIR/scripts/setup_tools.sh"

references/

k8s_best_practices.md

• Kubernetes YAML のベストプラクティスを網羅したガイドです
• メタデータ、ラベル、リソース制限、セキュリティコンテキストを扱います
• よくある検証上の問題とその修正方法を説明します
• 検証エラーの背景情報を提供する際に読み込んでください

validation_workflow.md

• すべてのステージを網羅した詳細な検証ワークフローです
• コマンドオプションと設定を説明します
• エラー処理の方法を説明します
• ワークフローの全体図を掲載しています
• 複雑な検証シナリオで読み込んでください

assets/

.yamllint

• Kubernetes YAML 用に事前設定された yamllint ルールです
• Kubernetes の規約（2 スペースのインデント、行の長さなど）に従います
• プロジェクトごとにカスタマイズできます
• 使用方法：yamllint -c "$SKILL_DIR/assets/.yamllint" "$TARGET_FILE"