croct-tech/agent-skills

Modelar conteúdo Croct

Projete componentes e slots, escreva seus esquemas e preencha-os com definições de conteúdo que permanecem válidas à medida que o modelo evolui. Tudo o que um esquema pode expressar também existe no editor visual do dashboard; o JSON é o mesmo modelo, escrito manualmente.

Modelo mental

Conceito	O que é	Escopo
Componente	Um esquema nomeado e reutilizável. Apenas structure e union podem ser componentes (esquemas de nível superior).	Reutilizável em slots e outros componentes
Componente regular	Uma structure com um conjunto fixo de atributos.
Componente de união	Uma union de até 10 componentes regulares; o editor escolhe uma variante por conteúdo.
Slot	Um espaço reservado no aplicativo (hero, barra de anúncios) vinculado a um componente. Contém conteúdo padrão por localidade.	Específico ao contexto; um componente pode alimentar vários slots
Definição de conteúdo	JSON contendo os valores reais para um esquema, com valores estáticos ou dinâmicos (CQL).

Camadas de conteúdo, da base ao topo: conteúdo padrão do slot (mostrado quando nenhuma experiência ou experimento corresponde, para bots excluídos pela filtragem de bots, na renderização estática e em erros) -> conteúdo da experiência (por audiência) -> conteúdo do experimento (por variante, pelo menos duas variantes) -> grupos de conteúdo (variações extras para subsegmentos dentro de uma experiência ou variante de experimento). O conteúdo de fallback reside no código-fonte do aplicativo e renderiza quando a busca falha ou o serviço está suspenso; a CLI baixa o conteúdo padrão do slot como fallback.

Decida a forma

Se você precisa...	Use
Um layout fixo (mesmo campos em todos os lugares)	Componente regular (structure)
Variações que o editor escolhe (banner de texto vs banner de imagem vs banner de formulário)	Componente de união referenciando componentes regulares
Consistência em muitos lugares (um botão CTA usado em todos os lugares)	Um componente separado, embutido com {"type": "reference", "id": "..."}
Flexibilidade em um lugar (um par título + imagem)	Um atributo structure aninhado ou primitivos, não um novo componente
Uma página com várias seções independentes	Um componente e um slot por seção, não um componente gigante
Um conjunto predefinido de opções	text com choices (Enumeração)
Upload de imagem, vídeo, áudio ou documento	reference para @croct/file (arquivos são limitados a 5 MB; para vídeos mais longos, considere um atributo de texto url)
Texto formatado editado em um editor de barra de ferramentas	reference para @croct/richText
Formatação leve em um campo de texto simples	text + um interpretador Markdown no aplicativo (veja Markdown abaixo)
Um valor usado apenas para calcular outros valores (por exemplo, uma variável dinâmica)	Atributo com "private": true

Regra prática da documentação: pergunte "Preciso de flexibilidade ou consistência?" Flexibilidade -> atributo de estrutura. Consistência -> novo componente.

Fluxo de trabalho

1. Liste as seções da página; cada seção colocada de forma independente se torna um slot.
2. Para cada slot, escolha um componente regular ou de união. Reutilize componentes existentes onde a estrutura deve permanecer consistente.
3. Escreva o esquema: atributos com type, label, description, position e optional onde o conteúdo pode estar ausente. Adicione validação (maximumLength, minimum, pattern, allowedTypes, maximumLength em listas) a partir das restrições reais da interface do usuário.
4. Verifique os limites (abaixo) antes de adicionar aninhamento. Calcule a pontuação de complexidade.
5. Escreva a definição de conteúdo padrão para cada slot e cada localidade suportada.
6. Se o componente já estiver em uso, espere uma nova versão em mudanças que quebram compatibilidade; aumente a versão do slot no aplicativo após atualizar o conteúdo afetado (veja Versionamento).

Esqueleto do esquema

