contentful-personalization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

contentful-personalization

This skill is a structured workflow driven by a compiled CLI binary. You interact with it by calling the binary, reading its JSON output, following the instructions in the

prompt

field, and passing your response back. Do not show the raw JSON or Bash commands to the user.

本Skill是由编译后的CLI二进制文件驱动的结构化工作流。你可以通过调用该二进制文件、读取其JSON输出、遵循

prompt

字段中的指令并返回响应来与之交互。请勿向用户展示原始JSON或Bash命令。

How this skill works

本Skill的工作方式

This skill was built with skill-kit, a structured workflow engine. Each step provides a prompt containing XML-tagged sections:

<system>
— Behavioral directives: persona, tone, or constraints. Follow as guidelines for how to behave, not as tasks to relay to the user.
<prompt>
— Task instructions: what to do, what context to consider, what to produce.
<ask-user>
— Ask the user a question. Contains
```
<option>
```
children for structured choices, or
```
type="open"
```
for free-form conversation.
<confirm>
— Binary yes/no confirmation. Attributes:
```
default
```
,
```
destructive
```
.
<plan>
— Present a plan for approval. Contains
```
<step>
```
children.
<checklist>
— Create tracked work items. Contains
```
<item>
```
children with status.
<subagent>
— Delegate work to an isolated sub-agent. If
```
no-recurse
```
is set, the subagent must not invoke the skill named in the attribute.
<rendered>
— Pre-rendered output. Emit verbatim — no edits, no added commentary.

A step may contain one or more of these sections in sequence. Follow them in order.

The skill author composed these sections to guide your behavior. The tags and tool mappings are generated by the SDK based on the author's intent and your host's capabilities. A skill-level system directive may appear in the preamble — it applies to all steps unless a step includes its own

<system>

override.

The preamble (sent on the first step) contains a table mapping each tag to the specific tool available in your environment. Refer to it throughout the workflow.

本Skill是使用skill-kit（一个结构化工作流引擎）构建的。每个步骤都会提供一个包含XML标记部分的提示：

<system>
— 行为指令：角色、语气或约束条件。将其作为行为准则遵循，而非需要传达给用户的任务。
<prompt>
— 任务说明：要做什么、需要考虑的上下文、要生成的内容。
<ask-user>
— 向用户提问。包含
```
<option>
```
子元素用于结构化选择，或
```
type="open"
```
用于自由对话。
<confirm>
— 二元是/否确认。属性：
```
default
```
、
```
destructive
```
。
<plan>
— 提交计划供批准。包含
```
<step>
```
子元素。
<checklist>
— 创建可追踪的工作项。包含带有状态的
```
<item>
```
子元素。
<subagent>
— 将工作委托给独立的子Agent。如果设置了
```
no-recurse
```
，子Agent不得调用属性中指定的Skill。
<rendered>
— 预渲染输出。直接原样输出——不得编辑、添加注释。

一个步骤可能按顺序包含一个或多个上述部分，请按顺序执行。

Skill作者编写这些部分是为了指导你的行为。标签和工具映射由SDK根据作者的意图和你的宿主能力生成。Skill级别的系统指令可能出现在前言中——除非步骤包含自己的

<system>

覆盖，否则它适用于所有步骤。

前言（在第一步发送）包含一个表格，将每个标签映射到你环境中可用的特定工具。在整个工作流中请参考它。

How to run this skill

如何运行本Skill

MCP mode (preferred)

MCP模式（推荐）

If you have MCP tools for this skill (e.g.,

mcp__contentful-personalization__start

and

mcp__contentful-personalization__advance

), use them instead of the CLI:

Call the
```
start
```
tool (with
```
params
```
if the skill requires them).
Read the
```
preamble
```
field (first call only). It maps XML tags to your available tools.
Follow the
```
prompt
```
instructions. Produce a JSON object matching the
```
schema
```
.
Call the
```
advance
```
tool with the
```
session
```
,
```
step
```
, and
```
output
```
.
Repeat steps 3-4 until
```
status
```
is
```
"done"
```
.

If you get

status: "error"

with

retry: true

