shadcn

Überblick über den shadcn skill

Wofür der shadcn skill gedacht ist

Der shadcn skill hilft einem AI-Assistenten dabei, sich in echten shadcn/ui-Projekten korrekt zu verhalten: Komponenten finden, sie mit der richtigen CLI installieren, Screens aus vorhandenen Primitives zusammensetzen und typische API-Fehler zwischen Presets und Komponentenfamilien vermeiden. Am nützlichsten ist er, wenn du mehr brauchst als nur „erzeuge einen Button“ und Output willst, der components.json, bereits installierte Registry-Items, dein Template und die Unterschiede zwischen base und radix berücksichtigt.

Für wen sich dieser shadcn skill eignet

Besonders passend ist der shadcn skill für:

• Entwickler, die shadcn/ui bereits einsetzen
• Teams, die ein Preset- oder Registry-basiertes UI-Setup einführen
• Personen, die AI zum Hinzufügen oder Refaktorieren von Formularen, Dialogen, Einstellungsseiten, Dashboards oder Theme-Arbeit nutzen
• alle, die möchten, dass der Assistent vor dem Schreiben von JSX zuerst den Projektkontext prüft

Wenn du weder shadcn/ui noch components.json oder die shadcn CLI verwendest, ist dieser skill wahrscheinlich zu speziell.

Die eigentliche Aufgabe dahinter

Nutzer wollen nicht bloß eine Repo-Zusammenfassung. Sie wollen, dass der Assistent:

1. das shadcn-Setup des Projekts erkennt,
2. vorhandene Komponenten auswählt, bevor er neue erfindet,
3. die korrekten CLI-Befehle und dokumentierten Flags verwendet,
4. UI nach den bevorzugten Mustern der Library zusammensetzt,
5. subtile Brüche vermeidet, etwa falsche Trigger-Komposition, fehlende Group-Wrapper oder fehlerhafte Form-Validation-Anbindung.

Genau hier liefert der shadcn skill mehr Wert als ein gewöhnlicher UI-Prompt.

Was shadcn von einem generischen Prompt unterscheidet

Die stärksten Unterschiede sind sehr praktisch:

• er startet beim Projektkontext aus npx shadcn@latest info --json
• er priorisiert search, view und docs vor eigener Implementierung
• er bildet Projektregeln aus Dateien wie rules/composition.md, rules/forms.md, rules/styling.md und rules/base-vs-radix.md ab
• er deckt Theming und Preset-Wechsel ab, nicht nur Komponenten-Snippets
• er enthält MCP-Hinweise für Registry-Suche und Installations-Workflows

Kurz gesagt: Beim shadcn skill geht es weniger um „schreibe React“ und mehr um „schreibe das richtige React für dieses shadcn-Setup“.

Wichtige Voraussetzungen und Grenzen bei der Einführung

Bevor du dich auf den shadcn skill verlässt, solltest du diese Punkte kennen:

• er setzt Zugriff auf die shadcn CLI über den Package-Runner des Projekts voraus: npx, pnpm dlx oder bunx --bun
• er ist auf dokumentierte CLI-Flags begrenzt; der skill warnt ausdrücklich davor, Flags zu erfinden
• viele gute Ergebnisse hängen von einer gültigen components.json ab
• API-Details können je nach Preset sowie zwischen base und radix variieren, daher kann blindes Wiederverwenden von Beispielen falsch sein

So verwendest du den shadcn skill

Installationskontext für den shadcn skill

Füge den skill mit dem normalen Installationsablauf des Verzeichnisses zu deiner AI-Umgebung hinzu und nutze ihn dann in einem Repo, das tatsächlich ein shadcn-Setup enthält oder enthalten soll. In der Praxis ist die Anforderung auf Repository-Seite wichtiger als der Installationsbefehl des skills: Der Assistent braucht Zugriff auf deine Projektdateien und sollte shadcn-CLI-Befehle ausführen können.

Im Zielprojekt sind diese Laufzeitbefehle relevant:

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

