confluent-skill-creator

Confluent Skill Creator

実際の Confluent 環境（ローカル、Platform、Cloud、または WarpStream）でテストされる、Confluent 製品向けのスキルを構築するための専用スキルクリエイターです。

このスキルは、基本の skill-creator ワークフローを Confluent 固有の要件で拡張します。

• 柔軟なスコープ：ユースケースに特化したスキル（例：「PostgreSQL から Iceberg への CDC」）にも、コンポーネントに特化したスキル（例：「Flink SQL スキル」「Schema Registry スキル」）にもできます
• プラットフォームの指定：スキルは特定のプラットフォーム（スキル内で明記）を対象にするか、プラットフォーム固有の参照ファイルを用意してすべてのプラットフォームに対応します
• 環境テスト：ローカル Confluent、Confluent Platform、Confluent Cloud、または WarpStream に対する実際の E2E テスト
• 安全な CRUD 操作：Confluent リソースを作成または変更する前に、計画全体を提示して確認を得ます
• 認証情報の管理：必要なすべての認証情報に対して、適切に .env ファイルを設定します
• 仕様への準拠：作成したスキルをAgent Skills 仕様に照らして検証します
• スマートなデフォルト：デフォルトでは JSON_SR を使用する Schema Registry（ヘッダー内のスキーマ GUID）

前提条件

• Python 3.9+
• confluent-kafka[avro,json,protobuf]、requests、jsonschema、python-dotenv の Python パッケージ（scripts/requirements.txt を参照）
• E2E テスト用の Confluent 環境（Cloud、Platform、ローカル Docker、または WarpStream）へのアクセス

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

次の内容に関わるスキルを外部ユーザー向けに作成する場合は、このスキルを使用してください。

• Kafka のトピック、プロデューサー、コンシューマー、ストリーミングアプリケーション
• Flink SQL またはストリーム処理
• コネクター（Debezium CDC、シンクコネクターなど）
• Schema Registry（Avro、JSON Schema、Protobuf）
• データレイク連携のための Tableflow
• データベースからデータレイクへの CDC パイプライン
• リアルタイムのデータ拡充または変換

コアワークフロー

1. スコープと対象プラットフォームを理解する（Confluent 固有）
2. 意図を把握してヒアリングする
3. スキルの草案を作成する
4. 仕様への準拠を検証する（Confluent 固有）
5. テスト環境と認証情報を設定する（Confluent 固有）
6. テストケースを作成して E2E テストを実行する（Confluent 固有）
7. ビューアーを使って評価する
8. 満足するまで繰り返す
9. 説明を最適化する
10. パッケージ化して提供する

---

スキルの構成と段階的な開示

作成するすべてのスキルに、次の構造原則を適用してください。これらは、基本となる skill-creator のガイダンスを拡張するものです。ステップ 4の仕様準拠チェックで詳細を検証します。このセクションは、考え方の指針です。

スキルの構成

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled resources (optional)
    ├── scripts/     — executable code for deterministic/repetitive tasks
    ├── references/  — docs loaded into context as needed
    └── assets/      — files used in output (templates, icons, fonts)

段階的な開示 — 3 段階の読み込みシステム

スキルはコンテキストを 3 段階で読み込むため、モデルは必要な情報にだけコストをかけます。

1. メタデータ（name + description）— 常にコンテキスト内に含まれます（約 100 語）。これがトリガーになるため、ここに注力してください。
2. SKILL.md の本文 — スキルがトリガーされるたびに読み込まれます（理想的には 500 行未満）。
3. バンドルされたリソース — 必要に応じてのみ読み込まれます（無制限。スクリプトはコンテキストに読み込まなくても実行できます）。

語数は目安です。スキルに本当に必要な場合は、長くしてもかまいません。

重要なパターン：

• SKILL.md は 500 行未満に保ってください。上限に近づいていますか？階層を追加し、モデルが次に参照すべき場所を明確に示してください。
• SKILL.md から参照ファイルを明示的に参照し、それぞれを「いつ」読むべきかを示してください。SKILL.md からすべてを最初に読み込ませないでください（ステップ 4を参照）。
• 大きな参照ファイル（300 行超）には、先頭に目次を含めてください。

