Geruyang/agent-skills-library

Export-Copy-Grenzen und Skill-Aliasnamen

Migration, Installation, Reparatur und Rückschreiben von Erfahrungen wirken nur auf die aktuell geladene Zielhost-Skill-Kopie. Die ursprünglichen Codex-Skills/MCPs, der heruntergeladene Quellcode und original-skills sind Ausgangsmaterialien und werden durch die Ausführung dieser Kopie nicht beschrieben; nur wenn der Benutzer explizit die Konfiguration des Codex-Produkts selbst anfordert, wird gemäß dem Prozess dieses Produkts vorgegangen. Wenn das Skript ein Installations- oder Statusverzeichnis benötigt, gib den Zielpfad explizit an; leite die Schreibposition nicht implizit aus CODEX_HOME ab.

Übergreifende Skill-Namen können Aliasnamen aus dem Quell-Repository verwenden. Prüfe zuerst die Skill-Alias-Tabelle, wähle bevorzugt Einträge mit derselben Quelle und demselben Plugin und verwende dann deren id zum Aufrufen oder Lesen des entsprechenden Einstiegspunkts; nimm nicht an, dass alte $skill- oder superpowers:skill-Namen im neuen Host direkt registriert sind. Wenn das Ziel nicht eindeutig ist, überprüfe es zuerst und ersetze keine echten Produktbefehle oder Shell-Umgebungsvariablen.

Conventionen zur Nutzung über Hosts hinweg

Diese Kopie ist für Clients gedacht, die Agent Skills unterstützen. Überprüfe zuerst die tatsächlich vom aktuellen Host bereitgestellten Tools, Berechtigungen und verbundenen Dienste, bevor du den Hauptarbeitsablauf ausführst. Die Werkzeugbezeichner im Originaltext sind Referenzen für Fähigkeiten; sie dürfen nur aufgerufen werden, wenn das Werkzeug tatsächlich vorhanden ist. Andere Hosts sollten die verifizierten äquivalenten MCPs, CLIs oder APIs verwenden. Schritte ohne äquivalente Fähigkeiten müssen als nicht verfügbar gemeldet werden; erfinde keine Aufrufe oder Abschlussstatus.

Skill-Ressourcen basieren auf dem Skill-Verzeichnis; die Ausgabe wird an den vom Benutzer im aktuellen Projekt angegebenen Speicherort geschrieben. Die Auslösung erfolgt über den Skill-Namen oder in natürlicher Sprache; der spezifische Kurzbefehl wird vom Host festgelegt. Namen, die echte Produkte, Modell-APIs, Protokollfelder und offizielle URLs betreffen, bleiben in ihrer ursprünglichen Bedeutung. Autorisierung, Genehmigung, Datenschutz und Tool-Bereichsbeschränkungen bleiben auch nach der Migration wirksam; erweitere die Berechtigungen nicht aus Kompatibilitätsgründen. Spezifische Abhängigkeiten und Migrationshinweise findest du in der Datei PORTABILITY.md im selben Verzeichnis.

shadcn/ui

Ein Framework zum Erstellen von UI, Komponenten und Designsystemen. Komponenten werden über die CLI als Quellcode zum Projekt des Benutzers hinzugefügt.

WICHTIG: Führe alle CLI-Befehle mit dem Paket-Runner des Projekts aus: npx shadcn@latest, pnpm dlx shadcn@latest oder bunx --bun shadcn@latest – basierend auf dem packageManager des Projekts. Die folgenden Beispiele verwenden npx shadcn@latest, ersetze es aber durch den korrekten Runner für das Projekt.

Aktueller Projektkontext

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "Kein shadcn-Projekt gefunden. Führe zuerst shadcn init aus."}'`

Das obige JSON enthält die Projektkonfiguration und die installierten Komponenten. Verwende npx shadcn@latest docs <component>, um Dokumentations- und Beispiel-URLs für jede Komponente zu erhalten.

Grundsätze

1. Verwende zuerst vorhandene Komponenten. Verwende npx shadcn@latest search, um Registries zu durchsuchen, bevor du benutzerdefinierte UI schreibst. Überprüfe auch Community-Registries.
2. Kombiniere, erfinde nicht neu. Einstellungsseite = Tabs + Card + Formularsteuerelemente. Dashboard = Sidebar + Card + Chart + Table.
3. Verwende integrierte Varianten vor benutzerdefinierten Stilen. variant="outline", size="sm" usw.
4. Verwende semantische Farben. bg-primary, text-muted-foreground – niemals Rohwerte wie bg-blue-500.

