contentful-personalization

contentful-personalization

このスキルは、コンパイル済みの CLI バイナリによって実行される、構造化されたワークフローです。バイナリを呼び出し、JSON 出力を読み取り、prompt フィールドの指示に従って、回答を返すことで操作します。未加工の JSON や Bash コマンドをユーザーに表示しないでください。

このスキルの仕組み

このスキルは、構造化ワークフローエンジンである skill-kit を使って構築されています。各ステップでは、XML タグ付きのセクションを含む プロンプトが提供されます。

• <system> — 振る舞いに関する指示です。ペルソナ、口調、制約などが含まれます。ユーザーに伝えるタスクではなく、振る舞い方のガイドラインとして従ってください。
• <prompt> — タスクの指示です。実行すること、考慮するコンテキスト、生成する内容が示されます。
• <ask-user> — ユーザーに質問します。選択肢を提示する場合は子要素として <option> を含み、自由形式の会話の場合は type="open" を指定します。
• <confirm> — 「はい」か「いいえ」の二択で確認します。属性：default、destructive。
• <plan> — 承認を得るために計画を提示します。子要素として <step> を含みます。
• <checklist> — 追跡対象の作業項目を作成します。ステータスを含む <item> 子要素があります。
• <subagent> — 分離されたサブエージェントに作業を委任します。no-recurse が設定されている場合、サブエージェントは属性で指定されたスキルを呼び出してはいけません。
• <rendered> — 事前にレンダリングされた出力です。編集やコメントの追加をせず、そのまま出力してください。

1 つのステップに、これらのセクションが 1 つ以上、順番に含まれる場合があります。記載された順に従ってください。

スキルの作成者は、振る舞いを導くためにこれらのセクションを構成しています。タグとツールの対応付けは、作成者の意図とホストの機能に基づいて SDK が生成します。スキルレベルのシステム指示がプリアンブルに記載される場合があります。各ステップに独自の <system> による上書きがない限り、すべてのステップに適用されます。

最初のステップで送信されるプリアンブルには、各タグを環境で利用可能な特定のツールに対応付ける表が含まれています。ワークフロー全体を通じて参照してください。

このスキルの実行方法

MCP モード（推奨）

このスキル用の MCP ツール（例：mcp__contentful-personalization__start と mcp__contentful-personalization__advance）がある場合は、CLI の代わりにそれらを使用してください。

1. start ツールを呼び出します（スキルで必要な場合は params を指定します）。
2. preamble フィールドを読み取ります（初回の呼び出しのみ）。XML タグと利用可能なツールの対応付けが記載されています。
3. prompt の指示に従います。schema に一致する JSON オブジェクトを生成します。
4. session、step、output を指定して advance ツールを呼び出します。
5. status が "done" になるまで、手順 3〜4 を繰り返します。

status: "error" かつ retry: true が返された場合は、出力を修正して再送信してください。 未加工の JSON、セッション ID、MCP ツールの呼び出しをユーザーに表示しないでください。

このセクションの残りは読み飛ばしてください。以下の CLI の手順は、MCP ツールを利用できない場合にのみ必要です。

CLI モード（代替手段）

この SKILL.md ファイルはスキルディレクトリ内にあります。このファイルの場所を基準に、scripts/run の絶対パスを解決してください（例：/path/to/skill/scripts/run）。すべての Bash コマンドで絶対パスを使用し、スキルディレクトリに cd しないでください。

以下の例では、<skill>/scripts/run はこの絶対パスを示すプレースホルダーです。

ホストの検出

実行中のエージェントホストを判別し、--host として渡してください。

• Claude Code：--host claude-code
• Codex：--host codex
• OpenCode：--host opencode
• Gemini CLI：--host gemini-cli
• Cline：--host cline
• Roo Code：--host roo-code
• Kilo Code：--host kilo-code
• Cursor：--host cursor
• Amp：--host amp
• 不明／その他：フラグを省略します（汎用設定がデフォルトです）

