Einen Custom Claude Code Skill für Shopify bauen

Wichtigste Erkenntnisse

• Ein Claude Code Skill ist ein Ordner mit einer SKILL.md-Datei. Das Frontmatter teilt Claude mit, wann er verwendet werden soll. Der Body sagt Claude, was zu tun ist.¹
• Persönliche Skills liegen unter ~/.claude/skills/<name>/SKILL.md. Projekt-Skills liegen unter .claude/skills/<name>/SKILL.md und können in Git committet 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 der description übereinstimmt, oder du ihn direkt mit /skill-name aufrufst.¹
• Halte die SKILL.md unter 500 Zeilen. Lagere langes Referenzmaterial in separate, gebündelte Dateien aus.¹

Dieses Claude Code Shopify Skill Tutorial zeigt dir, wie du deinen eigenen Agent-Skill für Shopify-Arbeiten erstellst: eine wiederverwendbare SKILL.md-Datei, die eine Liquid-Section scaffoldet, gegen eure Team-Regeln prüft und nur geladen wird, wenn du sie brauchst.

Ein Skill unterscheidet sich vom Shopify AI Toolkit Plugin. Das Plugin bietet dir Shopify-Docs, Schema-Validierung und Store-Ausführung. Ein Custom Skill beinhaltet deine Konventionen – deine Section-Muster, deine Namensregeln, deine Review-Checkliste. Dieser Guide behandelt Letzteres. Für das Setup des Plugins, sieh dir unseren Shopify AI Toolkit + Claude Code Setup Guide an.

Warum du uns vertrauen kannst

Jacques hat über 15 Jahre Erfahrung in der Entwicklung und mit hunderten von Shopify Stores gearbeitet. Wir haben Fudge entwickelt – einen AI-nativen Shopify Store Editor mit einem 5.0 Rating und einem Built for Shopify Badge. Wir bauen jeden Tag 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 Mechanik ist simpel. Die Datei besteht aus zwei Teilen: YAML-Frontmatter zwischen ----Markierungen, das Claude verrät, wann der Skill genutzt werden soll, und Markdown-Inhalt mit den Anweisungen, denen Claude bei der Ausführung des Skills folgt.¹

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

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

Diese Features überschneiden sich, daher hilft es, den Unterschied klar zu benennen.

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 auch genutzt wird. Langes Referenzmaterial kostet also fast nichts, bis du es wirklich 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.

Stolpersteine, die du 2026 vermeiden solltest

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 deutlich flotter beim Schreiben von Shopify Code. Allerdings liefert er dir nicht den Workflow, den echte Store-Changes verlangen: Drafts, Previews, Approvals und Rollbacks. Dein Code lebt in Git; der Status deines Stores jedoch nicht.

Genau diese Lücke füllt Fudge. Es ist ein KI-nativer Shopify Store Editor, der auf Basis eines Prompts markenkonforme Entwürfe (Drafts) für dich erstellt. Diese kannst du per Preview begutachten, nachbessern lassen und publishen, sobald du happy bist. Damit können auch die Leute in deinem Team Updates verschiffen, die weder Liquid schreiben noch SKILL.md-Dateien anfassen sollten. In welchen größeren Wandel das Thema passt, beleuchten wir in unserem Beitrag AI-First Shopify Development.

Schnellreferenz

Zusammenfassung

Ein Claude Code Skill ist ein kleiner, wiederverwendbarer Ordner, mit dem du Claude eure Shopify-Konventionen beibringst. Zwei Felder legen dabei den Grundstein: die description, die bestimmt, wann der Skill geladen wird, und ein Body (unter 500 Zeilen), der Claude befiehlt, was zu tun ist.¹

Baue dir einen Skill für euren internen Code-Style. Installiere dir das AI Toolkit Plugin für die absolute Shopify-Genauigkeit. Nutze am besten beides zusammen und überlasse das direkte Veröffentlichen in eurem laufenden Shop lieber den Drafts und Previews, statt den Code direkt ungefiltert ausführen zu lassen.

FAQ