wix-headless

Wix Headless

このスキルは、Wix のビジネスサービスをWix Headless フロントエンドに接続します。主な役割は、必要な機能を推定し、Wix アプリをインストールし、バックエンドのコンテンツを初期登録して、フロントエンドから Wix を呼び出す方法を説明する SDK 統合ガイドを作成するなど、Wix バックエンドを設定することです。

フロントエンドをどう扱うかは、プロジェクトの種類と操作によって異なります。

• バックエンドのみ（セルフマネージド、stripe、または「バックエンドだけを設定する」マネージド実行） — スキルは最終出力としてSDK ガイドを出力します。フロントエンド、ビルド、ホスティングはホストが担当します。
• マネージドの作成／接続 — スキルはフロントエンドも担当します。新しいプロジェクトをスキャフォールド（作成）するか、既存のプロジェクトに Wix を接続（connect）し、同じガイドを使ってバックエンドと連携させ、ビルドして Wix にリリースします。（デザイナーやテンプレートライブラリはありません。フロントエンドは目的に応じてその場で構築します。）

バックエンドのみの実行では、スキルはプロジェクトのスキャフォールディングを担当しません。 フロントエンドが必要な場合は、ユーザーの意図に従ってスキャフォールドしてください。フレームワークと構成はプロンプトに従います。スキルの役割は、Wix バックエンドと、既存のフロントエンドから Wix を呼び出す方法を説明する出力済み SDK ガイドであり、アプリの選定や生成ではありません。これは stripe 実行の標準的な方法です。プロジェクトは Stripe Projects 経由でプロビジョニングされ（認証情報は .env に入ります。stripe/AUTHENTICATION.md を参照）、スキルがバックエンドを設定してガイドを出力し、stripe/DEPLOYMENT.md に従ってライブサイトを仕上げます。その間、フロントエンドのスキャフォールドと意図に沿った連携はホストが担当します。

プロジェクトの種類

認証とデプロイだけは references/ 内の種類別フォルダーに分離されており、それ以外ではスキルの動作はすべてのプロジェクトの種類で同一です。

プロジェクトの種類	ホスティング	認証とデプロイの保存場所
managed	Wix のインフラストラクチャ（Wix が保守）	references/managed/
self-managed	ユーザー自身のホスト（未定）	references/self-managed/
stripe	Stripe Projects 経由でプロビジョニングされた、ユーザー自身のホスト	references/stripe/

それ以外のすべて（Discovery、Setup、Seed、SDK の引き継ぎ）はプロジェクトの種類に依存せず、特定の方式ではなく「提供された認証メカニズム」を参照します。

プロジェクトの種類の解決

Discovery の前に、次の順序で種類を解決してください。判断できた時点で、それ以降は確認しません。

1. 呼び出し元からの指定。 ホスト／呼び出し元からプロジェクトの種類（managed | self-managed | stripe）が渡された場合は、それを使用します。明示された値が常に優先されます。
2. プロジェクトのシグナルから検出（ディスク上）。 作業ディレクトリを読み取り専用で確認します。
   • stripe — .env に WIX_WIX_CLIENT_ID / WIX_WIX_CLIENT_SECRET / WIX_WIX_METASITE_ID（またはプレーンな WIX_* のフォールバック）が含まれています。これは Stripe Projects を示す指紋です。
   • managed — Wix CLI プロジェクトです。wix.config.json が存在するか、.wix/ ディレクトリがあるか、または package.json に @wix/cli / @wix/astro が含まれています。
   • self-managed — ディスク上にフロントエンドプロジェクトがあり（例：バンドラー／フレームワークを含む package.json）、Stripe の .env の指紋も上記の Wix CLI マーカーもありません。
3. ユーザーの意図から検出。 ディスク上の情報で判断できない場合は、プロンプトを確認します。
   • managed — 「managed」「host on Wix」「Wix-hosted」「deploy to Wix」「wix release」。
   • stripe — 「stripe projects」「I added Wix via Stripe」、Stripe Projects に関するコンテキスト。
   • self-managed — 「self-hosted」「my own host」、Wix 以外のホスト名、「I'll deploy it myself」。
4. 質問する。 シグナルがない、または矛盾する場合は、どの種類が該当するかユーザーに確認してください。推測しないでください。

解決した種類はスクラッチ領域に保持します。これは <TYPE_DIR> の選択に使われます（パスの解決を参照）。self-managed は未定です。これに解決された場合、認証ステップは「まだ接続されていません」という明確なエラーで停止します。

オペレーションの解決（managed のみ）

create／connect／iterate はmanaged のみです。managed の場合は、オペレーションをまず意図から、次にディレクトリから解決します。空のディレクトリを、ユーザーの要望より優先してはいけません。明確なディスク上のシグナルで判定できる iterate を最初に確認します。

