croct-tech/agent-skills

Croct-Inhalte modellieren

Komponenten und Slots entwerfen, ihre Schemas schreiben und mit Inhaltsdefinitionen füllen, die auch bei Weiterentwicklung des Modells gültig bleiben. Alles, was ein Schema ausdrücken kann, existiert auch im visuellen Editor des Dashboards. Das JSON ist dasselbe Modell, nur von Hand geschrieben.

Mentales Modell

Konzept	Was es ist	Gültigkeitsbereich
Komponente	Ein benanntes, wiederverwendbares Schema. Nur structure und union können Komponenten sein (Top-Level-Schemas).	Wiederverwendbar über Slots und andere Komponenten hinweg
Reguläre Komponente	Eine structure mit einem festen Satz von Attributen.
Union-Komponente	Eine union aus bis zu 10 regulären Komponenten; der Editor wählt pro Inhalt eine Variante aus.
Slot	Ein Platzhalter in der App (Hero, Ankündigungsleiste), der an eine Komponente gebunden ist. Enthält Standard-Inhalte pro Gebietsschema.	Kontextspezifisch; eine Komponente kann mehrere Slots bedienen
Inhaltsdefinition	JSON, das die tatsächlichen Werte für ein Schema enthält, mit statischen oder dynamischen (CQL) Werten.

Inhalts-Ebenen, von der Basis bis zur Spitze: Slot-Standardinhalt (wird angezeigt, wenn kein Erlebnis oder Experiment passt, für Bots, die durch Bot-Filterung ausgeschlossen sind, bei statischem Rendering und bei Fehlern) -> Erlebnisinhalt (pro Zielgruppe) -> Experimentinhalt (pro Variante, mindestens zwei Varianten) -> Inhaltsgruppen (zusätzliche Variationen für Untersegmente innerhalb einer Erlebnis- oder Experimentvariante). Fallback-Inhalt befindet sich im Quellcode der App und wird gerendert, wenn das Abrufen fehlschlägt oder der Dienst ausgesetzt ist. Die CLI lädt den Slot-Standardinhalt als Fallback herunter.

Die Form festlegen

Wenn Sie brauchen ...	Verwenden Sie ...
Ein festes Layout (gleiche Felder überall)	Reguläre Komponente (structure)
Variationen, zwischen denen der Editor wählt (Textbanner vs. Bildbanner vs. Formularbanner)	Union-Komponente, die auf reguläre Komponenten verweist
Konsistenz über viele Stellen hinweg (ein CTA-Button, der überall verwendet wird)	Eine separate Komponente, eingebettet mit {"type": "reference", "id": "..."}
Flexibilität an einer Stelle (ein Titel + Bild-Paar)	Ein verschachteltes structure-Attribut oder Primitive, keine neue Komponente
Eine Seite mit mehreren unabhängigen Abschnitten	Eine Komponente und ein Slot pro Abschnitt, nicht eine riesige Komponente
Einen vordefinierten Satz von Optionen	text mit choices (Aufzählung)
Bild-, Video-, Audio- oder Dokument-Upload	reference auf @croct/file (Dateien sind auf 5 MB begrenzt; für längere Videos erwägen Sie stattdessen ein url-Textattribut)
Formatierten Text, der in einem Toolbar-Editor bearbeitet wird	reference auf @croct/richText
Leichte Formatierung in einem Klartextfeld	text + einen Markdown-Parser in der App (siehe Markdown unten)
Einen Wert, der nur zur Berechnung anderer Werte verwendet wird (z.B. eine dynamische Variable)	Attribut mit "private": true

Faustregel aus der Dokumentation: Fragen Sie sich „Brauche ich Flexibilität oder Konsistenz?" Flexibilität -> Strukturattribut. Konsistenz -> neue Komponente.

Arbeitsablauf