ツールを報告する

利用可能なツールを、カンマ区切りの --tools フラグとして start コマンドに渡します。セッションで記憶されるため、advance では --tools を渡す必要はありません。

--host を指定すると、--tools はホストで認識されているツールレジストリと統合されます。 そのため、一部のツールだけを報告した場合でも、報告から漏れたツールはレジストリによって補完されます。--tools をまったく指定しない場合、スキルは --host からツールを推測します。 どちらも省略した場合、すべてのやり取りで汎用のフォールバックが使われます。

サブエージェントの呼び出し

別のエージェントによって起動されたサブエージェントである場合（ユーザーが対話しているトップレベルエージェントではない場合）、start コマンドに --subagent を追加してください。これにより、報告したツールは実際に利用可能なツールの一部であることがスキルに伝わり、ホストのレジストリとの統合は行われません。

--subagent を指定しない場合、スキルはあなたをトップレベルエージェントとみなし、ツールをレジストリと統合します（トップレベルエージェントは、利用可能なツールを一部しか報告しないことが多いためです）。

パラメーター

このスキルにパラメーターはありません。--params '{}' を渡してください。

ステップ 1：セッションを開始する

<skill>/scripts/run --params '{}' --host claude-code --tools <your-tools> --session new 2>/dev/null

これにより、sessionId、file、line を含む JSON ポインターが返されます。line フィールドは読み取る行を示します。値は 2 であり、1 ではありません（1 行目は内部ヘッダーのため、決して読み取らないでください）。

file の line 行のみを読み取ってください。そこにはステップのプロンプト、スキーマ、前文が含まれています。

最初に preamble を読んでください。 実行環境で利用可能なツールに XML タグを対応付ける表が含まれています。ワークフロー全体を通して参照してください。

ステップ 2：プロンプトに従う

prompt フィールドを読みます。そこには、（上記の「このスキルの仕組み」で説明されている）XML タグ付きのセクションが含まれています。従うべき <system> 指示、実行すべき <prompt> 指示、および前文で対応付けられたツールを使って実行する対話タグ（<ask-user>、<confirm>、<plan>、<checklist>、<subagent>）があります。<rendered> ブロックがある場合は、その内容をそのまま出力してください。

スキーマに一致する JSON オブジェクトを生成します。

ステップ 3：次へ進む

ステップ名を添えて、出力を渡します。

<skill>/scripts/run advance --step <step-name> --output '<your-json>' --session abc123 2>/dev/null

これにより、単一の行番号（例：4）が返されます。セッションファイルから、その行だけを正確に読み取ってください。そこには次のプロンプトが含まれています。他の行は読み取らないでください。

ステップ 4：完了するまで繰り返す

読み取った行に "type":"done" が含まれるまで、次へ進み続けます。finalOutput フィールドにスキルの結果が含まれています。それをユーザーに提示してください。

重要

• 生の JSON 出力や Bash コマンドをユーザーに見せないでください。 ユーザーに表示するのはプロトコルではなく、自然な言葉による回答です。
• 検証エラーが発生した場合（レスポンスに "error": "validation" または "type":"error" が含まれている場合）、message フィールドを読み、出力を修正して同じステップを再試行してください。

このスキルのステップ

• classify：ユーザーのリクエストを以下のカテゴリのいずれかに分類します。 ユーザーのメッセージのみを読み取ります — N...
• gather-context：ユーザーのリクエストを分類する確信が十分でありませんでした。 プロジェクトを静かに調査して、状況を把握します...
• pick-topic：（動的）

サブスキル

このスキルには、ワークフローが自動的に振り分けるサブスキルが含まれています。 通常どおりスキルを開始してください。どのサブスキルを使うかはディスパッチャーが判断します。 ユーザーが特定のサブスキル名を明示的に指定した場合に限り、サブスキルへ直接アクセスしてください。

サブスキルのステップ名には、<subskill>/<step> の形式で接頭辞が付きます（例：doctor/diagnose）。