ドメインの構成

スキルが複数のドメインやフレームワークにまたがる場合は、バリエーションごとに整理し、モデルが関連するファイルだけを読めるようにしてください。これは、クロスプラットフォームの Confluent スキル（references/confluent-cloud.md、references/warpstream.md、…）と同じパターンです。

cloud-deploy/
├── SKILL.md          # workflow + variant selection
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

驚きを与えない原則

スキルの動作は、その説明を読んだユーザーを驚かせるものであってはなりません。スキルにマルウェア、エクスプロイトコード、システムのセキュリティを侵害するおそれのあるものを含めてはなりません。また、不正アクセス、データの持ち出し、その他の悪意ある活動を助長してはなりません。「Xとしてロールプレイする」といった無害な創作上の設定は問題ありませんが、ユーザーを欺くスキルや悪意のあるスキルは許可されません。

---

ステップ 1：対象範囲とプラットフォームを決める

スキルの対象範囲

ユーザーが何を作りたいのかを把握します。スキルはユースケース特化型とコンポーネント特化型のどちらでも構いません。

ユースケース特化型 — 特定の問題をエンドツーエンドで解決します。

• 「Flink SQL を使ったリアルタイムの顧客注文データの拡充」
• 「Debezium と Tableflow を使った PostgreSQL から Iceberg への CDC パイプライン」
• 「Kafka Streams を使ったリアルタイムの異常検知」

コンポーネント特化型 — Confluent コンポーネントの機能を扱います。

• 「Flink SQL スキル」
• 「Kafka コネクタースキル」
• 「Schema Registry スキル」
• 「Tableflow スキル」

ユーザーのリクエストが曖昧な場合は、次のように尋ねます。

「このスキルでは何を扱いますか？特定のユースケース（例：『Postgres から Iceberg への CDC パイプライン』）にすることも、コンポーネント（例：『Flink SQL スキル』）に特化することもできます。どのような対象範囲をお考えですか？」

プラットフォームの指定

対象範囲を把握したら、次に対象プラットフォームを決めます。

「このスキルでサポートするプラットフォームを選んでください。

1. サポート対象のすべてのプラットフォーム（Confluent Cloud、Confluent Platform、Apache Kafka、WarpStream）
2. 特定のプラットフォームのみ（例：Confluent Cloud のみ、WarpStream のみ）」

プラットフォームを限定する場合：

• プラットフォーム名をスキルの name フィールドに必ず含めます（例：confluent-cloud-cdc-tableflow、warpstream-producer-optimization）。
• スキルの説明で対象プラットフォームを明示します。
• テストはその特定のプラットフォームに対して実行します。

複数のプラットフォームを対象とする場合：

• スキル名にプラットフォームの接頭辞を含めないでください。
• 生成する SKILL.md に、ユーザーが対象とするプラットフォームを尋ねるプラットフォーム検出ステップを含めます。
• プラットフォーム固有の注意点は references/<platform>.md ファイルに記載します。
  • references/confluent-cloud.md — Cloud 固有の設定、API キー、マネージドサービス
  • references/confluent-platform.md — セルフマネージド環境固有の情報、セキュリティ設定
  • references/apache-kafka.md — OSS のデフォルト設定、マネージド機能なし
  • references/warpstream.md — オブジェクトストレージアーキテクチャ、設定のオーバーライド
• SKILL.md から、条件に応じて次のように参照します：「ユーザーの対象が WarpStream の場合は、references/warpstream.md を読み込み、オーバーライドを適用します」
• 参照パターンについては、agent-skills の PR #27 を参照してください。

対象範囲とプラットフォームを把握したら、インタビューに進みます。

---

ステップ 2-3：意図を把握し、スキルを作成する

意図を把握してスキルのドラフトを作成する際は、基本の skill-creator プロセスに従います。次の点を確認してください。

1. このスキルでユーザーに何ができるようになる必要がありますか？

2. どのようなときに起動する必要がありますか？（ユーザーが使いそうなフレーズ）

3. どのようなコンポーネントが関係しますか？（トピック、スキーマ、Flink、コネクターなど）

