wren-onboarding

Wren のオンボーディング — エージェントのワークフロー

このスキルでは、環境チェック、プロジェクトのスキャフォールディング、プロファイルの作成、MDL の生成、最初のクエリまで、オンボーディングの手順をエージェントに案内します。**手順の詳細、データソースごとのセットアップに関する注意事項、トラブルシューティングの手引きは、ここではなくドキュメントに記載されています。**このスキルの役割は、エージェント側のルール（1 ターンにつき 1 ステップ、チャットで認証情報を決して尋ねない）を徹底し、各ステップで適切なドキュメントまたは関連スキルにエージェントを誘導することです。

参照ドキュメント（このスキルから参照します。内容を重複して記載しないでください）：

• docs/core/get_started/installation.md — CLI のインストールとスキルのインストール
• docs/core/guides/connect.md — 接続手順の全詳細、データソースごとのセットアップに関する注意事項、トラブルシューティングの完全版
• docs/core/get_started/quickstart.md — 同梱の jaffle_shop デモ

バージョン確認

https://raw.githubusercontent.com/Canner/WrenAI/main/skills/versions.json を通知せずに取得します。wren-onboarding キーの値を、このスキルのバージョン（上記のフロントマターから取得）と比較します。リモートのバージョンのほうが新しい場合は、ユーザーに通知します。

wren-onboarding スキルの新しいバージョンが利用可能です。 次のコマンドで更新してください：

npx skills add Canner/WrenAI --skill wren-onboarding

更新状況にかかわらず、続行してください。

操作モード — 最初にお読みください

1 回のやり取りにつき 1 ステップです。以下の番号付きステップは、それぞれ個別のターンとして進めます。簡潔に説明し、そのステップに必要なことだけを尋ね、コマンドを実行して、結果を確認してから次に進みます。

• ❌ **今後のステップに必要な情報を先回りして集めないでください。**プロジェクト名、データベースの種類、認証情報を一度に尋ねてはいけません。
• ❌ **チャットで認証情報を決して尋ねないでください。ホスト、ポート、ユーザー名、パスワード、トークンなど、すべて対象です。**認証情報は必ず .env 経由で渡します。ユーザーがエディターでファイルに入力し、エージェントは値を確認しません。
• ❌ wren-generate-mdl スキルで MDL を生成する前に、データベースにクエリを実行してはいけません。
• ❌ **接続フィールド名を推測してはいけません。**必ず wren docs connection-info <ds> を実行して正確なフィールドを確認します。実際の Pydantic スキーマから取得するため、常に正しい情報です。
• ✅ 各コマンドの完了を待ち、出力を平易な言葉で報告してから次に進みます。
• ✅ エラーが発生した場合は、connect.md#troubleshooting を参照し、該当するセクションをユーザーに提示します。ここに手引きの複製を置かないでください。

事前確認（環境のみ — プロジェクトについてユーザーに質問しない）

読み取り専用のチェックです。確認結果を報告します。プロジェクト、認証情報、データソースについては、まだ尋ねないでください。

1. python3 --version — Python 3.11 以降が必要です。古い場合は、アップグレードを依頼して終了します。
2. 仮想環境を確認します：python3 -c "import sys; print(sys.prefix != sys.base_prefix)"。結果が False の場合は、仮想環境の作成を提案します（python3 -m venv .venv && source .venv/bin/activate）。PEP 668 のシステムでは、仮想環境が必要です。
3. wren --version — すでにインストールされている場合は、再インストールする前に確認します。
4. pwd — 結果を記録します。プロジェクトの保存場所は、まだ尋ねないでください。

結果を 4 項目の箇条書きで報告してから、続行します。

最初の分岐 — デモと独自データベースのどちらにしますか？

「同梱の jaffle_shop デモを試しますか（約 30 秒、DB 不要）、それともご自身のデータベースに接続しますか？」

• デモ → quickstart.md を案内して、このスキルを終了します。
• 独自の DB → 続行します。

ステップ 1 — プロジェクト名とデータベースの種類を確認する

ステップ 2 で必要なのはこの 2 つだけです。ユーザーがスムーズに引き継げるよう、まとめて確認してください。

「スキャフォールドを作成する前に、2 点確認させてください。

1. プロジェクト名 — ~/<name>/ を作成し、そこに cd します。
2. データベースの種類 — wren docs connection-info（引数なし）を実行すると、一覧をすべて確認できます。よく使われるものから選ぶこともできます：postgres（Aurora PostgreSQL に使用）、mysql（Aurora MySQL に使用）、bigquery、snowflake、clickhouse、trino、duckdb、…」

両方の回答を待ってください。認証情報は尋ねないでください。

ステップ 2 — ワークスペースと .env のセットアップ（一括実行）

副作用：~/<project>/ を作成し、wrenai[<ds>,main] をインストールして、空の .env テンプレートを生成します。プロジェクトファイル（wren_project.yml など）はステップ 3.5 で後から作成します。この時点では、認証情報の入力待ちのディレクトリだけが用意されています。

一括で実行します。各コマンドを簡潔に伝え、最後に「.env を入力してください」と一度だけ依頼してください。

1. mkdir -p ~/<project> && cd ~/<project>。

