Einen Custom Claude Code Skill für Shopify bauen

Key Takeaways

• Ein Claude Code Skill ist ein Ordner mit einer SKILL.md-Datei. Das Frontmatter sagt Claude, wann er ihn nutzen soll. Der Body sagt Claude, was er tun soll.¹
• Persönliche Skills liegen unter ~/.claude/skills/<name>/SKILL.md. Projekt-Skills liegen unter .claude/skills/<name>/SKILL.md und können in Git eingecheckt werden.¹
• Baue einen Skill, wenn du immer wieder dieselbe Shopify-Checkliste in den Chat kopierst. Installiere das Shopify AI Toolkit Plugin, wenn du Docs, Schema-Validierung und Store-Ausführung brauchst.²
• Claude lädt einen Skill automatisch, wenn deine Anfrage mit seiner description übereinstimmt, oder du ihn direkt mit /skill-name aufrufst.¹
• Halte SKILL.md unter 500 Zeilen. Lagere langes Referenzmaterial in separate gebündelte Dateien aus.¹

Das offizielle AI Toolkit Plugin von Shopify bietet bereits Claude Code Skills für Shopify-Docs und -Validierung (claude plugin install shopify-ai-toolkit@claude-plugins-official). Um zusätzlich deine eigenen Konventionen festzulegen, schreibst du einen eigenen Claude Code Skill für Shopify: eine wiederverwendbare SKILL.md-Datei, die ein Grundgerüst für eine Liquid-Section erstellt, sie gegen die Regeln deines Teams prüft und nur lädt, wenn du sie brauchst. Genau darum geht es in diesem Guide.

Das Plugin liefert dir Shopifys Docs, Schema-Validierung und Store-Ausführung. Ein eigener Skill kodiert deine Konventionen – deine Section-Muster, deine Benennungsregeln, deine Review-Checkliste. Für das Plugin-Setup, sieh dir unseren Shopify AI Toolkit + Claude Code Setup Guide an.

Warum du uns vertrauen kannst

Jacques hat über 15 Jahre Entwicklungs-Erfahrung und mit hunderten Shopify-Stores gearbeitet. Wir haben Fudge, den KI-Operator für Shopify-Stores, mit einem 4.9 Rating und einem Built for Shopify-Badge gebaut. Wir bauen täglich Agent-Skills und Claude Code-Workflows für Shopify.

Was ist ein Claude Code Skill?

Ein Skill erweitert das, was Claude innerhalb von Claude Code tun kann. Du erstellst eine SKILL.md-Datei mit Anweisungen, und Claude fügt sie seinem Toolkit hinzu.¹

Die Datei besteht aus zwei Teilen: YAML-Frontmatter zwischen ----Markierungen, das Claude sagt, wann der Skill genutzt werden soll, und Markdown-Inhalt mit den Anweisungen, denen Claude folgt, wenn der Skill läuft.¹

Claude Code Skills folgen dem offenen Agent Skills-Standard, der über mehrere KI-Tools hinweg funktioniert.¹

Was ist der Unterschied zwischen einem Skill, Plugin und MCP-Server?

Das Hauptmerkmal eines Skills ist Progressive Disclosure (schrittweise Offenlegung). Die description bleibt im Kontext, damit Claude weiß, dass der Skill existiert. Der komplette Body wird erst geladen, wenn der Skill genutzt wird. Langes Referenzmaterial kostet fast nichts, bis du es brauchst.¹

Wann lädt Claude einen Skill?

Standardmäßig könnt sowohl du als auch Claude jeden Skill aufrufen.¹

Du kannst /skill-name tippen, um ihn direkt auszuführen. Claude kann ihn auch automatisch laden, wenn dein Prompt mit der description übereinstimmt.¹ Wegen genau dieses Auto-Load-Verhaltens ist eine präzise Description so wichtig – mehr dazu weiter unten.

Wann baut man einen Skill vs. wann nutzt man das Shopify AI Toolkit Plugin?

Beides existiert. Wähle basierend darauf, was du umsetzen willst.

Das Shopify AI Toolkit verbindet Claude mit den Shopify-Docs, API-Schemas und der Code-Validierung und kann deinen Store über die Execute-Funktion der CLI verwalten.² Es beantwortet die Frage: „Was ist der korrekte Shopify-Weg, um das zu tun?“

Ein Custom Skill beantwortet die Frage: „Was ist unser Weg, um das zu tun?“ Baue einen, wenn:

• Du immer wieder dieselbe Checkliste für das Scaffolding von Sections in den Chat kopierst.¹
• Ein Teil deiner CLAUDE.md eher zu einem Ablauf als zu einem einfachen Fakt angewachsen ist.¹
• Du spezifische Namensregeln, Schema-Muster oder eine Review-Checkliste für deinen Store hast.