サブスキルへの直接アクセス

<skill>/scripts/run <subskill> --params '<json>' --session new
<skill>/scripts/run <subskill> advance --session <id>

利用可能なサブスキル

• onboard：Contentful のパーソナライズをプロジェクト全体に実装、設定、または有効化するためのデフォルトのワークフローです。既存の設定状態が不明な場合も対象となります。コードベースを調査し、準備状況を確認して、SDK とアーキテクチャを選択し、パッケージをインストールして実装・検証します。extend-existing は、明示的に動作している連携への限定的な変更にのみ使用してください。— パラメーター：readinessOnly（ブール値）、userQuery（文字列）
• live-debug：Chrome DevTools MCP でライブ URL を調査し、実行時のパーソナライズの問題を確認します。コンソールの問題をチェックし、ninetailed.co へのリクエストを監視して、次のステップとして静的な doctor 診断を行うべきかどうかを報告します。— パラメーター：requestedUrl（文字列）
• doctor：Contentful のパーソナライズに関する問題を診断して修正します。まずプログラムによるチェック（認証情報、API 接続、コンテンツの状態）を実行し、インフラストラクチャの問題を修正してから、コードベースを調査します。— パラメーター：userQuery（文字列）
• extend-existing：明示的に存在し、動作している Contentful のパーソナライズ連携を拡張します。別のコンポーネントのパーソナライズ、実験の追加、インストール済み SDK への分析機能の接続など、限定的な変更にのみ使用してください。初回の実装、プロジェクト全体への実装、または状態が不明な場合の実装には使用せず、その場合は onboard を使用してください。— パラメーター：userQuery（文字列）

リファレンストピック

完全なワークフローを実行せずに参照できるクイックリファレンストピック：

<skill>/scripts/run topics              # list all topics
<skill>/scripts/run topic <name>         # load a specific topic

• how-personalization-works：基本概念：コンテンツモデル、レンダリングフロー、パーソナライズの仕組み
• sdk-selection：SDK の選択基準：Optimization のデフォルトとレガシー環境の保守
• provider-patterns：Pages Router、App Router、両方の SDK における Provider の配置パターン
• middleware-patterns：ミドルウェアと SSR／エッジのパターン：プリフライト、Cookie、matcher の設定
• component-patterns：コンポーネントのアーキテクチャパターン：ContentTypeMap、BlockRenderer、分離
• rendering-pipeline：レンダリングパイプライン：Contentful クライアントの設定、include の深さ、コンポーネントマッパー
• environment-variables：環境変数：名前、実行環境のマトリックス、フレームワークのプレフィックス
• analytics-and-preview：分析プラグイン（Insights、GTM、Segment）とプレビュー設定
• common-errors：よくある障害：根本原因と修正方法
• ssr-guide：SSR とエッジ側のパーソナライズ：パターン、アンチパターン、トラブルシューティング
• sdk-legacy-guide：既存のデプロイメントのデバッグや拡張に関する @ninetailed/experience.js のリファレンス
• sdk-next-guide：@contentful/optimization の実行環境選択
• optimization-overview：@contentful/optimization の実行環境とパッケージの選択
• optimization-react-web：@contentful/optimization の React Web Provider、フック、エントリー、ルーティング
• optimization-nextjs-app-router：@contentful/optimization の Next.js App Router 連携
• optimization-nextjs-pages-router：@contentful/optimization の Next.js Pages Router 連携
• optimization-web：@contentful/optimization の命令型ブラウザー連携と Web Components 連携
• optimization-node：@contentful/optimization のステートレスな Node リクエスト連携
• optimization-react-native：@contentful/optimization の React Native 連携
• contentful-integration-guide：Contentful CMS 連携：コンテンツタイプ、ExperienceMapper、公開ワークフロー
• implementation-examples：実際のコード例：Provider、BlockRenderer、Experience コンポーネントのパターン