Communitygithub.com

contentful/personalização

Implemente, estenda e depure a personalização do Contentful. Use o onboarding para configurações novas, de projeto inteiro ou desconhecidas; use 'estender existente' apenas para trabalho com escopo em uma integração que esteja funcionando explicitamente.

O que é personalização?

Esta skill oferece um fluxo de trabalho estruturado e orientado por um binário CLI para implementar, estender e depurar recursos de personalização do Contentful (como testes A/B, segmentação de público e variantes de conteúdo). Ela é útil para desenvolvedores que precisam configurar personalização em projetos Next.js, React ou outras plataformas compatíveis com os SDKs @contentful/optimization e @ninetailed/experience.js. A skill fornece modos MCP (preferencial) e CLI (fallback), e inclui sub-skills especializadas como 'onboard' (para configurações iniciais), 'live-debug' (para inspecionar URLs ativas), 'doctor' (para diagnosticar problemas) e 'extend-existing' (para estender integrações funcionais). Ela também oferece tópicos de referência rápida sobre conceitos como seleção de SDK, padrões de provedores, middleware e componentes, além de guias para SSR e solução de erros comuns.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

contentful-personalização

Esta skill é um fluxo de trabalho estruturado conduzido por um binário CLI compilado. Você interage com ela chamando o binário, lendo sua saída JSON, seguindo as instruções no campo prompt e passando sua resposta de volta. Não mostre o JSON bruto ou comandos Bash ao usuário.

Como esta skill funciona

Esta skill foi construída com skill-kit, um mecanismo de fluxo de trabalho estruturado. Cada etapa fornece um prompt contendo seções marcadas com XML:

  • <system> — Diretivas comportamentais: persona, tom ou restrições. Siga como diretrizes de como se comportar, não como tarefas a repassar ao usuário.
  • <prompt> — Instruções da tarefa: o que fazer, qual contexto considerar, o que produzir.
  • <ask-user> — Faça uma pergunta ao usuário. Contém filhos <option> para escolhas estruturadas, ou type="open" para conversa livre.
  • <confirm> — Confirmação sim/não. Atributos: default, destructive.
  • <plan> — Apresente um plano para aprovação. Contém filhos <step>.
  • <checklist> — Crie itens de trabalho rastreados. Contém filhos <item> com status.
  • <subagent> — Delegue trabalho a um subagente isolado. Se no-recurse estiver definido, o subagente não deve invocar a skill nomeada no atributo.
  • <rendered> — Saída pré-renderizada. Emita verbatim — sem edições, sem comentários adicionados.

Uma etapa pode conter uma ou mais dessas seções em sequência. Siga-as em ordem.

O autor da skill compôs essas seções para guiar seu comportamento. As tags e mapeamentos de ferramentas são gerados pelo SDK com base na intenção do autor e nas capacidades do seu hospedeiro. Uma diretiva de sistema no nível da skill pode aparecer no preâmbulo — ela se aplica a todas as etapas, a menos que uma etapa inclua sua própria substituição <system>.

O preâmbulo (enviado na primeira etapa) contém uma tabela mapeando cada tag para a ferramenta específica disponível em seu ambiente. Consulte-a ao longo do fluxo de trabalho.

Como executar esta skill

Modo MCP (preferencial)

Se você possui ferramentas MCP para esta skill (ex.: mcp__contentful-personalization__start e mcp__contentful-personalization__advance), use-as em vez da CLI:

  1. Chame a ferramenta start (com params se a skill os exigir).
  2. Leia o campo preamble (apenas na primeira chamada). Ele mapeia tags XML para suas ferramentas disponíveis.
  3. Siga as instruções do prompt. Produza um objeto JSON correspondente ao schema.
  4. Chame a ferramenta advance com session, step e output.
  5. Repita os passos 3-4 até que status seja "done".

Se você receber status: "error" com retry: true, corrija sua saída e reenvie. Não mostre JSON bruto, IDs de sessão ou chamadas de ferramenta MCP ao usuário.