Kritische Regeln

Diese Regeln werden immer durchgesetzt. Jede verlinkt zu einer Datei mit falschen/richtigen Code-Paaren.

Styling & Tailwind → styling.md

• className für Layout, nicht für Styling. Überschreibe niemals Komponentenfarben oder Typografie.
• Kein space-x-* oder space-y-*. Verwende flex mit gap-*. Für vertikale Stapel flex flex-col gap-*.
• Verwende size-* wenn Breite und Höhe gleich sind. size-10 nicht w-10 h-10.
• Verwende die Kurzform truncate. Nicht overflow-hidden text-ellipsis whitespace-nowrap.
• Keine manuellen dark:-Farbüberschreibungen. Verwende semantische Tokens (bg-background, text-muted-foreground).
• Verwende cn() für bedingte Klassen. Schreibe keine manuellen Template-Literal-Ternaries.
• Kein manuelles z-index auf Overlay-Komponenten. Dialog, Sheet, Popover usw. verwalten ihren eigenen Stacking-Kontext.

Formulare & Eingaben → forms.md

• Formulare verwenden FieldGroup + Field. Verwende niemals ein rohes div mit space-y-* oder grid gap-* für das Formular-Layout.
• InputGroup verwendet InputGroupInput/InputGroupTextarea. Niemals rohe Input/Textarea innerhalb von InputGroup.
• Schaltflächen innerhalb von Eingaben verwenden InputGroup + InputGroupAddon.
• Optionssets (2–7 Auswahlmöglichkeiten) verwenden ToggleGroup. Keine Schleife mit Button und manuellem aktivem Zustand.
• FieldSet + FieldLegend zum Gruppieren verwandter Kontrollkästchen/Optionenfelder. Verwende kein div mit einer Überschrift.
• Feldvalidierung verwendet data-invalid + aria-invalid. data-invalid auf Field, aria-invalid auf dem Steuerelement. Für deaktiviert: data-disabled auf Field, disabled auf dem Steuerelement.

Komponentenstruktur → composition.md

• Elemente befinden sich immer in ihrer Gruppe. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Verwende asChild (radix) oder render (base) für benutzerdefinierte Auslöser. Überprüfe das Feld base von npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet und Drawer benötigen immer einen Titel. DialogTitle, SheetTitle, DrawerTitle sind für die Barrierefreiheit erforderlich. Verwende className="sr-only", wenn visuell versteckt.
• Verwende die vollständige Card-Komposition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Wirf nicht alles in CardContent.
• Button hat kein isPending/isLoading. Kombiniere mit Spinner + data-icon + disabled.
• TabsTrigger muss sich innerhalb von TabsList befinden. Platziere Auslöser niemals direkt in Tabs.
• Avatar benötigt immer AvatarFallback. Für den Fall, dass das Bild nicht geladen werden kann.

Verwende Komponenten, kein benutzerdefiniertes Markup → composition.md

• Verwende vorhandene Komponenten vor benutzerdefiniertem Markup. Überprüfe, ob eine Komponente existiert, bevor du ein gestyltes div schreibst.
• Hinweise verwenden Alert. Baue keine benutzerdefinierten gestylten Divs.
• Leere Zustände verwenden Empty. Baue kein benutzerdefiniertes Leerzustands-Markup.
• Toast über sonner. Verwende toast() von sonner.
• Verwende Separator anstelle von <hr> oder <div className="border-t">.
• Verwende Skeleton für Ladeplatzhalter. Keine benutzerdefinierten animate-pulse-Divs.
• Verwende Badge anstelle von benutzerdefinierten gestylten Spans.

Symbole → icons.md

• Symbole in Button verwenden data-icon. data-icon="inline-start" oder data-icon="inline-end" auf dem Symbol.
• Keine Größenklassen auf Symbolen innerhalb von Komponenten. Komponenten handhaben die Symbolgröße über CSS. Kein size-4 oder w-4 h-4.
• Übergebe Symbole als Objekte, nicht als Zeichenfolgeschlüssel. icon={CheckIcon}, keine Zeichenfolgensuche.

CLI

• Dekodiere oder rufe Preset-Codes niemals manuell ab. Übergib sie direkt an npx shadcn@latest init --preset <code>.

Schlüsselmuster