Beides funktioniert gut zusammen. Installiere das Plugin für Shopify-Genauigkeit. Füge einen Skill für euren eigenen Style als Ergänzung hinzu.

Für einen breiteren Blick auf Agenten-basierte Theme-Arbeit, sieh dir unseren Guide zur Multi-Agent Shopify Theme-Entwicklung an.

Struktur und Frontmatter der SKILL.md

Jeder Skill braucht eine SKILL.md-Datei. Der Ordnername wird zum Befehl, den du eintippst, und die description hilft Claude zu entscheiden, wann er den Skill automatisch laden soll.¹

Ein minimaler Skill sieht so aus:

---
name: my-skill
description: Was dieser Skill macht

---
## Anweisungen

Der Markdown-Body, an den sich Claude hält, wenn der Skill ausgeführt wird.

name und description sind die beiden Frontmatter-Felder, die das meiste Gewicht haben.¹

Nützliche optionale Felder

Der Standard unterstützt noch mehr Frontmatter. Ein paar, die für die Shopify-Arbeit wichtig sind:¹

Das allowed-tools-Feld erteilt die Erlaubnis für die aufgelisteten Tools, während der Skill läuft. Es schränkt nicht ein, welche Tools existieren. Jedes Tool bleibt aufrufbar, und deine Berechtigungseinstellungen regeln weiterhin den Rest.¹

Ordnerstruktur: Wo Skills liegen

Skills werden aus zwei Hauptorten geladen.¹

Wenn Skills auf verschiedenen Ebenen denselben Namen teilen, überschreibt der persönliche den Projekt-Skill.¹

Committe Projekt-Skills in die Versionskontrolle, damit dein ganzes Team dasselbe Verhalten bekommt.¹ Ein Shopify-Theme-Repo mit einem geteilten Section-Scaffolding-Skill bedeutet, dass jeder Entwickler Sections auf dieselbe Weise generiert.

Beiliegende Dateien bündeln

Die SKILL.md ist Pflicht. Zusätzliche Dateien sind optional und lassen dich noch fähigere Skills bauen: Templates, die Claude ausfüllen soll, Beispiel-Outputs, ausführbare Skripte oder detaillierte Referenz-Docs.¹

Ein Skill, der Shopify Sections scaffoldet, könnte so aussehen:

~/.claude/skills/shopify-section/
├── SKILL.md              # Pflicht: Wann + Wie
├── references/
│   └── schema-rules.md   # On-Demand geladen
├── templates/
│   └── section.liquid    # Starter-Template
└── scripts/
    └── validate.sh       # Von Claude ausführbar

Referenziere diese Dateien aus deiner SKILL.md, damit Claude weiß, was sie enthalten und wann er sie laden soll.¹ Lass Skript-Pfade auf ${CLAUDE_SKILL_DIR} verweisen, damit sie aufgelöst werden können, egal ob der Skill auf persönlicher, Projekt- oder Plugin-Ebene installiert ist.¹

Praxisbeispiel: Ein Shopify Section Scaffolder

Hier ist ein kompletter Skill, der eine Liquid Section aus einem Prompt scaffoldet und das Ergebnis gegen deine Regeln validiert.

Schritt 1: Ordner erstellen

mkdir -p ~/.claude/skills/shopify-section

Schritt 2: SKILL.md schreiben

Speichere das unter ~/.claude/skills/shopify-section/SKILL.md:

---
name: shopify-section
description: Scaffoldet eine neue Shopify Liquid Section mit einem Schema-Block und validiert sie gegen unsere Theme-Regeln. Nutzen, wenn der User fragt, eine Section zu erstellen (create a section), hinzuzufügen (add a section) oder eine neue Section für ein Shopify-Theme zu bauen (build a new section).
---

## Eine Shopify Section scaffolden

Wenn du gebeten wirst, eine Section zu erstellen:

1. Erstelle die Datei unter `sections/` mit kebab-case Schreibweise.
2. Schreibe das Liquid-Markup, dann einen `{% schema %}` Block ans Ende.
3. Das Schema muss einen `name`, mindestens ein Setting und einen
   `presets` Eintrag enthalten, damit die Section im Theme Editor verfügbar ist.
4. Umschließe die Section mit einem Container und einer einzigartigen `id`,
   die auf `section.id` gescoped ist, damit Styles nicht leaken.
5. Füge Settings für das Padding der Section (oben und unten) als `range` Inputs hinzu.

## Vor dem Abschluss validieren

- Stelle sicher, dass jedes im Markup referenzierte Setting im Schema existiert.
- Stelle sicher, dass das Schema valides JSON ist.
- Stelle sicher, dass Inline-Styles keine hartkodierten Farben beinhalten. Ziehe Farben
  stattdessen aus den Settings.

