CloudWatch Logs Insights のクエリ生成スキルを Kiro で作ってみた — 検証ブログを AI 向けナレッジベースに
はじめに
2026年5〜6月にかけて、CloudWatch Logs Insights QLに新コマンド・関数が大量に追加されました。筆者はこれらを実環境で検証してブログ記事を2本書きました。
しかし、検証で得た知見を毎回チャットで口頭説明するのは非効率でした。
| 状態 | 説明 |
|---|---|
| 検証ブログのみ | AI が自動参照しにくい。毎回前提を補足する必要あり |
| スキル化後 | エージェントが自動参照。Critical Rules で誤りを抑制し、検証済みパターンに沿ったクエリを生成 |
本記事では、検証済みの知識をスキルとして構造化するプロセスを紹介します。
プロジェクトへのインストール方法
読者がすぐ試せるよう、先に導入手順を示します。
前提としてKiro CLIのインストールが必要です。インストール方法は Kiro 公式ドキュメント を参照してください。以下の手順はKiro CLI v2.6.1で動作確認しました。
スキルファイル・ナレッジベースの取得
プロジェクトルートにファイルを配置します。
curl -LO https://raw.githubusercontent.com/cm-suzuki-ryo/cloudwatch-logs-query-skill/main/cloudwatch-logs-query-builder.skill.md
curl -LO https://raw.githubusercontent.com/cm-suzuki-ryo/cloudwatch-logs-query-skill/main/cloudwatch-logs-query-languages-reference.md
エージェント定義の作成
.kiro/agents/ ディレクトリにエージェント定義を配置します。
mkdir -p .kiro/agents
cat > .kiro/agents/cw-logs-query.json << 'EOF'
{
"name": "cw-logs-query",
"description": "CloudWatch Logs Insights クエリ生成・実行エージェント",
"prompt": "You are a CloudWatch Logs Insights query expert. Always use the loaded skill and knowledge base when generating queries. Follow all Critical Rules strictly. Prefer verified knowledge in the loaded skill and knowledge base over general model knowledge.",
"allowedTools": ["read", "grep", "glob", "use_aws"],
"resources": [
"file://cloudwatch-logs-query-builder.skill.md",
"file://cloudwatch-logs-query-languages-reference.md"
]
}
EOF
エージェントの起動
kiro-cli chat --agent cw-logs-query
ポイント
resourcesのfile://パスはプロジェクトルートからの相対パスです。エージェント起動時に自動で読み込まれます- 2ファイル合計で約50KB分のテキストがコンテキストに入ります
- 外部リポジトリから取得したスキルファイルはエージェントが参照するコンテキストとして読み込まれます。利用前に内容を確認してください
リポジトリのライセンスはMITです。
スキルの設計思想
スキルは「スキルファイル（.skill.md）」と「ナレッジベース (reference.md)」の2ファイル構成です。
| 観点 | スキルファイル | ナレッジベース |
|---|---|---|
| 役割 | AI の行動指針（何をすべきか/してはいけないか） | 参照データ（辞書・リファレンス） |
| 例 | 「ago() を使うな」「limit を必ず付けろ」 |
limit の構文、now() の戻り値仕様 |
| 人間向けの対応物 | ベストプラクティス集 | リファレンスマニュアル |
ナレッジベースだけでは「関数が存在する」ことはわかっても「いつ使うべきか/使ってはいけないか」の判断ができません。一方、スキルだけではルールがあっても具体的な構文を参照できません。両方を組み合わせることで、検証済み仕様に沿ったクエリを生成できるようになります。
具体例を示します。now() 関数は検証環境でエポック秒（整数）を返すことを確認しており、ナレッジベースにもその旨を記載しています。一方 toMillis(@timestamp) はエポックミリ秒を返すため、単位を揃える必要があります。スキルのCritical Ruleでは「now() * 1000（ミリ秒換算）で toMillis(@timestamp) と比較せよ」と指示しています。
# 生成が期待されるクエリ例
fields @timestamp, @message
| filter toMillis(@timestamp) >= (now() * 1000 - 7200000)
| sort @timestamp desc
| limit 100
スキルなしの場合、AIは filter @timestamp > ago(30m) のような検証環境では動作しなかった関数を使うことが想定されます。また、@timestamp と数値時刻の単位や型を揃えずに比較してしまい、期待通りに絞り込めないクエリを生成する可能性もあります。
作成プロセス
スキルの作成は4つのフェーズで進めました。
Phase 1: 初期作成 — 検証ブログの知見を構造化
- 入力: 検証ブログ2本（5月分・6月分）+ AWS公式ドキュメント
- 出力: スキルファイル + ナレッジベースの初版
- 作業: 手動。ブログの検証結果を「コマンド/関数/構文」に分解し、ナレッジベースとして構造化しました。スキルファイルには言語選択ガイドとクエリパターンを配置しました
この時点では公式ドキュメントの情報も混在しており、未検証の記述がありました。
Phase 2: 実環境での再検証 — 「動く/動かない」の確定
6月分のアップデートで追加された23個の新機能のうち、主要なものをus-east-1およびap-northeast-1で実行しました。
発見した乖離の例
histogram: 第2引数を25/50に変えて実行し、生成される区間がその幅で変化することを確認しました。公式ドキュメントには「number of buckets」とありますが、実環境ではバケット幅として動作しています。
# バケット幅 50 で実行
stats count(*) as cnt by histogram(value, 50)
# 結果例: 入力データに応じて 50, 100 ... のように幅50区切りの値（バケット下限）が表示される
parse XML: parse @message XML as doc でエラーになりました。複数パターンを試行した結果、'/event/level' のようにXML要素のパスを指定する構文で動作することを確認しました。
# ❌ エラーになる構文
parse @message XML as doc
# ✅ 動作確認できた構文（XPath形式）
parse @message XML '/event/level' as xlevel
parse multi: regex形式の multi では、parse @message /regex/ as alias multi がエラーになりました。名前付きキャプチャグループ (?<name>...) を使う必要がありました。
# ❌ エラーになる構文
parse @message /(\w+)=(\S+)/ as key, value multi
# ✅ 動作確認できた構文
parse @message /(?<key>\w+)=(?<value>\S+)/ multi
このほか、ドキュメントに記載はあるが検証時点で期待通りに動作しなかった機能は、スキルの検証済み機能には含めない判断にしました。
品質方針の確立
この検証作業を通じて、「実環境で動作確認できなければスキルには含めない」という品質方針を確立しました。この方針はスキルファイル冒頭のVerification Policyとして明文化しています。
This skill contains ONLY patterns verified against a live AWS environment. When updating, always run queries in a real environment before adding—even if the source is official AWS documentation.
Phase 3: Kiro ウェブ Collaborative モードによる改善
スキルの初版をGitHubリポジトリにpushした後、KiroウェブのCollaborativeモードで改善を進めました。
- Collaborativeモードでスキルリポジトリを読み込み、改善提案を依頼
- 今回の実行では、Sub-agent（planner → coder → Semantic Reviewer → coder）の自動レビューサイクルで改善提案が生成された
- PRが作成される → 技術的正確性を人間が検証 → コメントで指摘 →
/kiro fixで修正
レビューで事実誤認が発見されたケースもありました。
- 「
filterはstatsの後に使えない」というAnti-pattern案が提出された → 実環境テストで使えることを確認 → 集計後の絞り込み（HAVINGに近い用途）としてスキルに追加した - 「
filterIndexは先頭必須」という記述が提案された → 検証環境では先頭以外でも動作した（ただし先頭を推奨）ことを確認 → 表現を修正した
AIが生成した改善提案であっても実環境確認なしに採用してはいけない、という教訓を得ました。このフェーズの具体的な作業フローは下記の記事で紹介しています。
Phase 4: PR ベースの機能追加とリファクタリング
Phase 3以降はGitHub PRフローに移行し、レビューフィードバックを複数ラウンド実施しました。主な変更内容は以下のとおりです。
- Phase 2で未検証だったJOIN/サブクエリ構文の追加検証と追加
- 時刻フィルタリングパターン + 品質ポリシーの明文化
- 優先度ベース構造へのリファクタリング（P1〜P4）
- Power/Skillパターンの適用
最終的なスキルファイルの構造は以下のようになりました。
frontmatter (name, description, keywords, author)
↓
Quick Start (3ステップ)
↓
Critical Rules (MUST/MUST NOT テーブル、11項目)
↓
Priority Index (P1〜P4)
↓
各セクション (P1基本 → P2標準 → P3応用 → P4特殊)
↓
Common Workflows (5パターン)
↓
Command Pipeline Ordering Rules (順序制約テーブル)
↓
Optimization Best Practices
↓
Error Scenarios (症状→原因→修正の逆引き)
Priority IndexはAIクエリ生成における参照頻度順の分類です。P1（時刻・filter・fields・sort/limit・parse）は毎回優先的に参照させたい項目、P4（dedup・expand・unmask等）は利用頻度が低い項目です。スキルファイルが約29KB、ナレッジベースが約21KBあるため、将来的にファイル分割する際の判断基準としても機能します。
構造パターンは Aurora DSQL Skillと aws-observability Powerを参考にしました（いずれもApache-2.0）。frontmatter・Critical Rules・Error Scenariosといった構造を取り入れています。
まとめ
検証ブログを書いていく中で、実環境での検証で得た知見をAIに活用させるには、記事として残すだけでは不十分だと感じました。CloudWatch Logs Insights QLでは、公式ドキュメントの記載と実環境の挙動が異なるケースもあります。AIに対して「使うべき構文」「避けるべき構文」「単位や順序の注意点」を明示的に指示する必要があります。
そこで、検証ブログの知見をスキルファイル＋ナレッジベースとして構造化しました。スキルファイルにはAIの行動ルールを、ナレッジベースには検証済みの構文や仕様を整理しています。
今回の取り組みを通じて、ブログ執筆で得た知見をAIが再利用できる形に変換できました。更新はパブリックリポジトリで公開する予定です。
このスキルの効果（スキルあり/なしの比較検証）は、次の記事で紹介します。
