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> — 将工作委派给隔离的子 Agent。如果设置了 no-recurse，子 Agent 不得调用该属性中命名的技能。
• <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"。

如果收到 status: "error" 且 retry: true，请修正输出并重新提交。 不要向用户显示原始 JSON、会话 ID 或 MCP 工具调用。

跳过本节其余内容；只有在 MCP 工具不可用时，才需要使用下面的 CLI 说明。

CLI 模式（备用）

此 SKILL.md 文件位于技能目录中。请根据此文件的位置解析 scripts/run 的绝对路径（例如 /path/to/skill/scripts/run）。所有 Bash 命令中都使用绝对路径，不要使用 cd 进入技能目录。

以下示例中的 <skill>/scripts/run 是该绝对路径的占位符。

检测你的宿主

确定你所运行的 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
• 未知／其他：省略该标记（默认为通用宿主）

报告你的工具

在 start 命令中，通过逗号分隔的 --tools 标志传入你可用的工具。会话会记住这些工具 — 继续时无需传入 --tools。

提供 --host 时，--tools 会与主机已知的工具注册表合并。 这意味着即使只报告部分工具，也能妥善处理 — 注册表会补充你遗漏的工具。如果完全省略 --tools，技能会根据 --host 推断工具。 如果两者都省略，所有交互都会使用通用回退方案。

子 Agent 调用

如果你是子 Agent（由另一个 Agent 启动，而非用户正在对话的顶层 Agent），请在 start 命令中添加 --subagent。这会告知技能，你报告的工具确实只是一个子集 — 技能不会将它们与主机注册表合并。

如果不添加 --subagent，技能会假定你是顶层 Agent，并将你的工具与注册表合并（因为顶层 Agent 经常不会报告所有工具）。

参数

此技能不接受任何参数。传入 --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> 块，请原样输出其中的内容。

生成符合 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              # 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、匹配器配置
• 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 组件模式