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, outype="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. Seno-recurseestiver 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:
- Chame a ferramenta
start(comparamsse a skill os exigir). - Leia o campo
preamble(apenas na primeira chamada). Ele mapeia tags XML para suas ferramentas disponíveis. - Siga as instruções do
prompt. Produza um objeto JSON correspondente aoschema. - Chame a ferramenta
advancecomsession,stepeoutput. - Repita os passos 3-4 até que
statusseja"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 campomessage, 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