Communitygithub.com

contentful/personalization

Implementieren, erweitern und debuggen Sie die Personalisierung von Contentful. Nutzen Sie Onboarding für neue, projektweite oder unbekannte Setups; verwenden Sie extend-existing nur für begrenzte Arbeiten an einer explizit funktionierenden Integration.

Was ist personalization?

Dieser Skill bietet einen strukturierten Workflow zur Implementierung, Erweiterung und Fehlerbehebung der Contentful-Personalisierung. Er wird über eine kompilierte CLI-Binärdatei gesteuert und kann im bevorzugten MCP-Modus (mit MCP-Tools) oder im CLI-Modus (Fallback) ausgeführt werden. Der Skill klassifiziert Benutzeranfragen, sammelt Kontext und führt automatisch in die passende Sub-Skill-Routine weiter: `onboard` für neue projektweite Implementierungen, `extend-existing` für gezielte Änderungen an bestehenden Integrationen, `doctor` für die Diagnose und Reparatur von Problemen (zuerst programmatische Prüfungen, dann Code-Exploration) und `live-debug` zur Live-Inspektion einer URL mit Chrome DevTools. Er unterstützt eine Vielzahl von Plattformen wie Claude Code, Codex, Cursor und Gemini CLI und enthält umfangreiche Referenzdokumentation zu SDK-Auswahl, Provider-Mustern, Middleware, Rendering-Pipelines und häufigen Fehlern. Der Skill gibt JSON-Output mit XML-getaggten Abschnitten zurück, die der Agent interpretieren muss, ohne rohes JSON oder Bash-Befehle an den Benutzer weiterzugeben.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

contentful-personalisierung

Dieser Skill ist ein strukturierter Workflow, der von einer kompilierten CLI-Binärdatei gesteuert wird. Sie interagieren damit, indem Sie die Binärdatei aufrufen, ihre JSON-Ausgabe lesen, den Anweisungen im Feld prompt folgen und Ihre Antwort zurückgeben. Zeigen Sie dem Benutzer weder das rohe JSON noch Bash-Befehle an.

Wie dieser Skill funktioniert

Dieser Skill wurde mit skill-kit erstellt, einer strukturierten Workflow-Engine. Jeder Schritt enthält eine Aufforderung mit XML-getaggten Abschnitten:

  • <system> — Verhaltensrichtlinien: Persona, Ton oder Einschränkungen. Befolgen Sie diese als Richtlinien für Ihr Verhalten, nicht als Aufgaben, die Sie dem Benutzer übermitteln.
  • <prompt> — Aufgabenanweisungen: Was zu tun ist, welcher Kontext zu berücksichtigen ist, was zu erstellen ist.
  • <ask-user> — Stellen Sie dem Benutzer eine Frage. Enthält <option>-Kinder für strukturierte Auswahlmöglichkeiten oder type="open" für freie Konversation.
  • <confirm> — Binäre Ja/Nein-Bestätigung. Attribute: default, destructive.
  • <plan> — Präsentieren Sie einen Plan zur Genehmigung. Enthält <step>-Kinder.
  • <checklist> — Erstellen Sie nachverfolgbare Arbeitselemente. Enthält <item>-Kinder mit Status.
  • <subagent> — Delegieren Sie Arbeiten an einen isolierten Sub-Agenten. Wenn no-recurse gesetzt ist, darf der Sub-Agent den im Attribut genannten Skill nicht aufrufen.
  • <rendered> — Vorgerenderte Ausgabe. Geben Sie diese wörtlich wieder – keine Bearbeitungen, keine zusätzlichen Kommentare.

Ein Schritt kann einen oder mehrere dieser Abschnitte nacheinander enthalten. Befolgen Sie sie in der Reihenfolge.