• iterate → references/managed/CONNECT.md。プロジェクトはすでに Wix に接続済みです。wix.config.json（または .wix/）がすでに存在し、所有者は機能の追加または変更を希望しています。フローは connect と同じですが、§1 では init をスキップし、既存の wix.config.json を再利用します。接続済みのプロジェクトで init を再実行してはいけません。
• connect → references/managed/CONNECT.md。ユーザーは、まだ Wix に接続されていないデザインを持ち込み、接続したいと考えています。ディスク上にある wix.config.json のないフロントエンドプロジェクト、または持ち込まれた／取得されたデザイン（展開または読み込む .zip／フォルダー／ファイル、デザインファイルの URL、Claude-Design／v0／Lovable のエクスポート）、または「これを接続して／このデザインを実装して（…Wix に接続）／これを Wix でホストして／これを Wix にデプロイして／このプロジェクトに Wix Headless を追加して」といった表現が該当します。持ち込まれた、または取得されたデザインは、現在のディレクトリが空でも connect です。デザインは別の場所から届く（zip／取得／URL）ため、処理開始時に空であることは create のシグナルではありません。（CONNECT.md の手順 1 では、持ち込まれたデザインを CWD に配置してから init します。）
• create → references/managed/CREATE.md。ユーザーは、何も持ち込まずに、プロンプトから新しいサイトを構築したいと考えています。「サイト／ストア／ブログを作って…」のように、デザインファイルもディスク上のプロジェクトもありません。
• backend-only — ユーザーはバックエンドの設定のみを希望しています（フロントエンド作業はありません）。→ 共通の基盤を使用し、SDK の引き継ぎ情報を出力します。

self-managed と stripe では、オペレーションは常に backend-only です（ホストがフロントエンドを管理します）。持ち込まれたデザインがなく、connect を示す表現も実際にない場合に限り、ディレクトリが空かどうかで判定します。空 → create、ディスク上に既存のフロントエンドがある → connect。

前提条件（ホストが用意するもの — 読み取りのみ行い、作成はしません）

1. プロジェクトの種類 — managed | self-managed | stripe。呼び出し元から提供されます。それ以外の場合は、プロジェクトのシグナル／ユーザーの意図から検出します（Project types §「プロジェクトの種類の解決」を参照）。それでも特定できない場合は、ユーザーに確認します。これによって <TYPE_DIR> を選択します（Path resolution を参照）。
2. Wix メタサイトと headless OAuth アプリが存在し、認証情報を利用できること — プロジェクトの種類に応じた AUTHENTICATION.md を通じて取得します。このスキルには、メタサイトへの認証に使用できるベアラートークンとメタサイト ID が必要です。
3. ユーザーの意図 — Wix に何を担わせるかを説明する自由形式のテキスト（「ストアを追加する」「ブログと問い合わせフォーム」「アプリのデータを永続化する」など）。
4. (任意) ディスク上のプロジェクト — ブランドや機能をより正確に推測するために、読み取り専用で参照します。

認証情報がない場合、Wix バックエンドに接続できません。明確なエラーを示して停止してください。

このスキルの動作

必ず最初に DISCOVERY.md を開きます（認証に依存せず、機能／ブランド／意図の推測と画像の判定を行います）。その後、プロジェクトの種類とオペレーションに応じて処理を振り分けます。

Backend-only（self-managed、stripe、または managed の backend-only） — 簡潔な基本フローです。