Dies sind die häufigsten Muster, die korrekten shadcn/ui-Code auszeichnen. Für Randfälle siehe die oben verlinkten Regeldateien.

// Formular-Layout: FieldGroup + Field, nicht div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">E-Mail</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validierung: data-invalid auf Field, aria-invalid auf dem Steuerelement.
<Field data-invalid>
  <FieldLabel>E-Mail</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Ungültige E-Mail.</FieldDescription>
</Field>

// Symbole in Schaltflächen: data-icon, keine Größenklassen.
<Button>
  <SearchIcon data-icon="inline-start" />
  Suchen
</Button>

// Abstände: gap-*, nicht space-y-*.
<div className="flex flex-col gap-4">  // richtig
<div className="space-y-4">           // falsch

// Gleiche Abmessungen: size-*, nicht w-* h-*.
<Avatar className="size-10">   // richtig
<Avatar className="w-10 h-10"> // falsch

// Statusfarben: Badge-Varianten oder semantische Tokens, nicht Rohfarben.
<Badge variant="secondary">+20,1 %</Badge>    // richtig
<span className="text-emerald-600">+20,1 %</span> // falsch

Komponentenauswahl

Bedarf	Verwendung
Schaltfläche/Aktion	Button mit passender Variante
Formulareingaben	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Umschalten (2–5 Optionen)	ToggleGroup + ToggleGroupItem
Datenanzeige	Table, Card, Badge, Avatar
Navigation	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Overlays	Dialog (modal), Sheet (Seitenpanel), Drawer (unteres Blatt), AlertDialog (Bestätigung)
Feedback	sonner (Toast), Alert, Progress, Skeleton, Spinner
Befehlspalette	Command innerhalb von Dialog
Diagramme	Chart (wrapper um Recharts)
Layout	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
Leere Zustände	Empty
Menüs	DropdownMenu, ContextMenu, Menubar
Tooltips/Informationen	Tooltip, HoverCard, Popover

Schlüsselfelder

Der injizierte Projektkontext enthält diese Schlüsselfelder:

• aliases → verwende das tatsächliche Alias-Präfix für Importe (z. B. @/, ~/), nie hartcodiert.
• isRSC → wenn true, benötigen Komponenten, die useState, useEffect, Ereignisbehandler oder Browser-APIs verwenden, "use client" am Anfang der Datei. Beziehe dich bei der Beratung zur Direktive immer auf dieses Feld.
• tailwindVersion → "v4" verwendet @theme inline-Blöcke; "v3" verwendet tailwind.config.js.
• tailwindCssFile → die globale CSS-Datei, in der benutzerdefinierte CSS-Variablen definiert sind. Bearbeite immer diese Datei, erstelle niemals eine neue.
• style → visuelle Behandlung der Komponente (z. B. nova, vega).
• base → primitive Bibliothek (radix oder base). Beeinflusst Komponenten-APIs und verfügbare Props.
• iconLibrary → bestimmt Symbol-Importe. Verwende lucide-react für lucide, @tabler/icons-react für tabler usw. Nimm niemals lucide-react an.
• resolvedPaths → genaue Dateisystem-Ziele für Komponenten, Hilfsprogramme, Hooks usw.
• framework → Routing- und Dateikonventionen (z. B. Next.js App Router vs. Vite SPA).
• packageManager → verwende dies für alle Nicht-shadcn-Abhängigkeitsinstallationen (z. B. pnpm add date-fns vs. npm install date-fns).

Siehe cli.md — info-Befehl für die vollständige Feldreferenz.

Komponentendokumentation, Beispiele und Verwendung

Führe npx shadcn@latest docs <component> aus, um die URLs für die Dokumentation, Beispiele und API-Referenz einer Komponente zu erhalten. Rufe diese URLs ab, um den tatsächlichen Inhalt zu erhalten.

npx shadcn@latest docs button dialog select

Führe beim Erstellen, Reparieren, Debuggen oder Verwenden einer Komponente immer zuerst npx shadcn@latest docs aus und rufe die URLs ab. Dies stellt sicher, dass du mit der korrekten API und den korrekten Nutzungsmustern arbeitest, anstatt zu raten.

Arbeitsablauf