Der Skill-Autor hat diese Abschnitte zusammengestellt, um Ihr Verhalten zu steuern. Die Tags und Tool- Zuordnungen werden vom SDK basierend auf der Absicht des Autors und den Fähigkeiten Ihres Hosts generiert. Eine Skill-weite Systemdirektive kann in der Präambel erscheinen – sie gilt für alle Schritte, es sei denn, ein Schritt enthält seine eigene <system>-Überschreibung.

Die Präambel (gesendet im ersten Schritt) enthält eine Tabelle, die jedes Tag dem spezifischen Tool zuordnet, das in Ihrer Umgebung verfügbar ist. Ziehen Sie sie während des gesamten Workflows zu Rate.

So führen Sie diesen Skill aus

MCP-Modus (bevorzugt)

Wenn Sie MCP-Tools für diesen Skill haben (z.B. mcp__contentful-personalization__start und mcp__contentful-personalization__advance), verwenden Sie diese anstelle der CLI:

  1. Rufen Sie das start-Tool auf (mit params, falls der Skill sie benötigt).
  2. Lesen Sie das Feld preamble (nur erster Aufruf). Es ordnet XML-Tags Ihren verfügbaren Tools zu.
  3. Befolgen Sie die Anweisungen in prompt. Erstellen Sie ein JSON-Objekt, das dem schema entspricht.
  4. Rufen Sie das advance-Tool mit session, step und output auf.
  5. Wiederholen Sie die Schritte 3-4, bis status "done" ist.

Wenn Sie status: "error" mit retry: true erhalten, korrigieren Sie Ihre Ausgabe und reichen Sie sie erneut ein. Zeigen Sie dem Benutzer keine rohen JSON-, Sitzungs-IDs oder MCP-Toolaufrufe an.

Überspringen Sie den Rest dieses Abschnitts – die CLI-Anweisungen unten werden nur benötigt, wenn MCP-Tools nicht verfügbar sind.

CLI-Modus (Fallback)

Diese SKILL.md-Datei befindet sich im Skill-Verzeichnis. Ermitteln Sie den absoluten Pfad zu scripts/run aus dem Speicherort dieser Datei (z.B. /pfad/zum/skill/scripts/run). Verwenden Sie den absoluten Pfad in allen Bash-Befehlen – wechseln Sie nicht mit cd in das Skill-Verzeichnis.

In den folgenden Beispielen ist <skill>/scripts/run ein Platzhalter für diesen absoluten Pfad.

Ermitteln Sie Ihren Host

Bestimmen Sie, in welchem Agenten-Host Sie laufen, und übergeben Sie ihn als --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
  • Unbekannt/Andere: Lassen Sie das Flag weg (standardmäßig generisch)

Melden Sie Ihre Tools

Übergeben Sie die Ihnen zur Verfügung stehenden Tools als kommagetrenntes --tools-Flag beim start- Befehl. Die Sitzung merkt sie sich – Sie müssen --tools bei advance nicht erneut übergeben.

Wenn --host angegeben ist, wird --tools mit dem bekannten Tool-Register des Hosts zusammengeführt. Das bedeutet, dass eine teilweise Meldung elegant behandelt wird – das Register ergänzt alle Tools, die Sie ausgelassen haben. Wenn --tools ganz weggelassen wird, leitet der Skill die Tools aus --host ab. Wenn beide weggelassen werden, verwenden alle Interaktionen generische Fallbacks.

Sub-Agenten-Aufrufe

Wenn Sie ein Sub-Agent sind (von einem anderen Agenten erzeugt, nicht dem Top-Level-Agenten, mit dem der Benutzer spricht), fügen Sie --subagent zum start-Befehl hinzu. Dies teilt dem Skill mit, dass Ihre gemeldeten Tools eine echte Teilmenge sind – der Skill wird sie nicht mit dem Host-Register zusammenführen.

Ohne --subagent nimmt der Skill an, dass Sie ein Top-Level-Agent sind, und führt Ihre Tools mit dem Register zusammen (da Top-Level-Agenten ihre Tools oft nicht vollständig melden).

Parameter