4. **このスキルは Confluent とどのように連携する必要がありますか？**ユーザーに次のように尋ねてください。

   「このスキルは Confluent とどのように連携する必要がありますか？

   1. MCP ツール（Confluent MCP サーバー経由 — Confluent リソースの検出、管理、操作）
   2. CLI（Confluent CLI — confluent kafka topic create、confluent flink statement create など）
   3. REST API（Confluent Cloud API、Schema Registry API、Kafka REST Proxy）
   4. クライアントライブラリ（confluent-kafka-python、Java クライアントなど）
   5. 組み合わせ（例：検出には MCP、プロビジョニングには CLI、データ処理にはクライアントライブラリ）」

   回答に基づき、作成するスキルには次の内容を含める必要があります。

   • 必要な具体的なツール／CLI／API の呼び出しと、その実行順序
   • 前提となる設定（MCP サーバーの設定、CLI へのログイン、API キーの作成）
   • 各連携方法のエラー処理

5. 期待する出力は何ですか？（動作するパイプライン、サンプルデータ、SQL ステートメントなど）

スキルを作成する際は、次の点に従ってください。

• 関連する Confluent ドキュメント（docs.confluent.io）へのリンクを含めます
• 具体的な API エンドポイント、CLI コマンド、または MCP ツール名を参照します
• ツール／CLI／API 呼び出しの実行順序を、手順ごとに明確に示します
• 一般的な操作には同梱スクリプトを使用します（scripts/ ディレクトリを参照）
• Confluent のベストプラクティスが推奨される理由を説明します
• スキルが自動的に最新の状態を保てるよう、外部ドキュメントへのリンクを含めます。docs.confluent.io のページに .md 形式がある場合は、.html よりもそちらを優先してください（docs.confluent.io は同じパスでクリーンな Markdown を提供しており、エージェントが扱いやすいためです）。また、公開前にすべてのリンクが有効であることを確認してください。

  For Flink SQL syntax, see [Confluent Flink SQL Reference](https://docs.confluent.io/cloud/current/flink/reference/overview.md)
  

実行前に計画を立てる要件

作成するスキルには、実行前に計画を立てるステップを必ず含めてください。スキルが何らかの操作（トピックの作成、スキーマの登録、Flink ステートメントのデプロイなど）を行う前に、次の手順を実施する必要があります。

1. 実行するすべての操作を番号付きの計画としてユーザーに提示する
2. 使用するツール／CLI コマンド／API 呼び出しと、その実行順序を一覧にする
3. 続行する前に、ユーザーから明示的な確認を得る
4. 承認なしにリソースを変更する操作を実行しない

連携方法の例を含む計画の形式については、plan-template.md を参照してください。

---

ステップ 4：仕様への準拠を検証する

テストに進む前に、作成したスキルが Agent Skills 仕様 に準拠していることを検証してください。

Frontmatter の検証

• name：必須。最大 64 文字。小文字の英字、数字、ハイフンのみを使用し、連続するハイフンは使用しません。親ディレクトリ名と一致させる必要があります
• description：必須。最大 1024 文字。スキルの機能と、使用する状況の両方を説明する必要があります
• プラットフォーム固有の場合：プラットフォーム名を name に含める必要があります（例：confluent-cloud-cdc-tableflow）
• metadata：author: confluent、version（semver 形式の文字列）、last_updated（YYYY-MM-DD）を含める必要があります
• compatibility：スキルが特定のパッケージ、CLI ツール、または環境へのアクセスを必要とする場合は、指定することを推奨します

トリガーの重複チェック

説明を確定する前に、リポジトリ内の既存スキルと意図しない重複がないか確認します。

1. 対象リポジトリの skills/*/SKILL.md を調べ、各スキルの description: フィールドを抽出します
2. 新しいスキルの説明に含まれるキーワードを既存スキルと比較します
3. 大きな重複（共有する一般的でないキーワードが 2 個以上）がある場合は、境界が明確であることを確認します。ユーザーのプロンプトによって、どちらか一方のスキルだけが明確に起動される必要があります
4. 境界が曖昧な場合は、対象範囲の違いが明確になるよう新しいスキルの説明を調整するか、必要に応じて対象外の事項を明記します

構造の検証

• SKILL.md の本文は500行未満にしてください。詳細な内容は references/ に移してください
• SKILL.md に参照ファイルの内容を直接記載しないでください — 参照は必要なときにのみ読み込む遅延読み込みにしてください。参照を直接記載すると、アクティベーションのたびにすべてのコンテキストコストが発生します。
• 参照ファイルは SKILL.md から1階層に配置してください（入れ子になった参照チェーンは不可）
• 300行を超える大きな参照ファイルには、先頭に目次を含めてください
• SKILL.md が約200行を超え、複数のワークフローを扱う場合は、先頭付近にモード判定テーブルを含めてください

必須の成果物

• evals/evals.json — 次の形式に従い、主要なユースケースごとに少なくとも1つのテストケースを用意してください。

  {
    "skill_name": "skill-name",
    "evals": [
      {
        "id": 1,
        "prompt": "realistic user prompt (≥40 chars, specific context, not abstract)",
        "expected_output": "description of success",
        "files": [],
        "assertions": [
          "Specific, verifiable check with a path, identifier, or NOT clause",
          "Another assertion encoding hard-won correctness"
        ]
      }
    ]
  }
  

  評価の品質ルール（confluent-skill-reviewer によって適用されます）：
  • assertions（文字列の配列）を使用してください。これはリポジトリの標準です。expectations やオブジェクト形式の項目（[{id, type, description, …}]）は使用しないでください。check_eval_schema.py でどちらもブロッキングエラーとして検出されます
  • すべての評価に files フィールドを含めてください（フィクスチャがない場合は空の配列 []）
  • プロンプトは40文字以上で、実際のユーザーメッセージのようにしてください（具体的なデータ形式や環境名を指定し、単に「Xを作って」としないでください）
  • アサーションは具体的にしてください。ファイルパス、クラス名、設定キー、NOT 条件、引用符付きの CLI フラグなどを含めてください。「コードの品質が高い」といった曖昧なアサーションは指摘されます
  • 合成データのみ — プロンプト、フィクスチャ、サンプルレコードに、実在する顧客の個人情報やシークレット（SSN、Luhnアルゴリズムで有効なカード番号、AWSキー、秘密鍵、実在するメールアドレスや電話番号）を含めないでください。example.com／.example ドメイン、555-01xx の電話番号、明らかなプレースホルダーを使用してください。PIIと合成データ を参照してください。違反は confluent-skill-reviewer によってブロックされます
• スキルに認証情報が必要な場合は .env.template または credentials.yaml.template
• クロスプラットフォームの場合は references/<platform>.md ファイル（サポートするプラットフォームごとに1つ）

検証を実行する

# If skills-ref is available
skills-ref validate ./created-skill

検証に失敗した場合： 問題を修正してから再度検証してください。スキルの検証に合格するまで、テストに進まないでください。

---

ステップ5：テスト環境と認証情報を設定する

テスト環境を選択する

ユーザーに、テスト対象の環境を尋ねてください。

「どの Confluent 環境をテスト対象にしますか？

1. ローカル Confluent（開発用の Docker）
2. Confluent Platform（オンプレミスのセルフマネージド環境）
3. Confluent Cloud（マネージド SaaS）
4. WarpStream（オブジェクトストレージをバックエンドとする Kafka 互換環境）

注：このスキルが特定のプラットフォームを対象とする場合は、そのプラットフォームでテストする必要があります。」

重要なルール： 特定のプラットフォーム向けに設計されたスキルの場合、テストは必ずそのプラットフォームで実行してください。

セキュリティ：認証情報ファイルの取り扱い

認証情報は .env ファイルまたは YAML ファイル（credentials.yaml）に保存されている場合があります。以下のルールは、スキルが使用するいずれの形式にも適用されます。

重大：認証情報ファイル（.env または credentials.yaml）やその内容を、読み取ったり、表示したり、ログに記録したりしないでください。 セキュリティポリシーの全文については、confluent-best-practices.md を参照してください。主なルール：

• .env または credentials.yaml に対して、cat、Read、head、grep などを決して使用しないでください
• .env の場合：変数名（例：$BOOTSTRAP_SERVERS）を参照し、値は決して読み取らないでください。test -n "$CLUSTER_API_KEY" で確認してください
• credentials.yaml の場合：それを使用するスクリプトまたはプロセス内で読み込んでください（例：実行時の YAML パーサー）。解析した値をログや標準出力に出力しないでください
• 認証情報ファイル（.env、credentials.yaml）を .gitignore に追加してください
• 生成するスキルにも、必ず同じガードレールを含めてください

重大：合成データのみを使用してください。実際の顧客の個人情報や秘密情報を決してコミットしないでください。 評価用プロンプト、フィクスチャ、サンプルレコード、参照例には、作成したデータ（example.com のメールアドレス、555-01xx の電話番号、明らかに架空の ID）を使用してください。実際の SSN、Luhn 検査に合格する決済カード番号、AWS キー、秘密鍵のデータを決して埋め込まないでください。PII and synthetic data を参照してください。パッケージ化する前に、python3 skills/confluent-skill-reviewer/scripts/scan_pii.py <skill-path> でスキルディレクトリを検証できます。

認証情報の設定

環境ごとの認証情報テンプレートについては、credentials reference を参照してください。Kafka、Schema Registry、Flink、Tableflow、Connectors を対象としたテンプレートは、.env 形式と YAML（credentials.yaml）形式の両方で利用できます。スキルに適した形式を選んでください。YAML は入れ子構造や構造化された設定に便利で、.env はフラットなシェル形式の変数に適しています。

---

ステップ 6：テストケースを作成し、E2E テストを実行する

テストケースの構成

各テストケースでは、ユースケース全体をエンドツーエンドで検証してください。CRUD 操作の計画形式については、plan-template.md を参照してください。計画を提示し、リソースを作成する前にユーザーの確認を待ってください。

Schema Registry のデフォルト設定

• デフォルト形式：ヘッダーに Schema GUID を含む JSON（JSON_SR）
• 代替形式：Avro、Protobuf
• JSON_SR から変更するかどうかをユーザーに確認してください：「デフォルトでは、Schema Registry を使用した JSON シリアライゼーション（ヘッダーにスキーマ GUID を含む）を使用します。代わりに Avro または Protobuf を使用しますか？」
• ヘッダー内の Schema GUID の設定詳細については、schema-guid-header.md を参照してください

コンピュートプールの確認（Flink スキルの場合）

Flink 操作を実行する前に、利用可能なコンピュートプールがあることを確認してください：

python scripts/check_compute_pool.py --pool-id $FLINK_COMPUTE_POOL_ID

利用可能なプールがない場合、または容量が上限に達している場合は、ユーザーに通知し、Flink のテストをスキップしてください。

テストの実行

テストの実行には、基本の skill-creator ワークフロー（スキルありとスキルなしでサブエージェントを起動）を使用し、Confluent 向けに調整してください。

スキルありの実行：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Environment: .env file at <workspace>/.env
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save:
  - Consumed data from output topic
  - SQL statements executed (if applicable)
  - Schema definitions
  - Verification logs

ベースライン実行： 同じプロンプトを使用し、スキルなしで、同じ環境で実行してください。

同梱スクリプト

一般的な操作には、scripts/ 内の同梱スクリプトを使用します。

• check_compute_pool.py — Flink コンピュートプールの利用可否を確認します
• produce_data.py — JSON_SR エンコードされたデータをトピックに生成します
• consume_and_verify.py — データを消費し、想定と照合して検証します
• register_schema.py — Schema Registry にスキーマを登録します
• cleanup_resources.py — トピック、スキーマ、Flink ステートメントをクリーンアップします（ローカルのみ）

スクリプトの実行が拒否された場合（例：ヘッドレス／非対話型セッションでは承認手段がない場合）、黙って処理を止めず、以下の手動手順に切り替えます。

• check_compute_pool.py → confluent flink compute-pool CLI または Cloud Console から、プールのステータスを手動で確認します
• produce_data.py → confluent kafka topic produce CLI、または説明文に記載された一時的なプロデューサーのコード例を使用して、JSON_SR エンコードされたレコードを手動で生成します
• consume_and_verify.py → confluent kafka topic consume を使用して手動で消費し、件数／内容を想定と手作業で照合します
• register_schema.py → confluent schema-registry schema create または Schema Registry UI を使用して、スキーマを手動で登録します
• cleanup_resources.py → 各リソースに対応する confluent CLI の削除コマンドを使用して、トピック／スキーマ／ステートメントを手動で削除します（Cloud）。または、環境が一時的な場合はクリーンアップを省略します（ローカルのみ）

パッケージ化する際は、作成したスキルの scripts/ ディレクトリに関連するスクリプトを含めます。独自のスクリプトを同梱する場合は、作成したスキルにも同じ代替手順を記載するようにしてください。

---

ステップ 7～8：評価と反復

基本的な skill-creator の評価ワークフローに従います。

1. テストの実行中に、アサーション（該当する場合）を作成します
2. 実行完了後にタイミングデータを記録します
3. 各実行を評価します
4. ベンチマークを集計します
5. 評価ビューアを起動します
6. ユーザーとフィードバックを確認します
7. フィードバックに基づいてスキルを改善します

Confluent 固有のアサーション — 適切なアサーションでは、以下を確認します。

• 生成／消費されたメッセージ数が正しいこと
• スキーマ互換性（例：前方／後方互換性）
• Flink ステートメントの構文が有効であること
• 出力データが想定される拡充結果と一致すること
• データの損失や重複がないこと
• トピックが正しい設定で作成されていること

---

ステップ 9～10：説明の最適化とパッケージ化

説明の最適化

スキルが適切に動作するようになったら、トリガーとなる説明を最適化します。以下に重点を置きます。

• 具体的なユースケースのキーワード（エンリッチメント、CDC、Tableflow など）
• Confluent 製品名（Flink、Kafka、Schema Registry など）
• よく使われるユーザーの表現（「パイプラインを設定する」、「変更を～からストリーミングする」など）
• プラットフォーム固有の場合：トリガーにプラットフォーム名を含めます

パッケージ化

以下をスキルに同梱します。

• 外部ドキュメントへのリンクを含む SKILL.md（500 行未満）。次の内容を含めます。
  • Confluent が作成したすべてのスキルには metadata.author: confluent
  • metadata.version（例：「1.0」のような semver 形式の文字列）
  • metadata.last_updated（YYYY-MM-DD）
  • スキルに環境要件またはパッケージ要件がある場合は compatibility フィールド
• evals/evals.json — 主要なユースケースごとに少なくとも 1 つのテストケース
• references/ — プラットフォーム固有のファイル（クロスプラットフォームの場合）および Tier 3 の参考資料
• scripts/ — 関連する同梱スクリプト
• 認証情報用の .env.template または credentials.yaml.template

検証ゲート： 提出前に、最後にもう一度 skills-ref validate ./created-skill を実行してください。検証に失敗するスキルは提出しないでください。

PR 提出チェックリスト

スキルを Confluent のスキルリポジトリ（例：confluentinc/agent-skills）に追加する場合は、以下を確認してください。

1. README を更新 — README.md のリポジトリのスキル一覧に新しいスキルを追加します
2. 評価で 90% 以上を達成 — 評価を実行し、PR の説明にスコアを記載します
3. SME レビュアー — スキルの専門領域に関する専門家を特定し、レビュアーとして割り当てます
4. DTX／DevRel レビュアー — DTX または Developer Advocates チームからレビュアーを割り当てます

これらは PR テンプレートで必須のゲートであり、confluent-skill-reviewer によって確認されます。

---

リファレンスファイル

• credential-templates.md — 環境別の認証情報テンプレート（.env および YAML）
• schema-guid-header.md — ヘッダー設定の Schema GUID
• plan-template.md — CRUD 操作の計画形式
• confluent-best-practices.md — セキュリティ、エラー処理、ドキュメント、テストのガイドライン
• example-enrichment.md — エンリッチメントスキルの完全な手順
• 一般的なパターンについては、skill-creator の基本ドキュメントを参照してください