Ersetze sie durch pnpm dlx shadcn@latest oder bunx --bun shadcn@latest, wenn das zum Package-Manager des Projekts passt.

Lies diese Dateien zuerst, bevor du Output anforderst

Für eine schnelle und saubere Nutzung des shadcn skill solltest du diese Dateien ungefähr in dieser Reihenfolge prüfen:

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

Warum diese Reihenfolge funktioniert:

• SKILL.md definiert Auslöser und Workflow
• cli.md verhindert erratene Befehle und Flags
• die Dateien unter rules/ erfassen die Fehler, die generische Code-Erzeugung oft macht
• customization.md ist wichtig, wenn du theme-sicheres Styling statt roher Tailwind-Farbtricks brauchst
• mcp.md ist relevant, wenn dein Assistent Registries per MCP durchsuchen kann, statt Shell-Befehle auszuführen

Starte jede shadcn-Aufgabe mit Projekterkennung

Der beste erste Schritt ist:

npx shadcn@latest info --json

Damit erfährt der Assistent, was bereits konfiguriert ist, inklusive Komponenten- und Projektkontext. Besonders nützlich ist das für:

• die Prüfung, ob components.json vorhanden ist
• das Erkennen installierter Komponenten
• das Ermitteln von Setup-Details, die gültige Code-Entscheidungen beeinflussen
• das Bestätigen des Package-Runners und das Vermeiden falscher Befehlsbeispiele

Wenn du das überspringst, rückt der shadcn skill deutlich näher an einen generischen Prompt heran.

So machst du aus einem groben Ziel einen starken shadcn-Prompt

Schwacher Prompt:

Build me a profile dialog with shadcn.

Besserer Prompt:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

Warum das stärker ist:

• es erzwingt Projekterkennung
• es benennt verhaltensrelevante Preset-Unterschiede
• es legt Icon- und Styling-Vorgaben fest
• es fordert Installationsschritte an, wenn Abhängigkeiten fehlen

Nutze search und docs vor eigenem Code

Ein hochwertiger shadcn-Workflow sieht so aus:

1. in Registries nach vorhandenen Komponenten suchen,
2. Docs und Beispiele prüfen,
3. fehlende Bausteine hinzufügen,
4. den Screen zusammensetzen.

Praktische Befehle:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

Das ist besonders wichtig bei Formularen, Overlays, Navigation und Empty States, weil die Regeln des skills dort Library-Muster klar gegenüber ad-hoc-div-Strukturen bevorzugen.

Baue Screens aus vorhandenen Bausteinen zusammen

Der shadcn skill ist am stärksten, wenn du nach Komposition fragst, nicht nach monolithischer Custom-UI. Gute Aufgabenstellungen sind zum Beispiel:

• „settings page = Tabs + Card + form controls“
• „dashboard = Sidebar + Card + Chart + Table“
• „empty state = Empty component, nicht ein selbst gebautes zentriertes div“
• „callout = Alert, nicht handgebaute Boxen mit Rahmen“

Das entspricht dem bevorzugten Workflow des skills: zuerst bestehende Komponenten nutzen, dann nur bei Bedarf Varianten und Wrapper anpassen.

Unterschiede zwischen base und radix respektieren

Einer der größten Stolpersteine bei der Einführung ist die Annahme, dass alle shadcn-Beispiele austauschbar sind. Das sind sie nicht.

Der shadcn skill enthält explizite Hinweise zu base vs radix, unter anderem zu:

• asChild vs render
• Unterschieden bei der Trigger-Komposition
• nativeButton={false} in bestimmten base-only-Fällen
• API-Unterschieden bei Komponenten wie Select, ToggleGroup, Slider und Accordion

Wenn dein Prompt nicht angibt, welches Setup du verwendest, sollte der Assistent es über npx shadcn@latest info erkennen.

Verwende Styling-Vorgaben, die Theming überstehen

Für shadcn for UI Design bekommst du bessere Ergebnisse mit semantischen Tokens und CSS-variablenbasiertem Theming statt mit fest verdrahteten Tailwind-Farben.

