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.

How this skill works

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.

How to run this skill

MCP mode (preferred)

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.

CLI mode (fallback)

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.

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)

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.

Subagent invocations

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).

Parameters

This skill takes no parameters. Pass

--params '{}'

Step 1: Start with a session

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.

Step 2: Follow the prompt

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

Step 3: Advance

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.

Step 4: Repeat until done

Keep advancing until the line you read contains

"type":"done"

. The

finalOutput

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

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.

Steps in this 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)

Sub-skills

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

Direct sub-skill access

bash

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

Available sub-skills

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)

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

contentful-personalization

NPX Install

Tags

SKILL.md Content

contentful-personalization

How this skill works

How to run this skill

MCP mode (preferred)

CLI mode (fallback)

Detect your host

Report your tools

Subagent invocations

Parameters

Step 1: Start with a session

Step 2: Follow the prompt

Step 3: Advance

Step 4: Repeat until done

Important

Steps in this skill

Sub-skills

Direct sub-skill access

Available sub-skills

Reference topics