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:
- 呼叫
start工具(如果技能需要,請附帶params)。 - 讀取
preamble欄位(僅第一次呼叫)。它將 XML 標籤映射到您可用的工具。 - 遵循
prompt指示。產出一個符合schema的 JSON 物件。 - 使用
session、step和output呼叫advance工具。 - 重複步驟 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 元件模式