1. Listen Sie die Abschnitte der Seite auf; jeder unabhängig platzierte Abschnitt wird zu einem Slot.
2. Wählen Sie für jeden Slot eine reguläre oder eine Union-Komponente aus. Verwenden Sie vorhandene Komponenten wieder, wenn die Struktur konsistent bleiben soll.
3. Schreiben Sie das Schema: Attribute mit type, label, description, position und optional, wo Inhalt fehlen kann. Fügen Sie Validierung (maximumLength, minimum, pattern, allowedTypes, maximumLength bei Listen) aus den tatsächlichen UI-Einschränkungen hinzu.
4. Überprüfen Sie die Grenzen (unten), bevor Sie Verschachtelungen hinzufügen. Berechnen Sie den Komplexitätsscore.
5. Schreiben Sie die Standard-Inhaltsdefinition für jeden Slot und jedes unterstützte Gebietsschema.
6. Wenn die Komponente bereits verwendet wird, erwarten Sie eine neue Version bei bahnbrechenden Änderungen; erhöhen Sie die Slot-Version in der App nach dem Aktualisieren der betroffenen Inhalte (siehe Versionierung).

Schema-Skelett

Eine reguläre Komponente ist eine structure. Jedes Attribut kapselt sein Schema in type:

{
  "type": "structure",
  "title": "CTA-Button",
  "description": "Ein Call-to-Action-Button, der auf eine Seite verlinkt.",
  "attributes": {
    "label": {
      "label": "Beschriftung",
      "description": "Der auf dem Button angezeigte Text.",
      "position": 0,
      "type": {
        "type": "text"
      }
    },
    "link": {
      "label": "Link",
      "description": "Die URL der zu verlinkenden Seite.",
      "position": 1,
      "type": {
        "type": "text"
      }
    }
  }
}

Eine Union-Komponente ordnet Komponenten-IDs Referenzen zu. Schlüssel müssen mit den referenzierten IDs übereinstimmen:

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

In der App ist der Union-Slot-Inhalt eine diskriminierte Union: Jede Variante hat eine _type-Eigenschaft, die auf die Komponenten-ID gesetzt ist (text-hero oder image-hero oben). Verzweigen Sie nach _type, um es zu rendern; siehe den Skill croct-integrate-sdk.

Attributtypen auf einen Blick

Dashboard-Typ	Schema-JSON
Text	{"type": "text"} (+ minimumLength, maximumLength, pattern)
Mehrzeiliger Text	{"type": "text", "format": "multiline"}
URL	{"type": "text", "format": "url"}
Farbe	{"type": "text", "format": "color"}
Datum / Uhrzeit	{"type": "text", "format": "instant"} (auch local-date, local-time, local-date-time, zoned-date-time)
Aufzählung	{"type": "text", "choices": {"left": {"label": "Links"}}}
Rich Text	{"type": "reference", "id": "@croct/richText", "properties": {}}
Datei	{"type": "reference", "id": "@croct/file", "properties": {}}
Zahl	{"type": "number"} (+ integer, minimum, maximum)
Boolean	{"type": "boolean"} (+ label.true, label.false, default)
Liste	{"type": "list", "items": {...}} (+ itemLabel, minimumLength, maximumLength)
Struktur	{"type": "structure", "attributes": {...}}
Komponente	{"type": "reference", "id": "<komponenten-id>"}

format und choices können nicht mit einer anderen Texteigenschaft außer type kombiniert werden. Vollständige Eigenschaftslisten, Standardwerte und Grenzen: references/schema.md.

Schema-Grenzen

Grenze	Wert
Attribute pro Struktur	30
Verschachtelungstiefe	6 Ebenen
Komponenten in einer Union	10
Schema-Komplexitätsscore	50
Listenelemente (Schema-Standard maximumLength)	30
Text maximumLength	300 einzeilig; 1000 mehrzeilig und URLs (implizite Begrenzung: einfacher text kann format nicht mit maximumLength kombinieren; Rich Text kann)
Text choices	20
Dateigröße	5 MB (5242880 Bytes)
Labels / Beschreibungen	60 / 160 Zeichen

