croct-tech/agent-skills

Modelar contenido de Croct

Diseña componentes y ranuras, escribe sus esquemas y llénalos con definiciones de contenido que se mantengan válidas a medida que el modelo evoluciona. Todo lo que un esquema puede expresar también existe en el editor visual del panel de control; el JSON es el mismo modelo, escrito a mano.

Modelo mental

Concepto	Qué es	Ámbito
Componente	Un esquema con nombre y reutilizable. Solo structure y union pueden ser componentes (esquemas de nivel superior).	Reutilizable en ranuras y otros componentes
Componente regular	Una structure con un conjunto fijo de atributos.
Componente de unión	Una union de hasta 10 componentes regulares; el editor elige una variante por contenido.
Ranura	Un marcador de posición en la aplicación (héroe, barra de anuncios) vinculado a un componente. Contiene contenido predeterminado por localidad.	Específico del contexto; un componente puede respaldar muchas ranuras
Definición de contenido	JSON que contiene los valores reales para un esquema, con valores estáticos o dinámicos (CQL).

Capas de contenido, de la base a la cima: contenido predeterminado de ranura (se muestra cuando no coincide ninguna experiencia o experimento, a bots excluidos por el filtrado de bots, en renderizado estático y en errores) -> contenido de experiencia (por audiencia) -> contenido de experimento (por variante, al menos dos variantes) -> grupos de contenido (variaciones adicionales para subsegmentos dentro de una experiencia o variante de experimento). El contenido de respaldo reside en el código fuente de la aplicación y se renderiza cuando falla la obtención o el servicio está suspendido; la CLI descarga el contenido predeterminado de la ranura como respaldo.

Decidir la forma

Si necesitas...	Usa
Un diseño fijo (mismos campos en todas partes)	Componente regular (structure)
Variaciones entre las que el editor elige (banner de texto vs banner de imagen vs banner de formulario)	Componente de unión que referencia componentes regulares
Consistencia en muchos lugares (un botón CTA usado en todas partes)	Un componente separado, incrustado con {"type": "reference", "id": "..."}
Flexibilidad en un lugar (un par título + imagen)	Un atributo structure anidado o primitivas, no un nuevo componente
Una página con varias secciones independientes	Un componente y una ranura por sección, no un componente gigante
Un conjunto predefinido de opciones	text con choices (Enumeración)
Carga de imagen, video, audio o documento	reference a @croct/file (los archivos tienen un límite de 5 MB; para videos más largos, considera un atributo de texto url en su lugar)
Texto formateado editado en un editor de barra de herramientas	reference a @croct/richText
Formato ligero en un campo de texto plano	text + un analizador Markdown en la aplicación (ver Markdown más abajo)
Un valor usado solo para calcular otros valores (por ejemplo, una variable dinámica)	Atributo con "private": true

Regla general de la documentación: pregúntate "¿Necesito flexibilidad o consistencia?" Flexibilidad -> atributo de estructura. Consistencia -> nuevo componente.

Flujo de trabajo

1. Enumera las secciones de la página; cada sección colocada de forma independiente se convierte en una ranura.
2. Para cada ranura, elige un componente regular o de unión. Reutiliza componentes existentes donde se pretenda que la estructura se mantenga consistente.
3. Escribe el esquema: atributos con type, label, description, position y optional donde el contenido puede estar ausente. Agrega validación (maximumLength, minimum, pattern, allowedTypes, maximumLength en listas) a partir de las restricciones reales de la interfaz de usuario.
4. Verifica los límites (más abajo) antes de agregar anidamiento. Calcula la puntuación de complejidad.
5. Escribe la definición de contenido predeterminado para cada ranura y cada localidad compatible.
6. Si el componente ya está en uso, espera una nueva versión en cambios disruptivos; incrementa la versión de la ranura en la aplicación después de actualizar el contenido afectado (ver Versionado).

Esqueleto de esquema

Un componente regular es una structure. Cada atributo envuelve su esquema en type:

{
  "type": "structure",
  "title": "CTA Button",
  "description": "A call-to-action button that links to a page.",
  "attributes": {
    "label": {
      "label": "Label",
      "description": "The text displayed on the button.",
      "position": 0,
      "type": {
        "type": "text"
      }
    },
    "link": {
      "label": "Link",
      "description": "The URL of the page to link to.",
      "position": 1,
      "type": {
        "type": "text"
      }
    }
  }
}