Bevorzuge:

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

Vermeide als Standard:

• bg-red-500
• text-gray-400
• viele manuelle dark:-Overrides

Das ist wichtig, weil customization.md erklärt, dass Komponenten von CSS-Variablen erben. Wenn der Assistent semantische Tokens nutzt, skaliert dein Design über Light-/Dark-Themes und Presets deutlich sauberer.

Formulare auf die shadcn-Art umsetzen

Die evals und Regeln zeigen, dass Formularqualität ein echter Schwerpunkt ist. Gute shadcn-Nutzung bei Formularen bedeutet meist:

• vorhandene Field-Layout-Muster statt roher gestapelter divs zu verwenden
• ungültige Zustände mit data-invalid und aria-invalid zu markieren
• Switch für unabhängige Ein/Aus-Einstellungen zu verwenden
• gap-* statt space-y-* zu bevorzugen, wenn die Regeln das vorgeben

Wenn deine Aufgabe Validierung enthält, sag das ausdrücklich dazu. Sonst erzeugen viele Assistenten Formulare, die optisch plausibel wirken, aber nicht zur Library passen.

Nutze MCP, wenn dein Editor es unterstützt

Wenn deine Umgebung MCP unterstützt, kann der shadcn skill bei Registry-Operationen verlässlicher werden. mcp.md dokumentiert Tools für:

• das Auflisten von Projekt-Registries
• die Suche nach Registry-Items
• das Anzeigen von Item-Details und Dateiinhalten
• das Abrufen von Beispielen
• das Installieren von Items

Das ist nützlich, wenn du möchtest, dass der Assistent Registries im Gespräch durchsucht, statt sich nur auf CLI-Output zu stützen. info --json für die Projektkonfiguration ersetzt das aber nicht.

Praktische Prompt-Vorlage für die Nutzung des shadcn skill

Nutze diese Vorlage, wenn du hochwertigeren Output möchtest:

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

FAQ zum shadcn skill

Ist dieser shadcn skill nur zum Installieren von Komponenten da?

Nein. Aufgaben rund um shadcn install gehören dazu, aber der shadcn skill ist breiter angelegt: Projektprüfung, Registry-Suche, Komponenten-Komposition, Theming, Debugging, Preset-Wechsel und API-korrekte Refaktorierungen gehören alle zum Umfang.

Ist der shadcn skill anfängerfreundlich?

Ja, sofern du bereits mit React und einem Package-Manager vertraut bist. Der skill reduziert Rätselraten, indem er den Assistenten auf die richtigen Befehle und Regeln lenkt. Weniger anfängerfreundlich ist er, wenn du eine vollständige Einführung in React, Tailwind oder Design-Systeme von Grund auf brauchst.

Wann ist shadcn besser als ein normaler Prompt?

Nutze den shadcn skill, wenn Korrektheit vom Projektkontext abhängt:

• vorhandene components.json
• passende installierte Komponenten
• Verhalten von base vs radix
• Verwendung ausschließlich dokumentierter CLI-Flags
• Erhalt von Theme-Tokens und Library-Kompositionsregeln

Ein normaler Prompt kann plausibles JSX liefern, übersieht aber eher Installationsschritte oder verwendet Komponenten-APIs falsch.

Wann solltest du den shadcn skill nicht verwenden?

Lass ihn weg, wenn:

• dein Projekt kein shadcn/ui nutzt
• du nur generische HTML/CSS-Mockups brauchst
• du eine design-system-agnostische Antwort willst
• der Assistent keine Dateien prüfen oder Befehle ausführen kann und du den nötigen Kontext auch nicht manuell liefern kannst

In solchen Fällen ist ein breiter aufgestellter Frontend-skill meist die bessere Wahl.

Hilft der skill auch bei shadcn for UI Design-Entscheidungen?