1. Discovery（references/DISCOVERY.md） — 機能、ブランド、意図、画像を推測します。
2. Setup（references/SETUP.md） — 必要な機能に応じて Wix アプリをインストールします。
3. Seed（references/SEED.md） — バックエンドのコンテンツを作成します（画像を使う場合はエンティティ画像も作成します）。
4. Handoff（references/SDK_HANDOFF.md） — Setup と Seed の後に、SDK の初期化、機能ごとの呼び出し形式、シードされた ID、@wix/* パッケージの一覧を含む統合ガイドを出力します。
5. Finalize deployment（<TYPE_DIR>/DEPLOYMENT.md） — プロジェクトの種類に応じた最終処理の手順を実行します。 実行中はいつでも — ユーザーがWixへのフィードバック送信を求めた場合、不満を述べたり苛立ちを示したりした場合、または実行中に実際の障害（わかりにくいエラー、ドキュメントの不足、ツールで行き詰まった状況、考案する必要があった回避策など。繰り返し発生する必要はありません）があった場合は、references/FEEDBACK.mdに従ってWixに伝えることを提案してください。尋ねられるまで待つのではなく、こちらから提案するのが基本です。各フローの最終ステップ（<TYPE_DIR>/DEPLOYMENT.md / managed/CREATE.md / managed/CONNECT.md）には、同じチェックポイントがあります。これは任意ではなく、必須の自己確認として扱ってください。明示的に了承を得た後にのみ送信し、自動で送信してはいけません。

Managedの作成／接続／反復 — Discovery後、実行全体をManagedフローに引き継ぎます。

• create → references/managed/CREATE.md（スキャフォールド → Setup → Seed → フロントエンドの構築 → リリース）。
• connect → references/managed/CONNECT.md（init → Setup → Seed → 既存UIの接続 → リリース）。
• iterate → references/managed/CONNECT.md — プロジェクトはすでに接続済みなので、既存のwix.config.jsonを再利用します（initは不要です）。Setup / Seed / 接続は段階的に行います。以前の実行ですでにセットアップやシードが済んでいる場合があるため、エージェントはまず現在の状態を確認し（インストール済みのアプリ、すでにシード済みのコンテンツ、既存の接続）、新しい要件に必要な差分のみを適用します。再インストールや再シードを無条件に行ってはいけません。フロントエンドのビルド出力が変更された場合にのみ、再リリースします。 これらのフローでは同じSETUP.md/SEED.md/SDK_HANDOFF.mdを再利用しますが、SDKガイドを出力するのではなく、それを適用してフロントエンドを構築／接続し、managed/DEPLOYMENT.mdを通じてリリースします。

Wixへの各呼び出しでは、<TYPE_DIR>/AUTHENTICATION.mdに従って取得した$TOKEN/$SITE_IDを使い、共通の呼び出し形式（SETUP.md §1）に従います。スキルは非対話で実行されます。ただし、画像に関する質問が1つある場合と、プロジェクトの種類を判定できない場合にその種類を尋ねる場合を除きます。

ユーザーから確認を求められない限り、フロントエンドをローカルでスモークテストしないでください。 納品物はビルドしてリリースしたサイト（Managed）またはSDKガイド（バックエンドのみ）であり、ローカルテストのレポートではありません。ページへのcurl、カート／予約／ログインの操作、ヘッドレスブラウザーの起動のために、基本的には開発サーバー（wix dev / astro dev / npm run dev）を起動しないでください。正しさは手順に従うことで担保され、実際のエラーはwix build / wix releaseで表面化します。また、ヘッドレス実行では対話型ログインも実際の支払いも完了できません。そのため、こうしたループはほとんど情報が得られないまま、壁時計時間を日常的に数分消費します（これは「最後に一度だけリリースする」というルールとは別であり、これに加えて適用されます。そのルールが禁止するのは余分なビルド＋リリースのサイクルのみで、開発サーバーによるテストではありません）。開発サーバーを起動してスモークテストを行うのは、ユーザーのプロンプトで検証／テスト／動作確認を明示的に求められた場合のみとし、その場合も1回の軽量な確認（ページがコンパイルされ、レンダリングされること）にとどめてください。購入／予約／ログインの一連の操作をすべて実行してはいけません。<TYPE_DIR>/DEPLOYMENT.mdに記載されたリリース後の確認が、許可された検証です。

スモークテスト方針に対する寄付の例外： 寄付を受け付けるビルドの場合は、動作すると宣言する前に、references/inline-recipes/how-to-code-donations.mdに記載された、範囲を限定した匿名APIの引き継ぎ確認を行ってください。これによって支払いやキャンペーンの変更が許可されるわけではなく、開発サーバーでのテストループも必要ありません。このレシピでは、ホスト型チェックアウトと支払いの確認についても個別に定義しています。

パスの解決

このファイルから <SKILL_ROOT> を算出します（<SKILL_ROOT>/SKILL.md の /SKILL.md を取り除きます）。絶対パスをスクラッチ領域に保持します。次に、プロジェクトタイプをフォルダーに解決し、そのパスも保持します。

<TYPE_DIR> = <SKILL_ROOT>/references/<projectType>/ — managed/、self-managed/、stripe/ のいずれかです。

項目	パス
縦型インデックス（インテントの照合＋縦型ごとのサイト仕様）	<SKILL_ROOT>/references/CAPABILITIES.md
ディスカバリー（機能＋ブランド＋インテントを推定。既存サイトの場合は §1 の Dynamic Context 呼び出し）	<SKILL_ROOT>/references/DISCOVERY.md
セットアップ（アプリをインストール）	<SKILL_ROOT>/references/SETUP.md
シード（バックエンドコンテンツを作成）	<SKILL_ROOT>/references/SEED.md
SDK 統合の引き継ぎ（出力されるか、create/connect によって適用）	<SKILL_ROOT>/references/SDK_HANDOFF.md
画像生成（オプトイン、種類を問わない）	<SKILL_ROOT>/references/IMAGE_GENERATION.md
デザイン — ユーザーが独自のデザイン方針を示していない場合に、構築したフロントエンドに適用する品質基準（managed の create のみ）	<SKILL_ROOT>/references/DESIGN.md
コンテンツ — ユーザーが独自のコピー／トーンの方針を示していない場合に、構築したフロントエンドに適用するコピーの品質基準（managed の create のみ）	<SKILL_ROOT>/references/CONTENT.md
エクスペリエンスオーバーレイ — DESIGN/CONTENT に加えて適用する、縦型固有のデザイン＋コピーの基準（縦型ごとに任意。該当する縦型を読み込む際に読みます）	<SKILL_ROOT>/references/inline-recipes/experience-<vertical>.md（現在：experience-store.md、experience-donations.md）
AI 機能 — テキスト／チャット＋埋め込み（オプトイン、種類を問わない）	<SKILL_ROOT>/references/AI_FEATURES.md
フィードバック — ヘッドレスエクスペリエンスに関するユーザーのフィードバックを Wix に伝達（オプトイン、ユーザーの承認が必要）	<SKILL_ROOT>/references/FEEDBACK.md
認証 — $TOKEN／$SITE_ID／clientId を取得（プロジェクトタイプ固有）	<TYPE_DIR>/AUTHENTICATION.md
デプロイ — ライブサイトを仕上げる（プロジェクトタイプ固有）	<TYPE_DIR>/DEPLOYMENT.md
Managed の create フロー（新しいプロジェクトをスキャフォールド）	<SKILL_ROOT>/references/managed/CREATE.md
Managed の connect フロー（既存のプロジェクトを接続）	<SKILL_ROOT>/references/managed/CONNECT.md
フロントエンドの軸となるリファレンス（フロントエンドと Wix の接続方法）	<SKILL_ROOT>/references/astro.md、non-astro.md

実行を開始したら、まず DISCOVERY.md を開いてください。 フローファイル（CAPABILITIES、DISCOVERY、SETUP、SEED、SDK_HANDOFF、IMAGE_GENERATION、AI_FEATURES）はプロジェクトタイプに依存しません。タイプごとの詳細は <TYPE_DIR>/（AUTHENTICATION.md、DEPLOYMENT.md、managed のみ CREATE.md／CONNECT.md）にあります。

方法の情報源

このスキルには上流のスキルはありません。方法は、dev.wix.com/docs にある最新の Wix ドキュメントから読み取ります。読み取りの優先順位：このスキルがリンクしているページは、その .md 版を curl で直接読み取ります（最優先です。検索して、厳選されたリンクを見つけ直さないでください）。Wix MCP のドキュメント／検索ツールは、スキルがリンクしていないページを探す場合、または取得に失敗した場合の代替手段として、次に優先します。（ドキュメントの URL の末尾に .md を付けると生の Markdown を取得できます。メニューページには子ページへのリンクが一覧表示され、コンテンツページにはスキーマが記載されています。）

ドキュメントの検索は、どちらのトラックでも共通のフォールバックです。最初の手段にはしないでください。 各トラックの第一の情報源は、ピン留めされた資料（以下）です。必要な情報がそこにない場合は、references/DOC_DISCOVERY.md にフォールバックしてください。これは、Wix MCP の有無にかかわらず使える、セマンティックなドキュメント検索とスキーマ参照の仕組みです。

• Seed は、各機能の作成フローをインラインレシピから読み取ります。これは機能ごとに SEED.md §「What to seed per capability」で指定された、自己完結型のローカルファイル inline-recipes/setup-*.md です。呼び出しがインラインで記載されており、REST ドキュメントのページに優先するため、このファイルだけを読んで Seed を実行してください。インラインレシピがない機能（例：coupons）に限り、ドキュメント検索にフォールバックします（DOC_DISCOVERY.md）。
• Handoff は、各機能の API 構造について SDK ドキュメントへのリンクを提供し、SDK_HANDOFF.md 内のインライン化されたマップから実行時パッケージのセットを提示します（SDK の .md ページにはナビゲーション用の @wix/* インポート文字列が記載されていないため、パッケージはリンクではなくマッピングで示されています）。

Setup には、アプリのインストール呼び出し（および appDefId 定数）が SETUP.md にインラインで記載されています。CAPABILITIES.md は縦割りのインデックスであり、Discovery が意図を照合するために使われます。また、構築された各縦割り機能について、Seed が有効にする Required site features（バックエンドに支えられた機能）と、Handoff がガイドに引き継ぐ Implementation checklist を定義します。これにより、ホストはデータを出力するだけではなく、完全なサイトを構築できます。このスキルは対象となる内容（どの機能を使うか、コンテンツをどれだけ用意するか、完成したサイトに何が含まれるか）を担い、方法はドキュメントから読み取ります。