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:
- 调用
start工具(如果技能需要,请带上params)。 - 读取
preamble字段(仅在第一次调用时)。它将 XML 标签映射到您可用的工具。 - 遵循
prompt指令。生成一个与schema匹配的 JSON 对象。 - 使用
session、step和output调用advance工具。 - 重复步骤 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 组件模式