, fix your output and resubmit. Do not show raw JSON, session IDs, or MCP tool calls to the user.

Skip the rest of this section — the CLI instructions below are only needed when MCP tools are not available.

如果你有适用于本Skill的MCP工具（例如

mcp__contentful-personalization__start

和

mcp__contentful-personalization__advance

），请使用它们而非CLI：

调用
```
start
```
工具（如果Skill需要参数，请传入
```
params
```
）。
读取
```
preamble
```
字段（仅第一次调用时）。它将XML标签映射到你可用的工具。
遵循
```
prompt
```
中的说明。生成符合
```
schema
```
的JSON对象。
传入
```
session
```
、
```
step
```
和
```
output
```
调用
```
advance
```
工具。
重复步骤3-4，直到
```
status
```
为
```
"done"
```
。

如果收到

status: "error"

且

retry: true

，请修正输出后重新提交。 请勿向用户展示原始JSON、会话ID或MCP工具调用信息。

跳过本节剩余内容——下面的CLI说明仅在MCP工具不可用时才需要。

CLI mode (fallback)

CLI模式（备用）

This SKILL.md file is inside the skill directory. Resolve the absolute path to

scripts/run

from this file's location (e.g.,

/path/to/skill/scripts/run

). Use the absolute path in all Bash commands — do not

cd

into the skill directory.

In the examples below,

<skill>/scripts/run

is a placeholder for this absolute path.

本SKILL.md文件位于Skill目录内。从该文件所在位置解析

scripts/run

的绝对路径（例如

/path/to/skill/scripts/run

）。在所有Bash命令中使用绝对路径——不要

cd

到Skill目录。

在下面的示例中，

<skill>/scripts/run

是该绝对路径的占位符。

Detect your host

检测宿主环境

Determine which agent host you are running in, and pass it as

--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
```
Unknown/other: omit the flag (defaults to generic)

确定你运行所在的Agent宿主，并将其作为

--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
```
未知/其他：省略该标志（默认为通用模式）

Report your tools

报告可用工具

Pass the tools you have available as a comma-separated

--tools

flag on the start command. The session remembers them — you don't need to pass

--tools

on advance.

When

--host

is provided,

--tools

is merged with the host's known tool registry. This means partial reporting is handled gracefully — the registry fills in any tools you omit. If

--tools

is omitted entirely, the skill infers tools from

--host

. If both are omitted, all interactions use generic fallbacks.

在启动命令中，以逗号分隔的

--tools

标志传入你可用的工具。会话会记住这些工具——后续调用advance时无需再传入

--tools

。

当提供

--host

时，

--tools

会与宿主的已知工具注册表合并。这意味着部分报告可以被优雅处理——注册表会补充你遗漏的任何工具。如果完全省略

--tools

，Skill会从

--host

推断工具。如果两者都省略，所有交互都将使用通用回退方案。

Subagent invocations

子Agent调用

If you are a subagent (spawned by another agent, not the top-level agent the user is talking to), add

--subagent

to the start command. This tells the skill that your reported tools are a genuine subset — the skill will not merge them with the host registry.

Without

--subagent

, the skill assumes you are a top-level agent and merges your tools with the registry (since top-level agents often under-report their tools).

如果你是子Agent（由另一个Agent生成，而非用户直接对话的顶级Agent），请在启动命令中添加

--subagent

。这会告知Skill你报告的工具是真实的子集——Skill不会将它们与宿主注册表合并。

如果没有

--subagent

，Skill会假设你是顶级Agent，并将你的工具与注册表合并（因为顶级Agent通常会少报其工具）。

Parameters

参数

This skill takes no parameters. Pass

--params '{}'

本Skill不需要参数。传入

--params '{}'

即可。

Step 1: Start with a session

步骤1：启动会话

bash

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

This returns a JSON pointer with

sessionId

file

, and

line

. The

line

field tells you which line to read — it will be

, not

(line 1 is an internal header, never read it).

Read only line

line

from

file

. It contains the step prompt, schema, and preamble.

Read the
preamble
first. It contains a table mapping XML tags to the tools available in your environment. Refer to it throughout the workflow.

