contentful-personalization
Esta skill es un flujo de trabajo estructurado impulsado por un binario CLI compilado. Interactúas con ella
llamando al binario, leyendo su salida JSON, siguiendo las instrucciones en el campo prompt
y pasando tu respuesta de vuelta. No muestres el JSON sin procesar ni los comandos Bash al usuario.
Cómo funciona esta skill
Esta skill fue construida con skill-kit, un motor de flujo de trabajo estructurado. Cada paso proporciona una indicación que contiene secciones etiquetadas con XML:
<system>— Directivas de comportamiento: persona, tono o restricciones. Síguelas como pautas de comportamiento, no como tareas que transmitir al usuario.<prompt>— Instrucciones de tarea: qué hacer, qué contexto considerar, qué producir.<ask-user>— Pregunta al usuario una cuestión. Contiene hijos<option>para opciones estructuradas, otype="open"para conversación libre.<confirm>— Confirmación binaria sí/no. Atributos:default,destructive.<plan>— Presenta un plan para aprobación. Contiene hijos<step>.<checklist>— Crea elementos de trabajo con seguimiento. Contiene hijos<item>con estado.<subagent>— Delega trabajo a un subagente aislado. Si se estableceno-recurse, el subagente no debe invocar la skill nombrada en el atributo.<rendered>— Salida prerrenderizada. Emítela textualmente, sin ediciones ni comentarios añadidos.
Un paso puede contener una o más de estas secciones en secuencia. Síguelas en orden.
El autor de la skill compuso estas secciones para guiar tu comportamiento. Las etiquetas y
asignaciones de herramientas son generadas por el SDK basándose en la intención del autor y las
capacidades de tu anfitrión. Una directiva de sistema a nivel de skill puede aparecer en el preámbulo; se aplica
a todos los pasos a menos que un paso incluya su propia anulación <system>.
El preámbulo (enviado en el primer paso) contiene una tabla que asigna cada etiqueta a la herramienta específica disponible en tu entorno. Consúltalo a lo largo del flujo de trabajo.
Cómo ejecutar esta skill
Modo MCP (preferido)
Si tienes herramientas MCP para esta skill (por ejemplo, mcp__contentful-personalization__start y
mcp__contentful-personalization__advance), úsalas en lugar del CLI:
- Llama a la herramienta
start(conparamssi la skill lo requiere). - Lee el campo
preamble(solo en la primera llamada). Asigna las etiquetas XML a tus herramientas disponibles. - Sigue las instrucciones de
prompt. Produce un objeto JSON que coincida con elschema. - Llama a la herramienta
advanceconsession,stepyoutput. - Repite los pasos 3 y 4 hasta que
statussea"done".
Si obtienes status: "error" con retry: true, corrige tu salida y vuelve a enviar.
No muestres JSON sin procesar, IDs de sesión o llamadas a herramientas MCP al usuario.
Omite el resto de esta sección: las instrucciones del CLI a continuación solo son necesarias cuando las herramientas MCP no están disponibles.
Modo CLI (alternativa)
Este archivo SKILL.md se encuentra dentro del directorio de la skill. Resuelve la ruta absoluta a scripts/run
desde la ubicación de este archivo (por ejemplo, /ruta/a/skill/scripts/run). Usa la ruta absoluta en todos
los comandos Bash; no hagas cd al directorio de la skill.
En los ejemplos a continuación, <skill>/scripts/run es un marcador de posición para esta ruta absoluta.
Detecta tu anfitrión
Determina en qué anfitrión de agente te estás ejecutando y pásalo como --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 - Desconocido/otro: omite la bandera (por defecto es genérico)
Reporta tus herramientas
Pasa las herramientas que tienes disponibles como una bandera --tools separada por comas en el comando start.
La sesión las recuerda; no necesitas pasar --tools en advance.
Cuando se proporciona --host, --tools se fusiona con el registro de herramientas conocido del anfitrión.
Esto significa que el reporte parcial se maneja de manera elegante: el registro completa cualquier herramienta
que omitas. Si se omite --tools por completo, la skill infiere las herramientas de --host.
Si ambos se omiten, todas las interacciones usan alternativas genéricas.
Invocaciones de subagentes
Si eres un subagente (generado por otro agente, no el agente de nivel superior con el que el usuario
está hablando), añade --subagent al comando start. Esto le dice a la skill que tus herramientas reportadas
son un subconjunto genuino; la skill no las fusionará con el registro del anfitrión.
Sin --subagent, la skill asume que eres un agente de nivel superior y fusiona tus herramientas
con el registro (ya que los agentes de nivel superior a menudo subestiman sus herramientas).
Parámetros
Esta skill no toma parámetros. Pasa --params '{}'.
Paso 1: Comienza con una sesión
<skill>/scripts/run --params '{}' --host claude-code --tools <tus-herramientas> --session new 2>/dev/null
Esto devuelve un puntero JSON con sessionId, file y line. El campo line te dice
qué línea leer; será 2, no 1 (la línea 1 es un encabezado interno, nunca la leas).
Lee solo la línea line de file. Contiene la indicación del paso, el esquema y el preámbulo.
Lee el preamble primero. Contiene una tabla que asigna las etiquetas XML a las herramientas
disponibles en tu entorno. Consúltalo a lo largo del flujo de trabajo.
Paso 2: Sigue la indicación
Lee el campo prompt. Contiene secciones etiquetadas con XML (descritas en "Cómo funciona esta skill"
anteriormente): directivas <system> a seguir, instrucciones <prompt> para actuar, y etiquetas
de interacción (<ask-user>, <confirm>, <plan>, <checklist>, <subagent>)
para ejecutar usando las herramientas mapeadas en el preámbulo. Si aparece un bloque <rendered>,
emite su contenido textualmente.
Produce un objeto JSON que coincida con el schema.
Paso 3: Avanza
Pasa tu salida de vuelta con el nombre del paso:
<skill>/scripts/run advance --step <nombre-del-paso> --output '<tu-json>' --session abc123 2>/dev/null
Esto devuelve un solo número de línea (por ejemplo, 4). Lee exacta y solo esa línea del archivo de sesión; contiene la siguiente indicación. No leas ninguna otra línea.
Paso 4: Repite hasta terminar
Sigue avanzando hasta que la línea que leas contenga "type":"done". El campo finalOutput
contiene el resultado de la skill. Preséntalo al usuario.
Importante
- Nunca muestres la salida JSON sin procesar ni los comandos Bash al usuario. El usuario ve tus respuestas en lenguaje natural, no el protocolo.
- Si obtienes un error de validación (la respuesta tiene
"error": "validation"o"type":"error"), lee el campomessage, corrige tu salida y reintenta el mismo paso.
Pasos en esta skill
- classify: Clasifica la solicitud del usuario en una de las categorías a continuación. Lee solo el mensaje del usuario; no ha...
- gather-context: No tenías suficiente confianza para clasificar la solicitud del usuario. Explora silenciosamente el proyecto para recop...
- pick-topic: (dinámico)
Sub-skills
Esta skill contiene sub-skills a las que el flujo de trabajo dirige automáticamente. Inicia la skill normalmente; el despachador determinará qué sub-skill usar. Solo usa el acceso directo a una sub-skill si el usuario solicita explícitamente una sub-skill específica por nombre.
Los nombres de los pasos de las sub-skills tienen prefijo: <subskill>/<step> (por ejemplo, doctor/diagnose).
Acceso directo a sub-skills
<skill>/scripts/run <subskill> --params '<json>' --session new
<skill>/scripts/run <subskill> advance --session <id>
Sub-skills disponibles
- onboard: Flujo de trabajo predeterminado para implementar, configurar o habilitar la personalización de Contentful en todo el proyecto, incluso cuando se desconoce el estado de la configuración existente. Explora el código base, verifica la preparación, elige SDK y arquitectura, instala paquetes, implementa y valida. Usa extend-existing solo para un cambio acotado en una integración que funcione explícitamente. — params:
readinessOnly(booleano),userQuery(cadena) - live-debug: Inspecciona una URL en vivo con Chrome DevTools MCP para problemas de personalización en tiempo de ejecución. Verifica problemas de consola, observa solicitudes de ninetailed.co e informa si el siguiente paso debe ser un diagnóstico estático de doctor. — params:
requestedUrl(cadena) - doctor: Diagnostica y soluciona problemas de personalización de Contentful. Ejecuta verificaciones programáticas primero (credenciales, conectividad API, estado del contenido), soluciona problemas de infraestructura, y solo entonces explora el código base. — params:
userQuery(cadena) - extend-existing: Extiende una integración de personalización de Contentful existente y que funcione explícitamente. Úsala solo para cambios acotados como personalizar otro componente, agregar un experimento o conectar análisis al SDK instalado. No la uses para solicitudes de implementación por primera vez, para todo el proyecto o de estado desconocido; usa onboard para esos casos. — params:
userQuery(cadena)
Temas de referencia
Temas de referencia rápida accesibles sin ejecutar el flujo de trabajo completo:
<skill>/scripts/run topics # lista todos los temas
<skill>/scripts/run topic <nombre> # carga un tema específico
- how-personalization-works: Conceptos centrales: modelo de contenido, flujo de renderizado y cómo funciona la personalización
- sdk-selection: Marco de decisión del SDK: Optimización predeterminada vs. mantenimiento de despliegue heredado
- provider-patterns: Patrones de colocación de proveedores para Pages Router, App Router y ambos SDK
- middleware-patterns: Patrones de middleware y SSR/edge: preflight, cookies, configuración de matcher
- component-patterns: Patrones de arquitectura de componentes: ContentTypeMap, BlockRenderer, aislamiento
- rendering-pipeline: Pipeline de renderizado: configuración del cliente de Contentful, profundidad de include, mapeador de componentes
- environment-variables: Variables de entorno: nombres, matriz de tiempo de ejecución, prefijos del framework
- analytics-and-preview: Plugins de análisis (Insights, GTM, Segment) y configuración de vista previa
- common-errors: Modos de fallo comunes con causas raíz y soluciones
- ssr-guide: Personalización SSR y edge: patrones, antipatrones, resolución de problemas
- sdk-legacy-guide: Referencia de @ninetailed/experience.js para depurar o extender despliegues existentes
- sdk-next-guide: Selector de tiempo de ejecución del SDK @contentful/optimization
- optimization-overview: Selector de tiempo de ejecución y paquete de @contentful/optimization
- optimization-react-web: Proveedor React Web, hooks, entradas y enrutamiento de @contentful/optimization
- optimization-nextjs-app-router: Integración de @contentful/optimization con Next.js App Router
- optimization-nextjs-pages-router: Integración de @contentful/optimization con Next.js Pages Router
- optimization-web: Integración imperativa de navegador y Web Components de @contentful/optimization
- optimization-node: Integración de solicitud Node sin estado de @contentful/optimization
- optimization-react-native: Integración de @contentful/optimization con React Native
- contentful-integration-guide: Integración con CMS Contentful: tipos de contenido, ExperienceMapper, flujo de trabajo de publicación
- implementation-examples: Ejemplos de código reales: proveedores, BlockRenderer, patrones del componente Experience