Communitygithub.com

contentful/skills

實作、擴充與除錯 Contentful 個人化功能。使用 onboarding 進行全新或未知狀態的專案設定;僅針對明確正常運作的整合使用 extend-existing。觸發關鍵字:personalization, optimization, ninetailed, A/B test, experiment, multivariate test, targeting, audience targeting, segments, variants, content variants, set up personalization, implement personalization, enable personalization, personalization not working, personalization broken, personalize this component, am I ready for personalization, experience API, Contentful Experiences, Experiences SDK, Studio Experiences, personalization in Next.js, @contentful/optimization, @ninetailed/experience.js, run an experiment, check this URL, debug this live page, inspect network requests, check console errors, experience.ninetailed.co

skills 是什麼?

本技能提供了一個結構化的工作流程,用於在專案中實作、擴充與除錯 Contentful 的個人化功能。它由一個編譯後的 CLI 二進位檔驅動,支援 MCP(首選模式)與 CLI(備援模式)兩種執行方式。技能包含多個子技能,例如 onboard(用於首次或未知狀態的專案設定)、extend-existing(用於對已正常運作的整合進行局部修改)、doctor(用於診斷與修復問題)以及 live-debug(用於檢查即時頁面的個人化問題)。使用者透過 JSON 輸出與技能互動,並遵循包含系統指令、提示、使用者詢問、確認、計劃、檢查清單與子代理等 XML 標籤的結構化提示。此技能專為 AI 代理設計(支援 Claude Code、Cursor、Codex 等平台),幫助開發者有效率地管理工作流程,無需將原始 JSON 或 Bash 指令暴露給最終使用者。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add https://github.com/contentful/skills/tree/HEAD/skills/contentful-personalization

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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> — 預先渲染的輸出。逐字輸出 — 不進行編輯,不添加額外評論。

一個步驟可能包含上述一個或多個區段,請依序遵循。

技能作者組合了這些區段來引導您的行為。這些標籤和工具映射是由 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. 重複步驟 3-4,直到 status 變為 "done"。

如果您得到帶有 retry: true 的 status: "error",請修正您的輸出並重新提交。 請勿向使用者顯示原始的 JSON、session 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)

報告您的工具

在 start 指令中,將您可用的工具以逗號分隔的 --tools 旗標傳遞。工作階段會記住這些工具 — 您無需在 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 行。它包含步驟提示、schema 和前文。

首先閱讀 preamble。 它包含一個表格,將 XML 標籤映射到您環境中可用的工具。請在整個工作流程中參考它。

步驟 2:遵循提示

讀取 prompt 欄位。它包含帶有 XML 標籤的區段(在「此技能的運作方式」中描述):要遵循的 <system> 指令、要執行的 <prompt> 指示,以及要使用前文中映射的工具來執行的互動標籤(<ask-user>、<confirm>、<plan>、<checklist>、<subagent>)。如果出現 <rendered> 區塊,請逐字輸出其內容。

產出一個符合 schema 的 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:將使用者的請求分類到以下類別之一。僅讀取使用者的訊息 — 請勿...
  • 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              # 列出所有主題
<skill>/scripts/run topic <name>         # 載入特定主題
  • how-personalization-works:核心概念:內容模型、渲染流程以及個人化如何運作
  • sdk-selection:SDK 決策框架:預設使用 Optimization、或維護舊版部署
  • provider-patterns:適用於 Pages Router、App Router 以及兩種 SDK 的 Provider 放置模式
  • middleware-patterns:中介軟體與 SSR/edge 模式:preflight、cookie、matcher 設定
  • component-patterns:元件架構模式:ContentTypeMap、BlockRenderer、隔離
  • rendering-pipeline:渲染管線:Contentful 客戶端設定、include 深度、元件映射器
  • environment-variables:環境變數:名稱、執行時期矩陣、框架前綴
  • analytics-and-preview:分析外掛(Insights、GTM、Segment)與預覽設定
  • common-errors:常見失敗模式及其根本原因與修復方式
  • ssr-guide:SSR 與 edge-side 個人化:模式、反模式、故障排除
  • sdk-legacy-guide:@ninetailed/experience.js 參考,用於除錯或擴充現有部署
  • sdk-next-guide:@contentful/optimization SDK 執行時期選擇器
  • optimization-overview:@contentful/optimization 執行時期與套件選擇器
  • optimization-react-web:@contentful/optimization React Web Provider、hooks、entries 與路由
  • 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 元件模式

相關技能