Un componente de unión mapea IDs de componentes a referencias. Las claves deben ser iguales a los IDs referenciados:

{
  "type": "union",
  "types": {
    "text-hero": {"type": "reference", "id": "text-hero"},
    "image-hero": {"type": "reference", "id": "image-hero"}
  }
}

En la aplicación, el contenido de una ranura de unión es una unión discriminada: cada variante tiene una propiedad _type establecida al ID del componente (text-hero o image-hero arriba). Ramifica en _type para renderizarlo; consulta la skill croct-integrate-sdk.

Tipos de atributos de un vistazo

Tipo de panel de control	JSON del esquema
Texto	{"type": "text"} (+ minimumLength, maximumLength, pattern)
Texto multilínea	{"type": "text", "format": "multiline"}
URL	{"type": "text", "format": "url"}
Color	{"type": "text", "format": "color"}
Fecha / hora	{"type": "text", "format": "instant"} (también local-date, local-time, local-date-time, zoned-date-time)
Enumeración	{"type": "text", "choices": {"left": {"label": "Left"}}}
Texto enriquecido	{"type": "reference", "id": "@croct/richText", "properties": {}}
Archivo	{"type": "reference", "id": "@croct/file", "properties": {}}
Número	{"type": "number"} (+ integer, minimum, maximum)
Booleano	{"type": "boolean"} (+ label.true, label.false, default)
Lista	{"type": "list", "items": {...}} (+ itemLabel, minimumLength, maximumLength)
Estructura	{"type": "structure", "attributes": {...}}
Componente	{"type": "reference", "id": "<component-id>"}

format y choices no se pueden combinar con ninguna otra propiedad de texto excepto type. Listas completas de propiedades, valores predeterminados y límites: references/schema.md.

Límites del esquema

Límite	Valor
Atributos por estructura	30
Profundidad de anidamiento	6 niveles
Componentes en una unión	10
Puntuación de complejidad del esquema	50
Elementos de lista (maximumLength predeterminado del esquema)	30
maximumLength de texto	300 de una línea; 1000 multilínea y URL (límite implícito: text simple no puede combinar format con maximumLength; texto enriquecido sí puede)
choices de texto	20
Tamaño de archivo	5 MB (5242880 bytes)
Etiquetas / descripciones	60 / 160 caracteres

Puntuación de complejidad: estructura = 1 + sus atributos; lista = 1 + su tipo de elemento; primitiva = 1; unión = su miembro más complejo; referencia = el componente referenciado. Una lista de productos con título, imagen y precio puntúa 5.

Esqueleto de definición de contenido

Cada valor es {"type": "<tipo de contenido>", "value": {"type": "static" | "dynamic", ...}}. Las estructuras anidan attributes; las listas contienen items; el contenido de unión es una estructura con name establecido a la clave de unión.

{
  "type": "structure",
  "attributes": {
    "message": {
      "type": "text",
      "value": {"type": "static", "value": "Welcome, {{variable}}!"}
    },
    "variable": {
      "type": "text",
      "value": {
        "type": "dynamic",
        "expression": "user's name",
        "nullable": true,
        "default": "guest"
      }
    }
  }
}

• expression es CQL (consulta la skill croct-cql). default se usa cuando la evaluación falla, devuelve null o devuelve un tipo incompatible.
• nullable debe coincidir con el indicador optional del atributo en el esquema.
• Marca los atributos auxiliares como variable con "private": true en el esquema para que se mantengan fuera del contenido entregado a la aplicación.
• Límites de contenido: hasta 30 elementos de lista, hasta 10 valores dinámicos, puntuación de complejidad 50.
• Los valores dinámicos son una característica del plan Scale; la localización es un complemento.

Marcadores de posición, rutas relativas, respaldos y cada tipo de contenido: references/definition.md.

Localización

• Las localidades se configuran por espacio de trabajo. La localización es un complemento.
• Proporciona contenido predeterminado de ranura por localidad compatible. Una localidad sin contenido predeterminado utiliza el contenido de la localidad predeterminada. Las experiencias y experimentos también contienen contenido por localidad; una experiencia sin contenido para una localidad sirve el contenido predeterminado de la ranura.
• Respaldo cuando falta la localidad solicitada: los documentos del SDK dicen la localidad predeterminada del espacio de trabajo; los documentos de la API de contenido dicen la localidad predeterminada de la ranura. Los documentos discrepan; dilo en lugar de elegir uno.
• Solicita una localidad en código con preferredLocale (por obtención) o defaultPreferredLocale (en toda la aplicación), o localeResolver en Next.js/Hydrogen; consulta la skill croct-integrate-sdk.
• croct.json contiene defaultLocale y locales; croct install descarga contenido de respaldo por ranura, versión y localidad. Consulta la skill croct-use-cli.