Melde jede Regel, die durch die Section gebrochen wird, und repariere sie vor der Rückgabe.

Die description ist hier das wichtigste Element. Sie nennt die absoluten Aktionen, nach denen ein Entwickler fragen würde: “create a section”, “add a section”, “build a new section”. Genau auf diese Formulierungen springt Claude an.¹

Schritt 3: Skill aufrufen

Frage nach etwas, das auf die Description passt, und Claude lädt den Skill automatisch:¹

Create a hero section with a heading, subheading, and a background image setting.

Oder führe ihn direkt aus:¹

/shopify-section

Claude liest den Skill-Body, scaffoldet die Section ins Verzeichnis sections/ und prüft sie anhand deiner Validierungsregeln, bevor die Datei zurückgegeben wird.

Wenn du das Ergebnis zusätzlich nicht nur gegen deine eigenen Regeln, sondern auch gegen Shopifys Live-Schema-Regeln prüfen willst, kombiniere den Skill einfach mit dem AI Toolkit Plugin. Das Plugin sorgt für die formale Shopify-Korrektheit; der Skill achtet auf euren Code-Style. Prompt-Muster, die gut dazu passen, findest du in unserem Guide zu Claude Prompts für Shopify.

Häufige Stolperfallen bei Claude Code Skills

Es gibt ein paar Dinge, über die man beim Schreiben des ersten Skills schnell stolpert.

Schwammige Descriptions

Claude entscheidet anhand der description, ob er einen Skill laden soll oder nicht.¹ “Hilft mit Shopify” ist viel zu unspezifisch und wird entweder permanent oder gar nicht auslösen.

Nenne stattdessen die konkreten Aktionen: “create a section, add a section, build a new section”. Setze den wichtigsten Use Case an den Anfang, denn der Text wird bei 1.536 Zeichen gekappt und der Anfang wird am stärksten gewichtet.¹

Aufgeblähte SKILL.md-Dateien

Halte die SKILL.md immer unter 500 Zeilen. Wirf zu detailliertes Referenzmaterial besser in separate Dateien.¹

Der Body wird bei jedem Start in den Kontext geladen – ein ultralanges File erzeugt also bei jedem Durchlauf unnötige Kosten. Schiebe daher Schema-Tabellen, lange Beispiele und Edge-Case-Docs ins Verzeichnis references/ und verlinke sie dann.¹

Ungeprüfte Tool-Berechtigungen

Bei Skills, die du ins .claude/skills/-Verzeichnis eines Projekts eincheckst, ist allowed-tools erst dann aktiv, wenn du den Workspace-Trust-Dialog akzeptierst.¹

Ein Skill kann sich weite Tool-Berechtigungen automatisch einräumen. Prüfe Projekt-Skills immer, bevor du einem Repository vertraust – genau wie du andere Permission-Regeln überprüfen würdest.¹

Einen Skill bauen, wenn es schon ein Plugin gibt

Wenn das Shopify Toolkit den Job bereits macht, baut man sich mit einem Skill nur extra Maintainance-Aufwand auf. Code einen Skill nur, wenn du Konventionen festlegst, die ein Plugin prinzipiell gar nicht kennen kann. Für ein plattformspezifisches Setup auf anderen Editoren, wirf einen Blick auf unseren Shopify AI Toolkit Cursor Setup Guide.

Wo Fudge hier reinpasst

Ein Skill macht Claude schneller beim Schreiben von Shopify-Code. Er fügt nicht den Workflow hinzu, den echte Store-Änderungen brauchen: Entwürfe, Previews, Freigaben und Rollbacks. Code lebt in Git; der Store-Zustand nicht.

Diese Lücke schließt Fudge, der KI-Operator für Shopify-Stores. Sein Shopify Store Editor verwandelt einen Prompt wie „Füge eine Größentabelle zu jeder Produktseite hinzu“ in einen markengerechten Entwurf (Draft) in deinem Theme. Dein Team schaut sich eine Vorschau an, verfeinert den Draft und veröffentlicht ihn, wenn alles passt. Jede veröffentlichte Änderung behält die Version, die sie ersetzt hat, sodass du jederzeit einen Rollback durchführen kannst.

Teammitglieder, die kein Liquid schreiben, können so trotzdem Änderungen live nehmen. Und im Gegensatz zu einem Skill wartet Fudge nicht darauf, gesagt zu bekommen, was zu bauen ist: Gib ein Ziel vor und es schlägt vor, welche Änderungen zuerst gemacht werden sollten. Wie sich das in den größeren Wandel einfügt, erfährst du in unserem Beitrag über AI-first Shopify-Entwicklung.

Schnellreferenz

FAQ