Communitygithub.com

contentful/personalization(Contentful パーソナライゼーション)

Contentful のパーソナライゼーション機能の実装、拡張、デバッグを行います。新規プロジェクトや未知のセットアップにはonboardingを使用し、既存の動作する統合への限定的な作業にはextend-existingを使用します。

personalization(Contentful パーソナライゼーション) とは?

このスキルは、Contentful のパーソナライゼーション機能(A/Bテスト、実験、マルチバリアントテスト、ターゲティング、オーディエンスセグメント、コンテンツバリアントなど)を実装、拡張、デバッグするための構造化ワークフローを提供します。skill-kit で構築されており、JSON 出力を生成するコンパイル済み CLI バイナリと、XML タグ付きセクション(`<system>`、`<prompt>`、`<ask-user>`、`<confirm>` など)を含むプロンプトを介して動作します。MCP モード(MCPツール利用時、優先)と CLI モード(フォールバック)の両方をサポートし、Claude Code、Cursor、Codex などの主要な AI エージェントホスト上で動作します。ワークフローはユーザーのリクエストを分類し、プロジェクトの状態に応じて、新規実装用の `onboard`、既存統合用の `extend-existing`、トラブルシューティング用の `doctor`、ライブURL検査用の `live-debug` のいずれかのサブスキルにルーティングします。また、パーソナライゼーションの仕組みやSDK選択、コンポーネントパターン、環境変数などに関するクイックリファレンストピックも提供します。

対応✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add https://github.com/contentful/skills/tree/HEAD/skills/contentful-personalization

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 つ以上含まれる場合があります。順番に従ってください。

スキル作成者は、これらのセクションを組み合わせてあなたの動作をガイドしています。タグとツールマッピングは、作成者の意図とホストの機能に基づいて 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
  • 不明/その他: フラグを省略(デフォルトは generic)

ツールを報告する

利用可能なツールをカンマ区切りで --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 は内部ヘッダーであり、絶対に読み取らないでください)。

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

最初に preamble を読んでください。 これには、XML タグを環境で利用可能なツールにマッピングするテーブルが含まれています。ワークフロー全体で参照してください。

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

prompt フィールドを読みます。これには XML タグ付きセクション(上記「このスキルの仕組み」で説明)が含まれています: 従うべき <system> ディレクティブ、実行する <prompt> 指示、およびプリアンブルでマッピングされたツールを使用して実行するインタラクションタグ(<ask-user>、<confirm>、<plan>、<checklist>、<subagent>)。<rendered> ブロックが表示された場合は、その内容を逐語的に出力してください。

schema に一致する JSON オブジェクトを生成します。

ステップ 3: 進める(Advance)

ステップ名を指定して出力を渡します。

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

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

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

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

重要

  • 生の JSON 出力や Bash コマンドをユーザーに見せないでください。 ユーザーはプロトコルではなく、自然言語の応答を見ます。
  • バリデーションエラーが発生した場合(応答に "error": "validation" または "type":"error" が含まれている場合)、message フィールドを読み、出力を修正して同じステップを再試行してください。

このスキルのステップ

  • classify: ユーザーのリクエストを以下のカテゴリのいずれかに分類します。ユーザーのメッセージのみを読み取ってください — これ以上は行わないでください...
  • 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 を使用してください。 — params: readinessOnly(ブール値)、userQuery(文字列)
  • live-debug: Chrome DevTools MCP を使用してライブ URL を検査し、ランタイムのパーソナライゼーション問題を特定します。コンソールの問題を確認し、ninetailed.co リクエストを監視し、次のステップが静的な doctor 診断であるべきかどうかを報告します。 — params: requestedUrl(文字列)
  • doctor: Contentful パーソナライゼーションの問題を診断して修正します。最初にプログラムによるチェック(認証情報、API 接続、コンテンツ状態)を実行し、インフラストラクチャの問題を修正してから、コードベースを探索します。 — params: userQuery(文字列)
  • extend-existing: 明示的に存在し、動作している Contentful パーソナライゼーション統合を拡張します。別のコンポーネントのパーソナライズ、実験の追加、インストール済み SDK へのアナリティクスの配線など、限定的な変更にのみ使用してください。初回、プロジェクト全体、または状態不明の実装リクエストには使用せず、そのような場合は onboard を使用してください。 — params: userQuery(文字列)

リファレンストピック

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

<skill>/scripts/run topics              # すべてのトピックを一覧表示
<skill>/scripts/run topic <name>         # 特定のトピックを読み込む
  • how-personalization-works: コアコンセプト: コンテンツモデル、レンダリングフロー、パーソナライゼーションの仕組み
  • sdk-selection: SDK 選択フレームワーク: Optimization のデフォルトとレガシーデプロイメントの保守
  • provider-patterns: Pages Router、App Router、両 SDK のプロバイダープレースメントパターン
  • middleware-patterns: ミドルウェアと SSR/エッジパターン: preflight、cookies、matcher 設定
  • component-patterns: コンポーネントアーキテクチャパターン: ContentTypeMap、BlockRenderer、分離
  • rendering-pipeline: レンダリングパイプライン: Contentful クライアントセットアップ、include depth、コンポーネントマッパー
  • environment-variables: 環境変数: 名前、ランタイムマトリックス、フレームワークプレフィックス
  • analytics-and-preview: アナリティクスプラグイン(Insights、GTM、Segment)とプレビュー設定
  • common-errors: 一般的な障害モードとその根本原因および修正
  • ssr-guide: SSR およびエッジサイドのパーソナライゼーション: パターン、アンチパターン、トラブルシューティング
  • sdk-legacy-guide: @ninetailed/experience.js 既存デプロイメントのデバッグまたは拡張のためのリファレンス
  • sdk-next-guide: @contentful/optimization SDK ランタイムセレクター
  • optimization-overview: @contentful/optimization ランタイムおよびパッケージセレクター
  • optimization-react-web: @contentful/optimization React Web プロバイダー、フック、エントリ、ルーティング
  • 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: 実際のコード例: プロバイダー、BlockRenderer、Experience コンポーネントパターン

関連スキル