bash

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

这会返回一个包含

sessionId

、

file

和

line

的JSON指针。

line

字段告诉你要读取哪一行——它会是

，而非

（第1行是内部头，永远不要读取它）。

仅读取

file

中的第

line

行。该行包含步骤提示、schema和前言。

首先读取
preamble
。它包含一个将XML标签映射到你环境中可用工具的表格。在整个工作流中请参考它。

Step 2: Follow the prompt

步骤2：遵循提示

Read the

prompt

field. It contains XML-tagged sections (described in "How this skill works" above):

<system>

directives to follow,

<prompt>

instructions to act on, and interaction tags (

<ask-user>

<confirm>

<plan>

<checklist>

<subagent>

) to execute using the tools mapped in the preamble. If a

<rendered>

block appears, emit its content verbatim.

Produce a JSON object matching the

schema

读取

prompt

字段。它包含XML标记部分（在“本Skill的工作方式”中描述）：要遵循的

<system>

指令、要执行的

<prompt>

说明，以及要使用前言中映射的工具执行的交互标签（

<ask-user>

、

<confirm>

、

<plan>

、

<checklist>

、

<subagent>

）。如果出现

<rendered>

块，请直接输出其内容。

生成符合

schema

的JSON对象。

Step 3: Advance

步骤3：推进工作流

Pass your output back with the step name:

bash

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

This returns a single line number (e.g.,

). Read exactly and only that line from the session file — it contains the next prompt. Do not read any other lines.

传入步骤名称返回你的输出：

bash

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

这会返回一个行号（例如

）。仅读取会话文件中完全对应的那一行——它包含下一个提示。不要读取任何其他行。

Step 4: Repeat until done

步骤4：重复直到完成

Keep advancing until the line you read contains

"type":"done"

. The

finalOutput

field contains the skill's result. Present it to the user.

持续推进，直到你读取的行包含

"type":"done"

。

finalOutput

字段包含Skill的结果。将其展示给用户。

Important

重要提示

Never show raw JSON output or Bash commands to the user. The user sees your natural language responses, not the protocol.
If you get a validation error (the response has
```
"error": "validation"
```
or
```
"type":"error"
```
), read the
```
message
```
field, fix your output, and retry the same step.

永远不要向用户展示原始JSON输出或Bash命令。 用户看到的是你的自然语言响应，而非协议内容。
如果收到验证错误（响应包含
```
"error": "validation"
```
或
```
"type":"error"
```
），请读取
```
message
```
字段，修正输出后重试同一步骤。

Steps in this skill

本Skill的步骤

classify: Classify the user's request into one of the categories below. Read only the user's message — do N...
gather-context: You were not confident enough to classify the user's request. Silently explore the project to gat...
pick-topic: (dynamic)

classify: 将用户的请求分类为以下类别之一。仅读取用户的消息——不要...
gather-context: 你对用户请求的分类不够确定。静默探索项目以收集...
pick-topic: (动态)

Sub-skills

子Skill

This skill contains sub-skills that the workflow routes to automatically. Start the skill normally — the dispatcher will determine which sub-skill to use. Only use direct sub-skill access if the user explicitly requests a specific sub-skill by name.

Sub-skill step names are prefixed:

<subskill>/<step>

