Einen Custom Claude Code Skill für Shopify bauen

Das Wichtigste in Kürze

• Ein Claude Code Skill ist ein Ordner mit einer SKILL.md-Datei. Das Frontmatter teilt Claude mit, wann er eingesetzt 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 per 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-Operationen brauchst.²
• Claude lädt einen Skill automatisch, wenn deine Anfrage zu seiner description passt, oder du rufst ihn direkt mit /skill-name auf.¹
• Halte die SKILL.md unter 500 Zeilen. Verschiebe langes Referenzmaterial in separat gebündelte Dateien.¹

Dieses Claude Code Shopify Skill Tutorial zeigt dir Schritt für Schritt, wie du deinen eigenen Agent Skill für die Shopify-Entwicklung baust: eine wiederverwendbare SKILL.md-Datei, die eine Liquid Section scaffoldet (generiert), sie gegen die Vorgaben deines Teams prüft und nur geladen wird, wenn du sie wirklich brauchst.

Ein Skill ist etwas anderes als das Shopify AI Toolkit Plugin. Das Plugin bietet dir Shopifys Docs, Schema-Validierung und Store-Ausführung. Ein Custom Skill codiert deine Konventionen – deine Section-Patterns, deine Namensregeln, deine Review-Checkliste. Dieser Guide behandelt Letzteres. 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 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 teilweise, daher hilft es, den Unterschied klar zu benennen.

Das wichtigste Merkmal 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. So kostet langes Referenzmaterial 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 hat seine Daseinsberechtigung. Wähle basierend darauf, was exakt abgebildet werden soll.

Das Shopify AI Toolkit verbindet Claude mit Shopifys Docs, API-Schemas, Code-Validierung und kann deinen Store über die Execute-Fähigkeiten der CLI verwalten.² Es beantwortet die Frage: “Was ist der offiziell korrekte Shopify-Weg dafür?”

Ein Custom Skill beantwortet die Frage: “Was ist unser Weg dafür?”. Baue einen, wenn:

• Du immer wieder dieselbe Checkliste zum Scaffolden einer Section in den Chat kopierst.¹
• Ein Teil in deiner CLAUDE.md eher zu einer Prozedur als zu einem reinen Hinweis herangewachsen ist.¹
• Du Namensregeln, Schema-Patterns oder eine Review-Checkliste speziell für euren Store hast.

Beide arbeiten Hand in Hand. Installiere das Plugin für Shopify-Genauigkeit. Ergänze einen Skill für euren internen Code-Style obendrauf.

Für einen breiteren Einblick in agentenbasierte Theme-Arbeit, wirf einen Blick auf unseren Guide zu Multi-Agent Shopify Theme Development.

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. Hier sind ein paar Felder, die für Shopify-Arbeiten nützlich sind:¹

Das allowed-tools-Feld räumt die Berechtigung für die aufgelisteten Tools ein, während der Skill läuft. Es schränkt jedoch nicht ein, welche Tools generell existieren. Jedes Tool bleibt aufrufbar, und deine regulären Berechtigungs-Einstellungen gelten auch weiterhin für den Rest.¹

Ordnerstruktur: Wo Skills liegen

Skills werden primär aus zwei Verzeichnissen geladen.¹

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

Committe Projekt-Skills in die Versionskontrolle, damit dein gesamtes Team dasselbe Verhalten bekommt.¹ Ein Shopify Theme-Repo mit einem geteilten Skill zum Scaffolden von Sections sorgt dafür, dass alle Entwickler Sections auf die gleiche Weise generieren.

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