Communitygithub.com

contentful-personalization

Implémentez, étendez et déboguez la personnalisation Contentful. Utilisez onboarding pour les nouvelles configurations, et extend-existing uniquement pour des modifications ciblées sur une intégration fonctionnelle.

Qu'est-ce que contentful-personalization ?

Cette compétence fournit un workflow structuré pour implémenter, étendre et déboguer la personnalisation Contentful (incluant l'optimisation, les tests A/B, le ciblage d'audience et les variantes de contenu). Elle utilise un binaire CLI compilé et des outils MCP pour guider l'agent à travers des étapes de classification, de collecte de contexte et de sous-compétences spécialisées. Les sous-compétences incluent `onboard` (pour les nouvelles configurations), `live-debug` (inspection de pages en production avec Chrome DevTools), `doctor` (diagnostic et correction) et `extend-existing` (modifications ciblées). L'agent interagit avec la compétence via des appels MCP ou CLI, en suivant des sections balisées XML (`<system>`, `<prompt>`, `<ask-user>`, etc.) et en produisant des objets JSON. Elle est conçue pour des plateformes comme Claude Code, Cursor, Codex, et autres, et inclut une bibliothèque de sujets de référence pour des concepts détaillés (SDK, patterns de composants, variables d'environnement).

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait contentful-personalization ?

Cette compétence est un workflow structuré piloté par un binaire CLI compilé. Vous interagissez avec elle en appelant le binaire, en lisant sa sortie JSON, en suivant les instructions du champ prompt, et en renvoyant votre réponse. Ne montrez pas le JSON brut ou les commandes Bash à l'utilisateur.

Comment cette compétence fonctionne

Cette compétence a été construite avec skill-kit, un moteur de workflow structuré. Chaque étape fournit un prompt contenant des sections balisées XML :

  • <system> — Directives comportementales : personnalité, ton ou contraintes. Suivez-les comme des lignes directrices pour votre comportement, pas comme des tâches à transmettre à l'utilisateur.
  • <prompt> — Instructions de tâche : quoi faire, quel contexte prendre en compte, quoi produire.
  • <ask-user> — Posez une question à l'utilisateur. Contient des enfants <option> pour des choix structurés, ou type="open" pour une conversation libre.
  • <confirm> — Confirmation binaire oui/non. Attributs : default, destructive.
  • <plan> — Présentez un plan pour approbation. Contient des enfants <step>.
  • <checklist> — Créez des éléments de travail suivis. Contient des enfants <item> avec statut.
  • <subagent> — Déléguez le travail à un sous-agent isolé. Si no-recurse est défini, le sous-agent ne doit pas invoquer la compétence nommée dans l'attribut.
  • <rendered> — Sortie pré-rendue. Émettez-la textuellement — aucune modification, aucun commentaire ajouté.

Une étape peut contenir une ou plusieurs de ces sections dans l'ordre. Suivez-les dans l'ordre.

L'auteur de la compétence a composé ces sections pour guider votre comportement. Les balises et les mappings d'outils sont générés par le SDK en fonction de l'intention de l'auteur et des capacités de votre hôte. Une directive système au niveau de la compétence peut apparaître dans le préambule — elle s'applique à toutes les étapes sauf si une étape inclut sa propre surcharge <system>.

Le préambule (envoyé à la première étape) contient un tableau mappant chaque balise à l'outil spécifique disponible dans votre environnement. Référez-vous-y tout au long du workflow.

Comment exécuter cette compétence

Mode MCP (recommandé)

Si vous avez des outils MCP pour cette compétence (par exemple, mcp__contentful-personalization__start et mcp__contentful-personalization__advance), utilisez-les à la place de la CLI :

  1. Appelez l'outil start (avec params si la compétence le nécessite).
  2. Lisez le champ preamble (premier appel uniquement). Il mappe les balises XML à vos outils disponibles.
  3. Suivez les instructions du prompt. Produisez un objet JSON correspondant au schema.
  4. Appelez l'outil advance avec le session, step, et output.
  5. Répétez les étapes 3-4 jusqu'à ce que le status soit "done".

Si vous obtenez status: "error" avec retry: true, corrigez votre sortie et soumettez-la à nouveau. Ne montrez pas le JSON brut, les identifiants de session ou les appels d'outils MCP à l'utilisateur.

Sautez le reste de cette section — les instructions CLI ci-dessous ne sont nécessaires que lorsque les outils MCP ne sont pas disponibles.

Mode CLI (solution de repli)

Ce fichier SKILL.md se trouve dans le répertoire de la compétence. Résolvez le chemin absolu vers scripts/run à partir de l'emplacement de ce fichier (par exemple, /chemin/vers/la-competence/scripts/run). Utilisez le chemin absolu dans toutes les commandes Bash — ne faites pas cd dans le répertoire de la compétence.

Dans les exemples ci-dessous, <competence>/scripts/run est un espace réservé pour ce chemin absolu.

Détecter votre hôte

Déterminez dans quel hôte agent vous vous exécutez, et passez-le comme --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
  • Inconnu/autre : omettez le drapeau (par défaut générique)

Signaler vos outils

Passez les outils dont vous disposez sous forme d'un drapeau --tools séparé par des virgules sur la commande start. La session les mémorise — vous n'avez pas besoin de passer --tools sur advance.

Lorsque --host est fourni, --tools est fusionné avec le registre d'outils connu de l'hôte. Cela signifie que le signalement partiel est géré avec élégance — le registre complète tous les outils que vous omettez. Si --tools est complètement omis, la compétence déduit les outils de --host. Si les deux sont omis, toutes les interactions utilisent des solutions de repli génériques.

Invocations de sous-agents

Si vous êtes un sous-agent (engendré par un autre agent, pas l'agent de premier niveau avec lequel l'utilisateur parle), ajoutez --subagent à la commande start. Cela indique à la compétence que vos outils signalés sont un véritable sous-ensemble — la compétence ne les fusionnera pas avec le registre de l'hôte.

Sans --subagent, la compétence suppose que vous êtes un agent de premier niveau et fusionne vos outils avec le registre (car les agents de premier niveau sous-signalent souvent leurs outils).

Paramètres

Cette compétence ne prend aucun paramètre. Passez --params '{}'.

Étape 1 : Démarrer avec une session

<competence>/scripts/run --params '{}' --host claude-code --tools <vos-outils> --session new 2>/dev/null

Cela renvoie un pointeur JSON avec sessionId, file et line. Le champ line vous indique quelle ligne lire — ce sera 2, pas 1 (la ligne 1 est un en-tête interne, ne la lisez jamais).

Lisez uniquement la ligne line du fichier file. Elle contient le prompt de l'étape, le schéma et le préambule.

Lisez le preamble en premier. Il contient un tableau mappant les balises XML aux outils disponibles dans votre environnement. Référez-vous-y tout au long du workflow.

Étape 2 : Suivre le prompt

Lisez le champ prompt. Il contient des sections balisées XML (décrites dans "Comment cette compétence fonctionne" ci-dessus) : des directives <system> à suivre, des instructions <prompt> sur lesquelles agir, et les balises d'interaction (<ask-user>, <confirm>, <plan>, <checklist>, <subagent>) à exécuter en utilisant les outils mappés dans le préambule. Si un bloc <rendered> apparaît, émettez son contenu textuellement.

Produisez un objet JSON correspondant au schema.

Étape 3 : Avancer

Passez votre sortie avec le nom de l'étape :

<competence>/scripts/run advance --step <nom-de-l-etape> --output '<votre-json>' --session abc123 2>/dev/null

Cela renvoie un seul numéro de ligne (par exemple, 4). Lisez exactement et uniquement cette ligne du fichier de session — elle contient le prochain prompt. Ne lisez aucune autre ligne.

Étape 4 : Répéter jusqu'à la fin

Continuez à avancer jusqu'à ce que la ligne que vous lisez contienne "type":"done". Le champ finalOutput contient le résultat de la compétence. Présentez-le à l'utilisateur.

Important

  • Ne montrez jamais la sortie JSON brute ou les commandes Bash à l'utilisateur. L'utilisateur voit vos réponses en langage naturel, pas le protocole.
  • Si vous obtenez une erreur de validation (la réponse contient "error": "validation" ou "type":"error"), lisez le champ message, corrigez votre sortie, et réessayez la même étape.

Étapes de cette compétence

  • classify : Classifiez la demande de l'utilisateur dans l'une des catégories ci-dessous. Lisez uniquement le message de l'utilisateur — ne fait...
  • gather-context : Vous n'étiez pas assez confiant pour classer la demande de l'utilisateur. Explorez silencieusement le projet pour rass...
  • pick-topic : (dynamique)

Sous-compétences

Cette compétence contient des sous-compétences que le workflow achemine automatiquement. Démarrez la compétence normalement — le répartiteur déterminera quelle sous-compétence utiliser. Utilisez l'accès direct à la sous-compétence uniquement si l'utilisateur demande explicitement une sous-compétence spécifique par son nom.

Les noms des étapes des sous-compétences sont préfixés : <sous-competence>/<etape> (par exemple, doctor/diagnose).

Accès direct à une sous-compétence

<competence>/scripts/run <sous-competence> --params '<json>' --session new
<competence>/scripts/run <sous-competence> advance --session <id>

Sous-compétences disponibles

  • onboard : Workflow par défaut pour implémenter, configurer ou activer la personnalisation Contentful à l'échelle du projet, y compris lorsque l'état de la configuration existante est inconnu. Explore le codebase, vérifie l'état de préparation, choisit le SDK et l'architecture, installe les packages, implémente et valide. Utilisez extend-existing uniquement pour une modification ciblée d'une intégration fonctionnelle. — params : readinessOnly (booléen), userQuery (chaîne)
  • live-debug : Inspecte une URL en production avec Chrome DevTools MCP pour les problèmes de personnalisation au runtime. Vérifie les problèmes de console, observe les requêtes vers ninetailed.co, et signale si la prochaine étape doit être un diagnostic statique du docteur. — params : requestedUrl (chaîne)
  • doctor : Diagnostique et corrige les problèmes de personnalisation Contentful. Exécute d'abord des vérifications programmatiques (identifiants, connectivité API, état du contenu), corrige les problèmes d'infrastructure, puis explore le codebase. — params : userQuery (chaîne)
  • extend-existing : Étendre une intégration de personnalisation Contentful existante et fonctionnelle. Utilisez uniquement pour des modifications ciblées comme la personnalisation d'un autre composant, l'ajout d'une expérience, ou le branchement d'analytiques dans le SDK installé. Pas pour les demandes d'implémentation pour la première fois, à l'échelle du projet ou avec un état inconnu ; utilisez onboard pour celles-ci. — params : userQuery (chaîne)

Sujets de référence

Sujets à accès rapide disponibles sans exécuter le workflow complet :

<competence>/scripts/run topics              # liste tous les sujets
<competence>/scripts/run topic <nom>         # charge un sujet spécifique
  • how-personalization-works : Concepts clés : modèle de contenu, flux de rendu et comment la personnalisation fonctionne
  • sdk-selection : Cadre de décision SDK : optimisation par défaut vs maintenance de déploiement hérité
  • provider-patterns : Modèles de placement des fournisseurs pour Pages Router, App Router et les deux SDK
  • middleware-patterns : Modèles de middleware et SSR/edge : pré-vérification, cookies, configuration de matcher
  • component-patterns : Modèles d'architecture de composants : ContentTypeMap, BlockRenderer, isolation
  • rendering-pipeline : Pipeline de rendu : configuration du client Contentful, profondeur d'inclusion, mappeur de composants
  • environment-variables : Variables d'environnement : noms, matrice d'exécution, préfixes du framework
  • analytics-and-preview : Plugins d'analytique (Insights, GTM, Segment) et configuration de prévisualisation
  • common-errors : Modes d'échec courants avec causes profondes et correctifs
  • ssr-guide : Personnalisation SSR et côté edge : modèles, anti-modèles, dépannage
  • sdk-legacy-guide : Référence @ninetailed/experience.js pour déboguer ou étendre les déploiements existants
  • sdk-next-guide : Sélecteur de runtime du SDK @contentful/optimization
  • optimization-overview : Sélecteur de runtime et de package @contentful/optimization
  • optimization-react-web : Fournisseur React Web, hooks, entrées et routage @contentful/optimization
  • optimization-nextjs-app-router : Intégration App Router Next.js @contentful/optimization
  • optimization-nextjs-pages-router : Intégration Pages Router Next.js @contentful/optimization
  • optimization-web : Intégration impérative navigateur et Web Components @contentful/optimization
  • optimization-node : Intégration requête Node sans état @contentful/optimization
  • optimization-react-native : Intégration React Native @contentful/optimization
  • contentful-integration-guide : Intégration CMS Contentful : types de contenu, ExperienceMapper, workflow de publication
  • implementation-examples : Exemples de code réels : fournisseurs, BlockRenderer, modèles de composants Experience

Skills associés