Pule o resto desta seção — as instruções da CLI abaixo só são necessárias quando as ferramentas MCP não estão disponíveis.

Modo CLI (fallback)

Este arquivo SKILL.md está dentro do diretório da skill. Resolva o caminho absoluto para scripts/run a partir da localização deste arquivo (ex.: /caminho/para/skill/scripts/run). Use o caminho absoluto em todos os comandos Bash — não use cd para o diretório da skill.

Nos exemplos abaixo, <skill>/scripts/run é um placeholder para este caminho absoluto.

Detecte seu hospedeiro

Determine em qual hospedeiro agente você está executando e passe-o 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
  • Desconhecido/outro: omita a flag (padrão genérico)

Reporte suas ferramentas

Passe as ferramentas que você possui disponíveis como uma flag --tools separada por vírgulas no comando start. A sessão as lembra — você não precisa passar --tools no advance.

Quando --host é fornecido, --tools é mesclado com o registro de ferramentas conhecido do hospedeiro. Isso significa que o relatório parcial é tratado com elegância — o registro preenche quaisquer ferramentas que você omitir. Se --tools for omitido completamente, a skill infere ferramentas a partir de --host. Se ambos forem omitidos, todas as interações usam fallbacks genéricos.

Invocações de subagente

Se você é um subagente (gerado por outro agente, não o agente de nível superior com quem o usuário está falando), adicione --subagent ao comando start. Isso informa à skill que suas ferramentas reportadas são um subconjunto genuíno — a skill não as mesclará com o registro do hospedeiro.

Sem --subagent, a skill assume que você é um agente de nível superior e mescla suas ferramentas com o registro (já que agentes de nível superior frequentemente subnotificam suas ferramentas).

Parâmetros

Esta skill não aceita parâmetros. Passe --params '{}'.

Passo 1: Inicie com uma sessão

<skill>/scripts/run --params '{}' --host claude-code --tools <suas-ferramentas> --session new 2>/dev/null

Isso retorna um ponteiro JSON com sessionId, file e line. O campo line informa qual linha ler — será 2, não 1 (a linha 1 é um cabeçalho interno, nunca a leia).

Leia apenas a linha line do file. Ela contém o prompt da etapa, esquema e preâmbulo.

Leia o preamble primeiro. Ele contém uma tabela mapeando tags XML para as ferramentas disponíveis em seu ambiente. Consulte-a ao longo do fluxo de trabalho.

Passo 2: Siga o prompt

Leia o campo prompt. Ele contém seções marcadas com XML (descritas em "Como esta skill funciona" acima): diretivas <system> a seguir, instruções <prompt> para agir e tags de interação (<ask-user>, <confirm>, <plan>, <checklist>, <subagent>) para executar usando as ferramentas mapeadas no preâmbulo. Se um bloco <rendered> aparecer, emita seu conteúdo verbatim.

Produza um objeto JSON correspondente ao schema.

Passo 3: Avance

Passe sua saída de volta com o nome da etapa:

<skill>/scripts/run advance --step <nome-da-etapa> --output '<seu-json>' --session abc123 2>/dev/null

Isso retorna um único número de linha (ex.: 4). Leia exatamente e apenas essa linha do arquivo de sessão — ela contém o próximo prompt. Não leia nenhuma outra linha.

Passo 4: Repita até concluir

Continue avançando até que a linha lida contenha "type":"done". O campo finalOutput contém o resultado da skill. Apresente-o ao usuário.

Importante

  • Nunca mostre saída JSON bruta ou comandos Bash ao usuário. O usuário vê suas respostas em linguagem natural, não o protocolo.
  • Se você receber um erro de validação (a resposta tem "error": "validation" ou "type":"error"), leia o campo message, corrija sua saída e tente novamente a mesma etapa.

Etapas nesta skill

  • classify: Classifique a solicitação do usuário em uma das categorias abaixo. Leia apenas a mensagem do usuário — não faça...
  • gather-context: Você não estava confiante o suficiente para classificar a solicitação do usuário. Explore silenciosamente o projeto para coletar...
  • pick-topic: (dinâmico)

Sub-skills