1. Projektkontext abrufen – bereits oben injiziert. Führe npx shadcn@latest info erneut aus, wenn du ihn aktualisieren musst.
2. Zuerst installierte Komponenten prüfen – bevor du add ausführst, überprüfe immer die Liste der components aus dem Projektkontext oder liste das Verzeichnis resolvedPaths.ui auf. Importiere keine Komponenten, die nicht hinzugefügt wurden, und füge keine erneut hinzu, die bereits installiert sind.
3. Komponenten finden – npx shadcn@latest search.
4. Dokumentation und Beispiele abrufen – führe npx shadcn@latest docs <component> aus, um URLs zu erhalten, und rufe sie dann ab. Verwende npx shadcn@latest view, um Registry-Elemente zu durchsuchen, die du nicht installiert hast. Um Änderungen an installierten Komponenten in der Vorschau anzuzeigen, verwende npx shadcn@latest add --diff.
5. Installieren oder aktualisieren – npx shadcn@latest add. Verwende beim Aktualisieren vorhandener Komponenten --dry-run und --diff, um zuerst die Änderungen in der Vorschau anzuzeigen (siehe Komponenten aktualisieren unten).
6. Importe in Drittanbieter-Komponenten korrigieren – nach dem Hinzufügen von Komponenten aus Community-Registries (z. B. @bundui, @magicui) überprüfe die hinzugefügten Nicht-UI-Dateien auf hartcodierte Importpfade wie @/components/ui/.... Diese stimmen möglicherweise nicht mit den tatsächlichen Aliasen des Projekts überein. Verwende npx shadcn@latest info, um den korrekten ui-Alias zu erhalten (z. B. @workspace/ui/components) und schreibe die Importe entsprechend um. Die CLI schreibt Importe für ihre eigenen UI-Dateien um, aber Drittanbieter-Registry-Komponenten verwenden möglicherweise Standardpfade, die nicht zum Projekt passen.
7. Hinzugefügte Komponenten überprüfen – nach dem Hinzufügen einer Komponente oder eines Blocks aus einer beliebigen Registry lies immer die hinzugefügten Dateien und verifiziere ihre Korrektheit. Überprüfe auf fehlende Unterkomponenten (z. B. SelectItem ohne SelectGroup), fehlende Importe, falsche Komposition oder Verstöße gegen die Kritischen Regeln. Ersetze auch alle Symbolimporte durch die iconLibrary des Projekts aus dem Projektkontext (z. B. wenn das Registry-Element lucide-react verwendet, das Projekt aber hugeicons, tausche die Importe und Symbolnamen entsprechend aus). Behebe alle Probleme, bevor du fortfährst.
8. Registry muss explizit sein – wenn der Benutzer bittet, einen Block oder eine Komponente hinzuzufügen, rate nicht über die Registry. Wenn keine Registry angegeben ist (z. B. sagt der Benutzer "Füge einen Login-Block hinzu", ohne @shadcn, @tailark usw. anzugeben), frage, welche Registry verwendet werden soll. Verwende niemals standardmäßig eine Registry im Namen des Benutzers.
9. Presets wechseln – frage den Benutzer zuerst: Neuinstallation, Zusammenführen oder Überspringen?
   • Neuinstallation: npx shadcn@latest init --preset <code> --force --reinstall. Überschreibt alle Komponenten.
   • Zusammenführen: npx shadcn@latest init --preset <code> --force --no-reinstall, führe dann npx shadcn@latest info aus, um installierte Komponenten aufzulisten, und verwende dann für jede installierte Komponente --dry-run und --diff, um sie einzeln intelligent zusammenzuführen.
   • Überspringen: npx shadcn@latest init --preset <code> --force --no-reinstall. Aktualisiert nur Konfiguration und CSS, lässt Komponenten unverändert.
   • Wichtig: Führe Preset-Befehle immer im Projektverzeichnis des Benutzers aus. Die CLI behält automatisch die aktuelle Basis (base vs radix) aus der components.json bei. Wenn du ein Scratch-/Temp-Verzeichnis verwenden musst (z. B. für --dry-run-Vergleiche), übergib explizit --base <current-base> – Preset-Codes codieren die Basis nicht.

Komponenten aktualisieren

Wenn der Benutzer bittet, eine Komponente von upstream zu aktualisieren und dabei seine lokalen Änderungen beizubehalten, verwende --dry-run und --diff, um intelligent zusammenzuführen. Rufe NIEMALS rohe Quelldateien ab – der gesamte offizielle Aktualisierungsprozess erfolgt über das CLI. Das CLI behandelt das Zusammenführen von Änderungen je nach verwendetem Ansatz unterschiedlich:

• Für Radix-Komponenten (radix-Basis): Das CLI überschreibt nur bestimmte Dateien basierend auf Aktualisierungen der Registry. Nicht geänderte Dateien werden überschrieben, geänderte Dateien können Konflikte verursachen. Verwende --diff, um zu bestimmen, ob deine lokalen Änderungen betroffen sind.
• Für Base-Komponenten (base-Basis): Das CLI behandelt die Komponente als monolithisch – jede Aktualisierung der Stammkomponente kann alles ändern. Verwende --dry-run, um die Auswirkungen zu bewerten.

Vorausgesetzte Schritte:

1. Führe npx shadcn@latest add <component> --dry-run aus. Wenn gemeldet wird, dass alles auf dem neuesten Stand ist (alles aktuell), stoppe hier.
2. Wenn Aktualisierungen gefunden werden, führe npx shadcn@latest add <component> --diff aus.
3. Analysiere den Diff:
   • Keine lokalen Konflikte: npx shadcn@latest add <component>
   • Lokale Konflikte: Führe eine manuelle Überprüfung durch.
4. Nach der Übernahme führe erneut npx shadcn@latest add <component> --dry-run aus, um zu bestätigen, dass keine ausstehenden Änderungen vorhanden sind.

Entwickler-Workflow: Verwende für die tägliche Entwicklung lokale Branchs des Repositorys anstelle dieser CLI-Funktionen. Das CLI ist für die Benutzerwartung konzipiert, nicht für die Entwicklung.

Entfernen von Komponenten

Verwende npx shadcn@latest remove <component>. Dadurch werden die Dateien der Komponente entfernt. Abhängigkeiten von gemeinsam genutzten Dienstprogrammdateien (z. B. cn, hover-card-utils) werden nicht automatisch entfernt.

Fehlerbehebung mit npx shadcn@latest info

Wenn etwas nicht funktioniert, führe npx shadcn@latest info erneut aus, um zu überprüfen, ob die Konfiguration aktuell ist. Das injizierte JSON oben spiegelt möglicherweise nicht den aktuellen Zustand wider, nachdem der Benutzer manuelle Änderungen vorgenommen hat.

Häufige Probleme & Lösungen

Problem	Lösung
Der Befehl kann nicht ausgeführt werden: npx shadcn@latest	Der Benutzer muss shadcn installieren oder das CLI global verfügbar machen: npm install -g shadcn oder pnpm add -g shadcn. Dies ist ein Entwicklungssetup-Problem, das nicht im Rahmen der Fähigkeiten dieses Skills liegt.
"components.json" fehlt oder ist ungültig	Der Benutzer muss npx shadcn@latest init ausführen, um zu beginnen.
"Die Registry-Anfrage ist fehlgeschlagen"	Überprüfe die Internetverbindung und die Registry-URL. Versuche es später erneut.
Komponente kann nicht hinzugefügt werden (Konflikt)	Verwende --diff, um Änderungen zu überprüfen, und wende dann mit --yes an.
Kompilierungsfehler nach dem Hinzufügen einer Komponente	Überprüfe auf fehlende Abhängigkeiten (z. B. recharts für Diagramme, @radix-ui/react-select für Select). Installiere sie mit dem packageManager des Projekts.
Importpfade funktionieren nicht (Drittanbieter-Registry)	Korrigiere Importe, um die Aliase des Projekts zu verwenden (siehe Schritt 6 im Arbeitsablauf).
Symbolimporte funktionieren nicht (falsche Symbolbibliothek)	Ersetze Symbolimporte durch die iconLibrary des Projekts aus dem Projektkontext.
Base-Komponenten werden neu gerendert oder funktionieren nicht wie erwartet	Überprüfe, ob die installierte Version der base-Bibliothek mit den in der components.json angegebenen Versionen übereinstimmt.

Änderungsprotokoll

Siehe CHANGELOG.md für Versionshinweise und Historie.

---

WICHTIGE HAFTUNGSAUSSCHLUSS: Dieses Dokument enthält den vollständigen SKILL.md-Inhalt des Original-Skills. Einige der darin enthaltenen Regeln, Abläufe und Verweise sind für die Erstellung der deutschen Übersetzung gedacht und können von der tatsächlichen englischen Originalversion abweichen. Die Übersetzung dient als Hilfestellung; für die endgültige Referenz wird die englische Originalversion empfohlen.