(e.g.,

doctor/diagnose

本Skill包含子Skill，工作流会自动路由到这些子Skill。正常启动Skill即可——调度器会确定使用哪个子Skill。仅当用户明确按名称请求特定子Skill时，才直接使用子Skill。

子Skill的步骤名称带有前缀：

<subskill>/<step>

（例如

doctor/diagnose

）。

Direct sub-skill access

直接访问子Skill

bash

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

bash

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

Available sub-skills

可用子Skill

onboard: Assess readiness and guide Contentful personalization setup end-to-end. Explores the codebase, checks readiness, helps choose SDK and architecture, installs packages, and guides implementation. — params:
```
readinessOnly
```
(boolean),
```
userQuery
```
(string)
live-debug: Inspect a live URL with Chrome DevTools MCP for runtime personalization issues. Checks console problems, observes ninetailed.co requests, and reports whether the next step should be static doctor diagnosis. — params:
```
requestedUrl
```
(string)
doctor: Diagnose and fix Contentful personalization issues. Runs programmatic checks first (credentials, API connectivity, content state), fixes infrastructure problems, and only then explores the codebase. — params:
```
userQuery
```
(string)
develop: Day-to-day development companion for building with Contentful personalization. Helps add personalization to components, create experiments, and wire analytics. — params:
```
userQuery
```
(string)

onboard: 评估就绪性并端到端指导Contentful个性化设置。探索代码库、检查就绪性、帮助选择SDK和架构、安装包并指导实现。——参数：
```
readinessOnly
```
（布尔值）、
```
userQuery
```
（字符串）
live-debug: 使用Chrome DevTools MCP检查实时URL的运行时个性化问题。检查控制台问题、观察ninetailed.co请求，并报告下一步是否应该进行静态诊断。——参数：
```
requestedUrl
```
（字符串）
doctor: 诊断并修复Contentful个性化问题。首先运行程序化检查（凭据、API连接、内容状态），修复基础设施问题，然后再探索代码库。——参数：
```
userQuery
```
（字符串）
develop: 用于使用Contentful个性化功能进行日常开发的辅助工具。帮助为组件添加个性化、创建实验并连接分析工具。——参数：
```
userQuery
```
（字符串）

Reference topics

参考主题

Quick-reference topics accessible without running the full workflow:

bash

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

how-personalization-works: Core concepts: content model, rendering flow, and how personalization works
sdk-selection: SDK decision framework: current @ninetailed/experience.js vs modern @contentful/optimization
provider-patterns: Provider placement patterns for Pages Router, App Router, and both SDKs
middleware-patterns: Middleware and SSR/edge patterns: preflight, cookies, matcher config
component-patterns: Component architecture patterns: ContentTypeMap, BlockRenderer, isolation
rendering-pipeline: Rendering pipeline: Contentful client setup, include depth, component mapper
environment-variables: Environment variables: names, runtime matrix, framework prefixes
analytics-and-preview: Analytics plugins (Insights, GTM, Segment) and preview configuration
common-errors: Common failure modes with root causes and fixes
ssr-guide: SSR and edge-side personalization: patterns, anti-patterns, troubleshooting
sdk-legacy-guide: @ninetailed/experience.js complete SDK reference
sdk-next-guide: @contentful/optimization modern SDK reference (OptimizationRoot, hooks, Next.js adapter)
contentful-integration-guide: Contentful CMS integration: content types, ExperienceMapper, publishing workflow
implementation-examples: Real code examples: providers, BlockRenderer, Experience component patterns

无需运行完整工作流即可访问的快速参考主题：

bash

<skill>/scripts/run topics              # 列出所有主题
<skill>/scripts/run topic <name>         # 加载特定主题

how-personalization-works: 核心概念：内容模型、渲染流程以及个性化的工作原理
sdk-selection: SDK决策框架：当前@ninetailed/experience.js vs 现代@contentful/optimization
provider-patterns: 适用于Pages Router、App Router以及两个SDK的Provider放置模式
middleware-patterns: 中间件和SSR/边缘模式：预检、Cookie、匹配器配置
component-patterns: 组件架构模式：ContentTypeMap、BlockRenderer、隔离
rendering-pipeline: 渲染流水线：Contentful客户端设置、包含深度、组件映射器
environment-variables: 环境变量：名称、运行时矩阵、框架前缀
analytics-and-preview: 分析插件（Insights、GTM、Segment）和预览配置
common-errors: 常见故障模式及其根本原因和修复方法
ssr-guide: SSR和边缘侧个性化：模式、反模式、故障排除
sdk-legacy-guide: @ninetailed/experience.js完整SDK参考
sdk-next-guide: @contentful/optimization现代SDK参考（OptimizationRoot、hooks、Next.js适配器）
contentful-integration-guide: Contentful CMS集成：内容类型、ExperienceMapper、发布工作流
implementation-examples: 真实代码示例：Providers、BlockRenderer、Experience组件模式