Communitygithub.com

contentful-personalization

实现、扩展和调试 Contentful 个性化功能。对于新项目、全局范围或未知状态的设置,请使用 onboarding;对于明确工作着的集成的局部修改,请使用 extend-existing。

contentful-personalization 是什么?

该技能是一个结构化的可执行工作流,由编译后的 CLI 二进制文件驱动。它支持 MCP(首选)和 CLI 两种交互模式,旨在引导 AI 代理完成 Contentful 个性化功能的实施、诊断和扩展。工作流通过 XML 标签化指令(如 `<system>`, `<prompt>`, `<ask-user>`, `<plan>`, `<checklist>`)与代理交互,代理需遵循提示、调用相应工具,并传递 JSON 格式的响应。技能包含多个子技能:`onboard`(默认工作流,用于项目范围的设置与未知状态的集成)、`live-debug`(通过 Chrome DevTools MCP 检查运行时问题)、`doctor`(诊断并修复基础设施问题)、`extend-existing`(仅用于对明确工作的集成进行局部修改)。此外,技能还提供一系列参考主题(如 SDK 选择、组件模式、常见错误等),可直接调用获取,无需执行完整工作流。该技能主要面向 Claude Code、Codex、Cursor 等 AI 编码代理,通过规范化的流程指导代理高效完成 Contentful 个性化相关的复杂任务。

兼容平台✓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 标签化部分的 prompt:

  • <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"。

如果您收到 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)

报告您的工具

在 start 命令中,将您可用的工具作为逗号分隔的 --tools 标志传递。会话会记住它们——您在 advance 时无需再次传递 --tools。

当提供了 --host 时,--tools 会与主机的已知工具注册表合并。这意味着部分报告会被优雅地处理——注册表会填补您遗漏的任何工具。如果完全省略 --tools,技能会从 --host 推断工具。如果两者都省略,所有交互都使用通用回退。

子代理调用

如果您是一个子代理(由另一个代理生成,而非用户正在与之对话的顶级代理),请在 start 命令中添加 --subagent。这告诉技能您报告的工具有限——技能不会将它们与主机注册表合并。

如果没有 --subagent,技能会假定您是顶级代理,并将您的工具与注册表合并(因为顶级代理通常未完全报告其工具)。

参数

此技能不接受任何参数。请传递 --params '{}'。

第一步:启动会话

<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 标签映射到您环境中可用工具的表格。请在整个工作流中参考它。

第二步:遵循提示

读取 prompt 字段。它包含 XML 标签化的部分(在“此技能的工作原理”中描述):需要遵循的 <system> 指令、需要执行的 <prompt> 指令,以及需要使用前文中映射的工具来执行的交互标签(<ask-user>、<confirm>、<plan>、<checklist>、<subagent>)。如果出现 <rendered> 块,请逐字输出其内容。

生成一个与 schema 匹配的 JSON 对象。

第三步:推进会话

将您的输出与步骤名称一起传递回来:

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

这将返回一个行号(例如 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/边缘模式:preflight、cookies、matcher 配置
  • 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 SDK 运行时选择器
  • optimization-overview: @contentful/optimization 运行时和包选择器
  • optimization-react-web: @contentful/optimization React Web Provider、hooks、entry 和路由
  • 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 组件模式

相关技能