Um componente regular é uma structure. Cada atributo envolve seu esquema em 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"
      }
    }
  }
}

Um componente de união mapeia IDs de componentes para referências. As chaves devem ser iguais aos IDs referenciados:

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

No aplicativo, o conteúdo do slot de união é uma união discriminada: cada variante tem uma propriedade _type definida para o ID do componente (text-hero ou image-hero acima). Ramifique em _type para renderizá-lo; veja a habilidade croct-integrate-sdk.

Tipos de atributo de relance

Tipo do dashboard	JSON do esquema
Texto	{"type": "text"} (+ minimumLength, maximumLength, pattern)
Texto de múltiplas linhas	{"type": "text", "format": "multiline"}
URL	{"type": "text", "format": "url"}
Cor	{"type": "text", "format": "color"}
Data / hora	{"type": "text", "format": "instant"} (também local-date, local-time, local-date-time, zoned-date-time)
Enumeração	{"type": "text", "choices": {"left": {"label": "Left"}}}
Rich text	{"type": "reference", "id": "@croct/richText", "properties": {}}
Arquivo	{"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)
Estrutura	{"type": "structure", "attributes": {...}}
Componente	{"type": "reference", "id": "<component-id>"}

format e choices não podem ser combinados com nenhuma outra propriedade de texto, exceto type. Listas completas de propriedades, valores padrão e limites: references/schema.md.

Limites do esquema

Limite	Valor
Atributos por estrutura	30
Profundidade de aninhamento	6 níveis
Componentes em uma união	10
Pontuação de complexidade do esquema	50
Itens da lista (maximumLength padrão do esquema)	30
maximumLength de texto	300 linha única; 1000 múltiplas linhas e URLs (limite implícito: text simples não pode combinar format com maximumLength; rich text pode)
choices de texto	20
Tamanho do arquivo	5 MB (5242880 bytes)
Rótulos / descrições	60 / 160 caracteres

Pontuação de complexidade: estrutura = 1 + seus atributos; lista = 1 + seu tipo de item; primitivo = 1; união = seu membro mais complexo; referência = o componente referenciado. Uma lista de produtos com título, imagem e preço pontua 5.

Esqueleto da definição de conteúdo

Cada valor é {"type": "<tipo de conteúdo>", "value": {"type": "static" | "dynamic", ...}}. Estruturas aninham attributes; listas contêm items; conteúdo de união é uma estrutura com name definido como a chave da união.

{
  "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 é CQL (veja a habilidade croct-cql). default é usado quando a avaliação falha, retorna null ou retorna um tipo incompatível.
• nullable deve corresponder à flag optional do atributo no esquema.
• Marque atributos auxiliares como variable com "private": true no esquema para que fiquem fora do conteúdo entregue ao aplicativo.
• Limites de conteúdo: até 30 itens de lista, até 10 valores dinâmicos, pontuação de complexidade 50.
• Valores dinâmicos são um recurso do plano Scale; localização é um complemento.

Placeholders, caminhos relativos, fallbacks e todos os tipos de conteúdo: references/definition.md.

Localização

• Localidades são configuradas por workspace. Localização é um complemento.
• Forneça conteúdo padrão para cada slot por localidade suportada. Uma localidade sem conteúdo padrão usa o conteúdo da localidade padrão. Experiências e experimentos também contêm conteúdo por localidade; uma experiência sem conteúdo para uma localidade serve o conteúdo padrão do slot.
• Fallback quando a localidade solicitada está ausente: os docs do SDK dizem localidade padrão do workspace; os docs da API de Conteúdo dizem localidade padrão do slot. As documentações discordam; diga isso em vez de escolher uma.
• Solicite uma localidade no código com preferredLocale (por busca) ou defaultPreferredLocale (aplicativo todo), ou localeResolver no Next.js/Hydrogen; veja a habilidade croct-integrate-sdk.
• croct.json contém defaultLocale e locales; croct install baixa conteúdo de fallback por slot, versão e localidade. Veja a habilidade croct-use-cli.

Versionamento e mudanças que quebram compatibilidade

1. Altere o esquema do componente, por exemplo, adicione um atributo ou altere um existente (exemplo dos docs).
2. Quando a alteração afeta a estrutura do conteúdo de uma forma que pode quebrar o aplicativo, o Croct cria uma nova versão e continua servindo a versão antiga para o aplicativo.
3. Atualize o conteúdo de cada slot e experiência afetados (o dashboard os sinaliza).
4. Aumente a versão do slot no código do aplicativo, por exemplo fetchContent('home-hero@2').

Faça:

• Fixe versões de slot (home-hero@1) no código do aplicativo. IDs sem versão usam a versão mais recente, então mudanças que quebram compatibilidade entram em vigor imediatamente e podem quebrar o aplicativo.
• Atualize também o conteúdo da experiência e do experimento, não apenas o conteúdo padrão do slot.
• Mantenha o conteúdo de fallback sincronizado após as alterações (a habilidade croct-use-cli cobre sincronização).

Não faça:

• Presuma quais edições são quebradas. Os docs não as listam; confie no alerta de impacto do slot no dashboard.

Refatoração

Situação	Técnica
Uma alteração deve se aplicar à maioria, mas não a todos os usos	Duplicar e modificar: duplique o componente, aponte as poucas exceções para a cópia e altere o original
Uma alteração deve se aplicar a apenas alguns usos	Duplicar e substituir: duplique, altere a cópia, aponte esses usos para a cópia
Componente atingiu o nível máximo de aninhamento	Achatar e mesclar: mescle os atributos de uma estrutura aninhada no pai e atualize o conteúdo em todos os lugares onde é usado
Componente próximo ao limite de complexidade	Divida em componentes menores renderizados por slots separados
Estrutura atingiu o limite de 30 atributos	Orientação (os docs não têm guia para isso): agrupe atributos relacionados em estruturas aninhadas, mantendo-se dentro de 6 níveis de aninhamento, ou divida em componentes e slots separados. Versões de slot fixadas (home-hero@1) mantêm o aplicativo ativo no esquema antigo enquanto você migra

Detalhes, etapas e melhores práticas: references/design-and-refactoring.md.

Markdown em atributos de texto

• Rich text (@croct/richText) armazena Markdown produzido por um editor de barra de ferramentas; restrinja-o com allowedFormatting.
• Atributos text simples armazenam strings brutas. Para suportar Markdown lá, interprete-o no aplicativo, por exemplo com @croct/md-lite (negrito, itálico, tachado, código, link, imagem, parágrafo).
• Mantenha a formatação simples. Modele rótulos de CTA, URLs e dados de produto como atributos separados.
• Declare a sintaxe suportada na description do atributo, por exemplo "Suporta sintaxe markdown para **negrito**, *itálico* e [links](https://example.com\)."

Código de renderização: references/design-and-refactoring.md.

Armadilhas

• Criar componentes para títulos ou imagens únicos. Use primitivos ou estruturas.
• Nomes genéricos ("Cartões de produto"). Prefira nomes de propósito ("Lista de funcionalidades do produto").
• Chaves types de união que diferem dos IDs de componente referenciados: o esquema é inválido.
• Mais de uma entrada choices com "default": true: o esquema é inválido.
• Valores de data/hora sem segundos: 10:15 é inválido, 10:15:00 é válido.
• Valores dinâmicos com nullable que discorda da flag optional do esquema.
• Visualizações mostram conteúdo desatualizado quando a versão do slot da experiência difere da versão do aplicativo.

Documentação online

• Índice: https://docs.croct.com/llms.txt
• Qualquer página como markdown: https://docs.croct.com/reference/content/schema/introduction.md
• Pesquisa: https://docs.croct.com/api/search.md?term=<termos>