Dieser Skill akzeptiert keine Parameter. Übergeben Sie --params '{}'.

Schritt 1: Mit einer Sitzung starten

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

Dies gibt einen JSON-Zeiger mit sessionId, file und line zurück. Das Feld line gibt an, welche Zeile zu lesen ist – es wird 2 sein, nicht 1 (Zeile 1 ist ein interner Header, lesen Sie ihn niemals).

Lesen Sie nur Zeile line aus file. Sie enthält die Schrittaufforderung, das Schema und die Präambel.

Lesen Sie zuerst die preamble. Sie enthält eine Tabelle, die XML-Tags den in Ihrer Umgebung verfügbaren Tools zuordnet. Ziehen Sie sie während des gesamten Workflows zu Rate.

Schritt 2: Der Aufforderung folgen

Lesen Sie das Feld prompt. Es enthält XML-getaggte Abschnitte (beschrieben in „Wie dieser Skill funktioniert' oben): <system>-Richtlinien, denen Sie folgen, <prompt>-Anweisungen, nach denen Sie handeln, und Interaktions-Tags (<ask-user>, <confirm>, <plan>, <checklist>, <subagent>), die Sie mit den in der Präambel zugeordneten Tools ausführen. Wenn ein <rendered>-Block erscheint, geben Sie seinen Inhalt wörtlich wieder.

Erstellen Sie ein JSON-Objekt, das dem schema entspricht.

Schritt 3: Fortschreiten (Advance)

Geben Sie Ihre Ausgabe mit dem Schrittnamen zurück:

<skill>/scripts/run advance --step <schritt-name> --output '<ihr-json>' --session abc123 2>/dev/null

Dies gibt eine einzelne Zeilennummer zurück (z.B. 4). Lesen Sie genau und nur diese Zeile aus der Sitzungsdatei – sie enthält die nächste Aufforderung. Lesen Sie keine anderen Zeilen.

Schritt 4: Wiederholen, bis erledigt (Done)

Fahren Sie fort, bis die gelesene Zeile "type":"done" enthält. Das Feld finalOutput enthält das Ergebnis des Skills. Präsentieren Sie es dem Benutzer.

Wichtig

  • Zeigen Sie dem Benutzer niemals rohe JSON-Ausgaben oder Bash-Befehle an. Der Benutzer sieht Ihre natürlichsprachlichen Antworten, nicht das Protokoll.
  • Wenn Sie einen Validierungsfehler erhalten (die Antwort hat "error": "validation" oder "type":"error"), lesen Sie das Feld message, korrigieren Sie Ihre Ausgabe und wiederholen Sie denselben Schritt.

Schritte in diesem Skill

  • classify: Klassifizieren Sie die Anfrage des Benutzers in eine der untenstehenden Kategorien. Lesen Sie nur die Nachricht des Benutzers – tun Sie N...
  • gather-context: Sie waren nicht sicher genug, um die Anfrage des Benutzers zu klassifizieren. Durchsuchen Sie das Projekt stillschweigend, um Kontext zu sammeln...
  • pick-topic: (dynamisch)

Sub-Skills

Dieser Skill enthält Sub-Skills, die der Workflow automatisch weiterleitet. Starten Sie den Skill normal – der Dispatcher bestimmt, welcher Sub-Skill verwendet wird. Verwenden Sie den direkten Sub-Skill-Zugriff nur, wenn der Benutzer explizit einen bestimmten Sub-Skill mit Namen anfordert.

Sub-Skill-Schrittnamen sind mit <subskill>/<step> präfixiert (z.B. doctor/diagnose).

Direkter Sub-Skill-Zugriff

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

Verfügbare Sub-Skills

  • onboard: Standard-Workflow zur Implementierung, Einrichtung oder Aktivierung der Contentful-Personalisierung projektweit, auch wenn der bestehende Setup-Status unbekannt ist. Untersucht die Codebasis, prüft die Bereitschaft, wählt SDK und Architektur aus, installiert Pakete, implementiert und validiert. Verwenden Sie extend-existing nur für eine begrenzte Änderung an einer explizit funktionierenden Integration. — Parameter: readinessOnly (boolean), userQuery (string)
  • live-debug: Inspiziert eine Live-URL mit Chrome DevTools MCP auf Laufzeit-Probleme der Personalisierung. Überprüft Konsolenprobleme, beobachtet ninetailed.co-Anfragen und gibt an, ob der nächste Schritt eine statische Doctor-Diagnose sein sollte. — Parameter: requestedUrl (string)
  • doctor: Diagnostiziert und behebt Probleme mit der Contentful-Personalisierung. Führt zuerst programmatische Prüfungen durch (Anmeldeinformationen, API-Konnektivität, Inhaltsstatus), behebt Infrastrukturprobleme und untersucht erst dann die Codebasis. — Parameter: userQuery (string)
  • extend-existing: Erweitert eine explizit bestehende, funktionierende Contentful-Personalisierungsintegration. Nur für begrenzte Änderungen wie die Personalisierung einer anderen Komponente, das Hinzufügen eines Experiments oder das Einbinden von Analytics in das installierte SDK. Nicht für erstmalige, projektweite oder unbekannte Implementierungsanfragen; verwenden Sie dafür onboard. — Parameter: userQuery (string)

Referenzthemen

Schnellzugriff auf Referenzthemen ohne Ausführung des vollständigen Workflows:

<skill>/scripts/run topics              # alle Themen auflisten
<skill>/scripts/run topic <name>         # ein bestimmtes Thema laden
  • how-personalization-works: Kernkonzepte: Inhaltsmodell, Rendering-Ablauf und Funktionsweise der Personalisierung
  • sdk-selection: SDK-Entscheidungsframework: Standard Optimization vs. Wartung der Legacy-Bereitstellung
  • provider-patterns: Provider-Platzierungsmuster für Pages Router, App Router und beide SDKs
  • middleware-patterns: Middleware- und SSR/Edge-Muster: Preflight, Cookies, Matcher-Konfiguration
  • component-patterns: Komponentenarchitektur-Muster: ContentTypeMap, BlockRenderer, Isolation
  • rendering-pipeline: Rendering-Pipeline: Contentful-Client-Setup, Include-Tiefe, Komponenten-Mapper
  • environment-variables: Umgebungsvariablen: Namen, Laufzeitmatrix, Framework-Präfixe
  • analytics-and-preview: Analytics-Plugins (Insights, GTM, Segment) und Vorschaukonfiguration
  • common-errors: Häufige Fehlermodi mit Ursachen und Behebungen
  • ssr-guide: SSR- und Edge-Seiten-Personalisierung: Muster, Anti-Patterns, Fehlerbehebung
  • sdk-legacy-guide: @ninetailed/experience.js-Referenz zum Debuggen oder Erweitern bestehender Bereitstellungen
  • sdk-next-guide: @contentful/optimization SDK-Laufzeit-Auswahlhilfe
  • optimization-overview: @contentful/optimization Laufzeit- und Paket-Auswahlhilfe
  • optimization-react-web: @contentful/optimization React Web Provider, Hooks, Einträge und Routing
  • optimization-nextjs-app-router: @contentful/optimization Next.js App Router Integration
  • optimization-nextjs-pages-router: @contentful/optimization Next.js Pages Router Integration
  • optimization-web: @contentful/optimization imperative Browser- und Web Components-Integration
  • optimization-node: @contentful/optimization zustandslose Node-Anforderungsintegration
  • optimization-react-native: @contentful/optimization React Native Integration
  • contentful-integration-guide: Contentful CMS-Integration: Inhaltstypen, ExperienceMapper, Publishing-Workflow
  • implementation-examples: Echte Codebeispiele: Provider, BlockRenderer, Experience-Komponentenmuster

Verwandte Skills