Versionado y cambios disruptivos

1. Cambia el esquema del componente, por ejemplo agrega un atributo o cambia uno existente (ejemplo de la documentación).
2. Cuando el cambio afecte la estructura del contenido de una manera que pueda dañar la aplicación, Croct crea una nueva versión y sigue sirviendo la antigua a la aplicación.
3. Actualiza el contenido de cada ranura y experiencia afectada (el panel las marca).
4. Incrementa la versión de la ranura en el código de la aplicación, por ejemplo fetchContent('home-hero@2').

Haz:

• Fija las versiones de las ranuras (home-hero@1) en el código de la aplicación. Los IDs sin versión usan la última versión, por lo que los cambios disruptivos surten efecto inmediatamente y pueden dañar la aplicación.
• Actualiza también el contenido de experiencias y experimentos, no solo el contenido predeterminado de la ranura.
• Mantén sincronizado el contenido de respaldo después de los cambios (la skill croct-use-cli cubre la sincronización).

No hagas:

• Supongas qué ediciones son disruptivas. La documentación no las enumera; confía en la alerta de impacto de ranura del panel.

Refactorización

Situación	Técnica
Un cambio debe aplicarse a la mayoría, pero no a todos los usos	Duplicar y modificar: duplica el componente, apunta las pocas excepciones a la copia, luego cambia el original
Un cambio debe aplicarse solo a unos pocos usos	Duplicar y reemplazar: duplica, cambia la copia, apunta esos usos a la copia
El componente alcanzó el nivel máximo de anidamiento	Aplanar y fusionar: fusiona los atributos de una estructura anidada en la principal, luego actualiza el contenido en todos los lugares donde se use
Componente cerca del límite de complejidad	Dividir en componentes más pequeños renderizados por ranuras separadas
La estructura alcanzó el límite de 30 atributos	Orientación (la documentación no tiene guía para esto): agrupa atributos relacionados en estructuras anidadas, manteniéndote dentro de los 6 niveles de anidamiento, o divide en componentes y ranuras separados. Las versiones fijadas de ranura (home-hero@1) mantienen la aplicación en vivo en el esquema antiguo mientras migras

Detalles, pasos y mejores prácticas: references/design-and-refactoring.md.

Markdown en atributos de texto

• El texto enriquecido (@croct/richText) almacena Markdown producido por un editor de barra de herramientas; restringelo con allowedFormatting.
• Los atributos de texto simple (text) almacenan cadenas sin procesar. Para admitir Markdown allí, analízalo en la aplicación, por ejemplo con @croct/md-lite (negrita, cursiva, tachado, código, enlace, imagen, párrafo).
• Mantén el formato simple. Modela etiquetas CTA, URL y datos de producto como atributos separados.
• Indica la sintaxis compatible en la description del atributo, por ejemplo "Admite sintaxis markdown para **negrita**, *cursiva* y [enlaces](https://example.com\)."

Código de renderizado: references/design-and-refactoring.md.

Errores comunes

• Crear componentes para títulos o imágenes únicos. Usa primitivas o estructuras.
• Nombres genéricos ("Product cards"). Prefiere nombres de propósito ("Product feature list").
• Claves types de unión que difieren de los IDs de componente referenciados: el esquema no es válido.
• Más de una entrada choices con "default": true: el esquema no es válido.
• Valores de fecha/hora sin segundos: 10:15 no es válido, 10:15:00 sí es válido.
• Valores dinámicos con nullable que discrepa del indicador optional del esquema.
• Las vistas previas muestran contenido obsoleto cuando la versión de la ranura de la experiencia difiere de la versión de la aplicación.

Documentos en vivo

• Índice: https://docs.croct.com/llms.txt
• Cualquier página como markdown: https://docs.croct.com/reference/content/schema/introduction.md
• Búsqueda: https://docs.croct.com/api/search.md?term=<terms>