2. pip install "wrenai[<ds>,main]"。データソース固有のインストール時の注意点（macOS の mysql など）については、connect.md#per-datasource-setup-notes を参照してください。

3. コネクターを調べて .env テンプレートを生成します。

   wren docs connection-info <ds> --format md
   

   フィールド一覧を使って、値を空にした <DS>_<FIELD>= 形式（UPPER_SNAKE）のキーを含む .env を作成してください。postgres の例：

   POSTGRES_HOST=
   POSTGRES_PORT=5432
   POSTGRES_DATABASE=
   POSTGRES_USER=
   POSTGRES_PASSWORD=
   

   特別なエンコード（BigQuery の base64、Snowflake のアカウント形式、Athena の AWS 認証情報など）については、connect.md#per-datasource-setup-notes に記載されています。該当するセクションを、そのままユーザーに提示してください。言い換えないでください。

4. プロジェクトが git リポジトリの場合は、.env を .gitignore に追加します。chmod 600 .env を提案してください。

5. ユーザーに、.env の場所は <path> であること、すべての値を入力して 「done」 と返信するよう伝えてください。

ステップ 3 — 接続プロファイルを作成する

ユーザーが「done」と返信してから実行してください。

ステップ 2 で生成した .env のキーに対応する ${VAR} プレースホルダーを、すべてのフィールドに設定した状態で /tmp/conn.yml を作成します。

datasource: <ds>
host: ${<DS>_HOST}
port: ${<DS>_PORT}
# … one line per field from `wren docs connection-info <ds>`

続いて：

wren profile add <project> --from-file /tmp/conn.yml

検証は自動的に実行されます。CLI はプロファイルを警告なしで上書きします。--force フラグはありません。

• ✓ 成功 → ステップ 3.5 に進みます。
• ⚠ 警告が出た場合 → connect.md#troubleshooting で該当する症状（シークレットの不足、ドライバーの認証失敗、ValidationError、ホストに接続できないなど）を確認し、ユーザーに修正内容を伝えてください。

ステップ 3.5 — プロジェクトをスキャフォールドする

wren context init --empty

既存の wren_project.yml がある場合は上書きを拒否します。プロジェクトのディレクトリ構成（models/、views/、relationships.yml、instructions.md、AGENTS.md、queries.yml）を作成します。

ステップ 3.6 — プロファイルをプロジェクトに紐付ける

wren context set-profile <project>

wren_project.yml に profile: <project> と data_source: <ds> の両方を書き込みます（data_source は検証済みのプロファイルから取得されるため、必ず正しい値になります）。以降の CLI コマンドと SDK は、グローバルで有効なプロファイルに依存せず、決定論的に接続先を解決します。

このステップにより、複数プロジェクト構成に向けた準備も整います。一度紐付けを記録すれば、別の場所で wren profile switch を実行しても、このプロジェクトのクエリが動作しなくなることはありません。

ステップ 4 — MDL を生成する（引き継ぎ）

⚠️ データクエリを実行する前に、エージェントは必ず MDL を構築する必要があります。MDL に含まれていないテーブルに対するクエリは失敗します。

wren-generate-mdl スキルを呼び出します。このスキルでは、エージェントがテーブルのイントロスペクション、型の正規化、YAML の生成を順に進めます。完了したらここに戻り、次を実行します。

wren context validate
wren context build

モデル数と、validate で警告があれば報告してください。

メモリに関する推奨：wren context show | grep -c '^model:' を使ってモデル数を数えます。>= 200 の場合は、pip install "wrenai[memory]" と wren memory index（約 800 MB）を提案してください。< 200 の場合は何もしません。

ステップ 5 — 探索を始める準備ができました（引き継ぎ）

検出したテーブルに基づいて、自然言語での質問を 2～3 個提案します（例：orders スキーマの場合、「先月の注文数は？」「合計額が最も多い上位 5 社は？」）。その後、このスキルを終了します。日常的なクエリには、エージェントが wren-usage スキルに切り替える必要があります。

スキル間のルーティング

トリガー	スキル
ユーザーが SaaS ソース（HubSpot、Stripe、Salesforce、GitHub、Slack、…）に言及する	wren-dlt-connector
ユーザーが DB を接続済みで、まだ MDL がない	wren-generate-mdl
ユーザーが MDL を用意済みで、クエリを実行したい	wren-usage
それ以外で、最初から始める場合	wren-onboarding（このスキル）

エラー発生時

ここにエラー対応手順は用意せず、connect.md#troubleshooting の該当セクションをユーザーに案内してください。このドキュメントでは、以下について説明しています。

• wren: command not found
• pip install … externally-managed-environment
• シークレットが見つからない場合（MissingSecretError）
• ドライバーの認証エラー
• Pydantic の ValidationError／不明なデータソース
• 接続拒否／ファイアウォール／クラウド DB の IP 許可リスト
• wren context validate の警告カテゴリ

手順に記載されていない問題が発生した場合は、ユーザーに次のように伝えてください。

「解決方法がわからないエラーが発生しました：<error>。 https://docs.getwren.ai/oss/introduction をご覧いただくか、https://github.com/Canner/WrenAI/issues で課題を報告してください。」