Ja, besonders bei Komposition und Theming. Er lenkt den Assistenten in Richtung wiederverwendbarer Primitives, semantischer Farb-Tokens, korrekter Overlay-Muster und Komponentenstrukturen, die wartbarer sind als einmalig handgebaute Layouts.

Woran scheitert shadcn-Nutzung in AI-Outputs am häufigsten?

Typische Fehler sind:

• nicht unterstützte CLI-Flags zu erfinden
• die falsche Trigger-Komposition für base vs radix zu verwenden
• Custom-UI zu bauen, statt eine vorhandene Registry-Komponente zu nutzen
• mit rohen Farben zu stylen, die dem Theme-System in die Quere kommen
• erforderliche Subcomponents wie Titel, Gruppen oder Fallbacks wegzulassen

Genau in diesen Bereichen soll der shadcn skill die Qualität spürbar erhöhen.

So verbesserst du den shadcn skill

Gib dem shadcn skill fehlenden Kontext von Anfang an

Die wirksamste Verbesserung ist besserer Input. Gib nach Möglichkeit an:

• Framework oder Template (next, vite, astro usw.)
• ob components.json existiert
• base oder radix, falls bereits bekannt
• das aktuelle Icon-Set
• die Ziel-Komponente oder den Ziel-Screen
• ob die Aufgabe Installation, Refaktorierung oder Bugfixing umfasst

Schon ein einziger konkreter Satz Kontext kann verhindern, dass der Assistent die falschen APIs auswählt.

Bitte zuerst um Befehle, wenn Komponenten fehlen könnten

Wenn in deinem Projekt die benötigte Komponente eventuell noch nicht installiert ist, formuliere den Prompt etwa so:

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

Das verbessert den Output, weil Umgebungsänderungen und Implementierung getrennt werden. So lässt sich das Ergebnis leichter prüfen und anwenden.

Erzwinge regelbewussten Output für fragile Komponententypen

Bei Formularen, Dialogen, Dropdowns, Sheets, Drawers und Selects solltest du den Assistenten ausdrücklich anweisen, die Regeldateien zu befolgen. Beispiel:

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

Das ist wichtig, weil viele schwache Generierungen auf den ersten Blick gut aussehen, dabei aber Accessibility oder Kompositionsverträge brechen.

Verbessere die shadcn-Nutzung durch präzise Design-Vorgaben

Ein guter UI-Prompt ist nicht nur „make it modern“. Sinnvolle Vorgaben sind zum Beispiel:

• nur semantische Tokens
• keine rohen Palette-Utilities
• Dark Mode muss ohne manuelle Overrides funktionieren
• vorhandene Varianten vor Custom-Klassen verwenden
• vorhandene Library-Komponenten für Empty States, Alerts, Separators, Badges und Skeletons bevorzugen

Diese Details verbessern die Qualität des ersten Durchlaufs bei shadcn for UI Design deutlich.

Iteriere mit gezielten Korrekturen statt mit kompletten Neuanläufen

Nach dem ersten Output solltest du nicht nur „try again“ sagen. Besser sind gezielte Hinweise wie:

• „Refactor this to use installed shadcn components only.“
• „Make this valid for base, not radix.“
• „Replace raw color classes with semantic tokens.“
• „Add the missing title/fallback/group wrappers required by shadcn.“
• „Show the exact shadcn add commands for anything assumed.“

So bleibt gute Vorarbeit erhalten, während die Teile korrigiert werden, die am ehesten falsch sind.

Prüfe gegen die stärksten Signale im Repository

Um die Verlässlichkeit zu erhöhen, vergleiche den Output mit:

• cli.md für Befehle und Flags
• rules/composition.md für Struktur
• rules/base-vs-radix.md für API-Korrektheit
• rules/forms.md für Validierungs- und Layout-Muster
• rules/styling.md und customization.md für theme-sicheres Styling
• evals/evals.json dafür, wie „gut“ in der Praxis aussieht

Das ist der schnellste Weg, um zu erkennen, ob der shadcn skill repo-konformen Output erzeugt oder nur generischen UI-Code.