Esta skill contém sub-skills para as quais o fluxo de trabalho roteia automaticamente. Inicie a skill normalmente — o despachante determinará qual sub-skill usar. Use o acesso direto à sub-skill apenas se o usuário solicitar explicitamente uma sub-skill específica pelo nome.

Os nomes das etapas das sub-skills são prefixados: <subskill>/<step> (ex.: doctor/diagnose).

Acesso direto à sub-skill

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

Sub-skills disponíveis

  • onboard: Fluxo de trabalho padrão para implementar, configurar ou habilitar personalização Contentful em todo o projeto, inclusive quando o estado da configuração existente é desconhecido. Explora o codebase, verifica a prontidão, escolhe SDK e arquitetura, instala pacotes, implementa e valida. Use extend-existing apenas para uma alteração com escopo em uma integração explicitamente funcional. — params: readinessOnly (booleano), userQuery (string)
  • live-debug: Inspecione uma URL ativa com Chrome DevTools MCP para problemas de personalização em tempo de execução. Verifica problemas no console, observa requisições ninetailed.co e relata se o próximo passo deve ser o diagnóstico estático do doctor. — params: requestedUrl (string)
  • doctor: Diagnostique e corrija problemas de personalização Contentful. Executa verificações programáticas primeiro (credenciais, conectividade da API, estado do conteúdo), corrige problemas de infraestrutura e só então explora o codebase. — params: userQuery (string)
  • extend-existing: Estenda uma integração existente e funcional de personalização Contentful. Use apenas para alterações com escopo, como personalizar outro componente, adicionar um experimento ou conectar análise ao SDK instalado. Não use para solicitações de implementação em primeira vez, em todo o projeto ou com estado desconhecido; use onboard para essas. — params: userQuery (string)

Tópicos de referência

Tópicos de referência rápida acessíveis sem executar o fluxo de trabalho completo:

<skill>/scripts/run topics              # lista todos os tópicos
<skill>/scripts/run topic <nome>         # carrega um tópico específico
  • how-personalization-works: Conceitos principais: modelo de conteúdo, fluxo de renderização e como a personalização funciona
  • sdk-selection: Estrutura de decisão do SDK: padrão Optimization vs. manutenção de implantação legada
  • provider-patterns: Padrões de colocação de provedores para Pages Router, App Router e ambos os SDKs
  • middleware-patterns: Padrões de middleware e SSR/edge: preflight, cookies, configuração de matcher
  • component-patterns: Padrões de arquitetura de componentes: ContentTypeMap, BlockRenderer, isolamento
  • rendering-pipeline: Pipeline de renderização: configuração do cliente Contentful, profundidade de include, mapeador de componentes
  • environment-variables: Variáveis de ambiente: nomes, matriz de runtime, prefixos de framework
  • analytics-and-preview: Plugins de análise (Insights, GTM, Segment) e configuração de preview
  • common-errors: Modos de falha comuns com causas raiz e correções
  • ssr-guide: Personalização SSR e edge: padrões, antipadrões, solução de problemas
  • sdk-legacy-guide: Referência @ninetailed/experience.js para depurar ou estender implantações existentes
  • sdk-next-guide: Seletor de runtime do SDK @contentful/optimization
  • optimization-overview: Seletor de runtime e pacote @contentful/optimization
  • optimization-react-web: Provedor React Web, hooks, entradas e roteamento @contentful/optimization
  • optimization-nextjs-app-router: Integração @contentful/optimization Next.js App Router
  • optimization-nextjs-pages-router: Integração @contentful/optimization Next.js Pages Router
  • optimization-web: Integração imperativa de navegador e Web Components @contentful/optimization
  • optimization-node: Integração de requisição Node sem estado @contentful/optimization
  • optimization-react-native: Integração React Native @contentful/optimization
  • contentful-integration-guide: Integração CMS Contentful: tipos de conteúdo, ExperienceMapper, fluxo de publicação
  • implementation-examples: Exemplos de código reais: provedores, BlockRenderer, padrões de componente Experience

Habilidades Relacionadas