Communitygithub.com

contentful/personalization

Implementa, extiende y depura la personalización de Contentful. Utiliza onboarding para configuraciones nuevas, de todo el proyecto o desconocidas; usa extend-existing solo para trabajo acotado en una integración que funcione explícitamente.

¿Qué es personalization?

Esta skill proporciona un flujo de trabajo estructurado para implementar, extender y depurar la personalización de Contentful (incluyendo A/B testing, experimentos multivariantes, segmentación de audiencias y variantes de contenido). Es útil para desarrolladores que trabajan con Contentful y necesitan configurar, diagnosticar o mejorar la personalización en sus proyectos, soportando plataformas como Next.js y usando SDKs como @contentful/optimization y @ninetailed/experience.js. La skill funciona mediante un CLI binario que guía al agente a través de pasos (clasificar, recopilar contexto, elegir tema) con indicaciones en XML, y puede delegar tareas a sub-skills como onboard, live-debug, doctor y extend-existing. También incluye una biblioteca de temas de referencia para consultar conceptos clave como selección de SDK, patrones de proveedores y resolución de errores comunes.

Compatible con✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add https://github.com/contentful/skills/tree/HEAD/skills/contentful-personalization

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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, o type="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 establece no-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:

  1. Llama a la herramienta start (con params si la skill lo requiere).
  2. Lee el campo preamble (solo en la primera llamada). Asigna las etiquetas XML a tus herramientas disponibles.
  3. Sigue las instrucciones de prompt. Produce un objeto JSON que coincida con el schema.
  4. Llama a la herramienta advance con session, step y output.
  5. Repite los pasos 3 y 4 hasta que status sea "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 campo message, 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

Skills relacionados