Komplexitätsscore: Struktur = 1 + ihre Attribute; Liste = 1 + ihr Elementtyp; primitiv = 1; Union = ihr komplexestes Mitglied; Referenz = die referenzierte Komponente. Eine Liste von Produkten mit Titel, Bild und Preis hat einen Score von 5.

Inhaltsdefinitions-Skelett

Jeder Wert ist {"type": "<Inhaltstyp>", "value": {"type": "static" | "dynamic", ...}}. Strukturen verschachteln attributes; Listen enthalten items; Union-Inhalt ist eine Struktur mit name, das auf den Union-Schlüssel gesetzt ist.

{
  "type": "structure",
  "attributes": {
    "message": {
      "type": "text",
      "value": {"type": "static", "value": "Willkommen, {{variable}}!"}
    },
    "variable": {
      "type": "text",
      "value": {
        "type": "dynamic",
        "expression": "user's name",
        "nullable": true,
        "default": "Gast"
      }
    }
  }
}

• expression ist CQL (siehe den Skill croct-cql). default wird verwendet, wenn die Auswertung fehlschlägt, null zurückgibt oder einen inkompatiblen Typ zurückgibt.
• nullable muss mit dem optional-Flag des Attributs im Schema übereinstimmen.
• Markieren Sie Hilfsattribute wie variable im Schema als "private": true, damit sie aus dem an die App gelieferten Inhalt herausgehalten werden.
• Inhaltsgrenzen: bis zu 30 Listenelemente, bis zu 10 dynamische Werte, Komplexitätsscore 50.
• Dynamische Werte sind ein Feature des Scale-Plans; Lokalisierung ist ein Add-on.

Platzhalter, relative Pfade, Fallbacks und jeden Inhaltstyp finden Sie unter: references/definition.md.

Lokalisierung

• Gebietsschemata werden pro Arbeitsbereich konfiguriert. Lokalisierung ist ein Add-on.
• Geben Sie jedem Slot Standard-Inhalt pro unterstütztem Gebietsschema. Ein Gebietsschema ohne Standardinhalt verwendet den Inhalt des Standardgebietsschemas. Erlebnisse und Experimente enthalten ebenfalls Inhalt pro Gebietsschema; ein Erlebnis ohne Inhalt für ein Gebietsschema liefert den Standardinhalt des Slots.
• Fallback, wenn das angeforderte Gebietsschema fehlt: Die SDK-Dokumentation spricht vom Standardgebietsschema des Arbeitsbereichs; die Content-API-Dokumentation spricht vom Standardgebietsschema des Slots. Die Dokumente widersprechen sich; sagen Sie das, anstatt eine zu wählen.
• Fordern Sie ein Gebietsschema im Code mit preferredLocale (pro Abruf) oder defaultPreferredLocale (appweit) oder localeResolver in Next.js/Hydrogen an; siehe den Skill croct-integrate-sdk.
• croct.json enthält defaultLocale und locales; croct install lädt Fallback-Inhalt pro Slot, Version und Gebietsschema herunter. Siehe den Skill croct-use-cli.

Versionierung und bahnbrechende Änderungen

1. Ändern Sie das Komponenten-Schema, z.B. fügen Sie ein Attribut hinzu oder ändern Sie ein vorhandenes (das Beispiel aus der Dokumentation).
2. Wenn die Änderung die Inhaltsstruktur in einer Weise beeinflusst, die die App beschädigen könnte, erstellt Croct eine neue Version und liefert die alte Version weiterhin an die App aus.
3. Aktualisieren Sie den Inhalt jedes betroffenen Slots und Erlebnisses (das Dashboard kennzeichnet sie).
4. Erhöhen Sie die Slot-Version im App-Code, z.B. fetchContent('home-hero@2').

Do:

• Fixieren Sie Slot-Versionen (home-hero@1) im App-Code. Unversionierte IDs verwenden die neueste Version, sodass bahnbrechende Änderungen sofort wirksam werden und die App beschädigen können.
• Aktualisieren Sie auch den Inhalt von Erlebnissen und Experimenten, nicht nur den Standardinhalt von Slots.
• Halten Sie den Fallback-Inhalt nach Änderungen synchron (der Skill croct-use-cli behandelt die Synchronisierung).

Don't:

• Gehen Sie nicht davon aus, welche Bearbeitungen bahnbrechend sind. Die Dokumentation listet sie nicht auf; verlassen Sie sich auf den Slot-Auswirkungsalarm im Dashboard.

Refaktorierung

Situation	Technik
Eine Änderung soll für die meisten, aber nicht alle Verwendungen gelten	Duplizieren und ändern: Duplizieren Sie die Komponente, weisen Sie die wenigen Ausnahmen der Kopie zu und ändern Sie dann das Original
Eine Änderung soll nur für wenige Verwendungen gelten	Duplizieren und ersetzen: Duplizieren, die Kopie ändern, diese Verwendungen auf die Kopie umleiten
Komponente hat die maximale Verschachtelungsebene erreicht	Abflachen und zusammenführen: Führen Sie die Attribute einer verschachtelten Struktur in die übergeordnete Struktur zusammen und aktualisieren Sie dann den Inhalt überall dort, wo sie verwendet wird
Komponente nahe der Komplexitätsgrenze	Teilen Sie sie in kleinere Komponenten auf, die von separaten Slots gerendert werden
Struktur hat das Limit von 30 Attributen erreicht	Anleitung (die Dokumentation hat keinen Leitfaden dafür): Gruppieren Sie verwandte Attribute in verschachtelten Strukturen, bleiben Sie innerhalb von 6 Verschachtelungsebenen, oder teilen Sie sie in separate Komponenten und Slots auf. Festgepinnte Slot-Versionen (home-hero@1) halten die Live-App auf dem alten Schema, während Sie migrieren

Details, Schritte und Best Practices: references/design-and-refactoring.md.

Markdown in Textattributen

• Rich Text (@croct/richText) speichert Markdown, das von einem Toolbar-Editor erstellt wurde; schränken Sie es mit allowedFormatting ein.
• Einfache text-Attribute speichern rohe Zeichenketten. Um dort Markdown zu unterstützen, parsen Sie es in der App, z.B. mit @croct/md-lite (fett, kursiv, durchgestrichen, Code, Link, Bild, Absatz).
• Beschränken Sie es auf einfache Formatierung. Modellieren Sie CTA-Beschriftungen, URLs und Produktdaten als separate Attribute.
• Geben Sie die unterstützte Syntax in der Attributbeschreibung an, z.B. „Unterstützt Markdown-Syntax für **fett**, *kursiv* und [Links](https://example.com\)."

Rendering-Code: references/design-and-refactoring.md.

Fallstricke

• Komponenten für einzelne Titel oder Bilder erstellen. Verwenden Sie Primitive oder Strukturen.
• Generische Namen („Produktkarten"). Bevorzugen Sie zweckorientierte Namen („Produkt-Feature-Liste").
• Union-types-Schlüssel, die von den referenzierten Komponenten-IDs abweichen: Das Schema ist ungültig.
• Mehr als ein choices-Eintrag mit "default": true: Das Schema ist ungültig.
• Datums-/Uhrzeitwerte ohne Sekunden: 10:15 ist ungültig, 10:15:00 ist gültig.
• Dynamische Werte mit nullable, das nicht mit dem optional-Flag des Schemas übereinstimmt.
• Vorschauen zeigen veralteten Inhalt, wenn die Slot-Version des Erlebnisses von der App-Version abweicht.

Live-Dokumentation

• Index: https://docs.croct.com/llms.txt
• Jede Seite als Markdown: https://docs.croct.com/reference/content/schema/introduction.md
• Suche: https://docs.croct.com/api/search.md?term=<begriffe>