Géruyang/agent-skills-library

Exportation des limites de copie et alias de compétence

La migration, l'installation, la correction et la réécriture de l'expérience ne s'appliquent qu'à la copie de la compétence hôte actuellement chargée. La compétence originale Codex/MCP, le code source téléchargé et les original-skills sont tous des matériaux source ; ils ne sont pas écrits par l'exécution de cette copie. Ce n'est que lorsque l'utilisateur demande explicitement de configurer le produit Codex lui-même que le processus de ce produit est suivi pour traiter la cible spécifiée. Lorsque le script a besoin d'un répertoire d'installation ou d'état, fournissez explicitement le chemin cible ; ne déduisez pas implicitement l'emplacement d'écriture de CODEX_HOME.

Les noms inter-compétences peuvent hériter des alias du dépôt source. Vérifiez d'abord le tableau des alias de compétence, sélectionnez de préférence l'entrée avec la même source et le même plugin, puis utilisez son id pour appeler ou lire l'entrée correspondante ; ne supposez pas que les anciens noms $skill, superpowers:skill sont directement enregistrés sur le nouvel hôte. Si vous ne pouvez pas déterminer la cible, vérifiez d'abord, ne remplacez pas les commandes de produits réelles ou les variables d'environnement du shell.

Convention d'utilisation multi-hôte

Ce exemplaire est destiné aux clients prenant en charge les compétences de l'agent. Vérifiez d'abord les outils, autorisations et services connectés réellement fournis par l'hôte actuel, puis exécutez le flux de travail du corps. Les identifiants d'outils hôtes dans le texte original sont des références de capacité ; ils ne peuvent être appelés que si l'outil est réellement trouvé. Les autres hôtes doivent utiliser les MCP, CLI ou API équivalents vérifiés. Les étapes sans capacité équivalente doivent signaler qu'elles ne sont pas disponibles, ne peuvent pas inventer d'appel ou d'état d'achèvement.

Les ressources de la compétence sont basées sur le répertoire de cette compétence ; la sortie est écrite à l'emplacement spécifié par l'utilisateur dans le projet en cours. Déclenché par le nom de la compétence ou le langage naturel, la commande de raccourci spécifique est déterminée par l'hôte. Les noms impliquant des produits réels, des API de modèles, des champs de protocole et des URL officielles restent dans leur sens d'origine. L'autorisation, l'approbation, la confidentialité et les limites de la portée des outils restent en vigueur après la migration ; les autorisations ne doivent pas être étendues pour la compatibilité. Voir PORTABILITY.md dans le même répertoire pour les dépendances spécifiques et les instructions de migration.

shadcn/ui

Un framework pour construire des UI, des composants et des systèmes de design. Les composants sont ajoutés en tant que code source au projet de l'utilisateur via la CLI.

IMPORTANT : Exécutez toutes les commandes CLI en utilisant le gestionnaire de paquets du projet : npx shadcn@latest, pnpm dlx shadcn@latest, ou bunx --bun shadcn@latest — en fonction du packageManager du projet. Les exemples ci-dessous utilisent npx shadcn@latest mais remplacez par le bon exécuteur pour le projet.

Contexte actuel du projet

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "Aucun projet shadcn trouvé. Exécutez shadcn init d'abord."}'`

Le JSON ci-dessus contient la configuration du projet et les composants installés. Utilisez npx shadcn@latest docs <composant> pour obtenir les URL de documentation et d'exemples pour n'importe quel composant.

Principes

1. Utilisez d'abord les composants existants. Utilisez npx shadcn@latest search pour vérifier les registres avant d'écrire une UI personnalisée. Vérifiez également les registres communautaires.
2. Composez, ne réinventez pas. Page de paramètres = Tabs + Card + contrôles de formulaire. Tableau de bord = Sidebar + Card + Chart + Table.
3. Utilisez les variantes intégrées avant les styles personnalisés. variant="outline", size="sm", etc.
4. Utilisez les couleurs sémantiques. bg-primary, text-muted-foreground — jamais de valeurs brutes comme bg-blue-500.

Règles critiques

Ces règles sont toujours appliquées. Chacune est liée à un fichier avec des paires de code Incorrect/Correct.

Style & Tailwind → styling.md

• className pour la mise en page, pas le style. Ne remplacez jamais les couleurs ou la typographie des composants.
• Pas de space-x-* ou space-y-*. Utilisez flex avec gap-*. Pour les piles verticales, flex flex-col gap-*.
• Utilisez size-* lorsque la largeur et la hauteur sont égales. size-10 pas w-10 h-10.
• Utilisez le raccourci truncate. Pas overflow-hidden text-ellipsis whitespace-nowrap.
• Pas de remplacements de couleur manuels dark:. Utilisez les tokens sémantiques (bg-background, text-muted-foreground).
• Utilisez cn() pour les classes conditionnelles. N'écrivez pas de ternaires manuels de template literal.
• Pas de z-index manuel sur les composants de superposition. Dialog, Sheet, Popover, etc. gèrent leur propre empilement.

Formulaires et entrées → forms.md

• Les formulaires utilisent FieldGroup + Field. N'utilisez jamais de div brut avec space-y-* ou grid gap-* pour la mise en page du formulaire.
• InputGroup utilise InputGroupInput/InputGroupTextarea. Jamais de Input/Textarea brut à l'intérieur de InputGroup.
• Les boutons à l'intérieur des entrées utilisent InputGroup + InputGroupAddon.
• Les ensembles d'options (2 à 7 choix) utilisent ToggleGroup. Ne faites pas de boucle Button avec un état actif manuel.
• FieldSet + FieldLegend pour regrouper les cases à cocher/boutons radio associés. N'utilisez pas de div avec un titre.
• La validation de champ utilise data-invalid + aria-invalid. data-invalid sur Field, aria-invalid sur le contrôle. Pour désactivé : data-disabled sur Field, disabled sur le contrôle.

Structure des composants → composition.md

• Les éléments sont toujours à l'intérieur de leur Groupe. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Utilisez asChild (radix) ou render (base) pour les déclencheurs personnalisés. Vérifiez le champ base de npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet et Drawer ont toujours besoin d'un Titre. DialogTitle, SheetTitle, DrawerTitle requis pour l'accessibilité. Utilisez className="sr-only" si visuellement caché.
• Utilisez la composition complète de Card. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Ne mettez pas tout dans CardContent.
• Button n'a pas de isPending/isLoading. Composez avec Spinner + data-icon + disabled.
• TabsTrigger doit être à l'intérieur de TabsList. Ne rendez jamais les déclencheurs directement dans Tabs.
• Avatar a toujours besoin de AvatarFallback. Pour quand l'image ne se charge pas.

Utilisez les composants, pas le balisage personnalisé → composition.md

• Utilisez les composants existants avant le balisage personnalisé. Vérifiez si un composant existe avant d'écrire un div stylisé.
• Les encadrés utilisent Alert. Ne construisez pas de divs stylisés personnalisés.
• Les états vides utilisent Empty. Ne construisez pas de balisage d'état vide personnalisé.
• Toast via sonner. Utilisez toast() de sonner.
• Utilisez Separator au lieu de <hr> ou <div className="border-t">.
• Utilisez Skeleton pour les espaces réservés de chargement. Pas de divs animate-pulse personnalisés.
• Utilisez Badge au lieu de spans stylisés personnalisés.

Icônes → icons.md

• Les icônes dans Button utilisent data-icon. data-icon="inline-start" ou data-icon="inline-end" sur l'icône.
• Pas de classes de dimensionnement sur les icônes à l'intérieur des composants. Les composants gèrent le dimensionnement des icônes via CSS. Pas de size-4 ou w-4 h-4.
• Passez les icônes en tant qu'objets, pas de clés de chaîne. icon={CheckIcon}, pas une recherche de chaîne.

CLI

• Ne décodez et ne récupérez jamais les codes de preset manuellement. Passez-les directement à npx shadcn@latest init --preset <code>.

Modèles clés

Voici les modèles les plus courants qui différencient le code shadcn/ui correct. Pour les cas limites, consultez les fichiers de règles liés ci-dessus.

// Mise en page du formulaire : FieldGroup + Field, pas div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validation : data-invalid sur Field, aria-invalid sur le contrôle.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Email invalide.</FieldDescription>
</Field>

// Icônes dans les boutons : data-icon, pas de classes de dimensionnement.
<Button>
  <SearchIcon data-icon="inline-start" />
  Rechercher
</Button>

// Espacement : gap-*, pas space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // faux

// Dimensions égales : size-*, pas w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // faux

// Couleurs d'état : variantes Badge ou tokens sémantiques, pas de couleurs brutes.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // faux

Sélection de composants

Besoin	Utilisez
Bouton/action	Button avec la variante appropriée
Entrées de formulaire	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Basculer entre 2 et 5 options	ToggleGroup + ToggleGroupItem
Affichage de données	Table, Card, Badge, Avatar
Navigation	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Superpositions	Dialog (modale), Sheet (panneau latéral), Drawer (feuille inférieure), AlertDialog (confirmation)
Retour d'information	sonner (toast), Alert, Progress, Skeleton, Spinner
Palette de commandes	Command à l'intérieur de Dialog
Graphiques	Chart (encapsule Recharts)
Mise en page	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
États vides	Empty
Menus	DropdownMenu, ContextMenu, Menubar
Infobulles/info	Tooltip, HoverCard, Popover

Champs clés

Le contexte de projet injecté contient ces champs clés :

• aliases → utilisez le préfixe d'alias réel pour les imports (par exemple @/, ~/), ne codez jamais en dur.
• isRSC → lorsque true, les composants utilisant useState, useEffect, les gestionnaires d'événements ou les API du navigateur ont besoin de "use client" en haut du fichier. Référencez toujours ce champ lorsque vous conseillez sur la directive.
• tailwindVersion → "v4" utilise les blocs @theme inline ; "v3" utilise tailwind.config.js.
• tailwindCssFile → le fichier CSS global où les variables CSS personnalisées sont définies. Modifiez toujours ce fichier, n'en créez jamais un nouveau.
• style → traitement visuel du composant (par exemple nova, vega).
• base → bibliothèque primitive (radix ou base). Affecte les API des composants et les props disponibles.
• iconLibrary → détermine les imports d'icônes. Utilisez lucide-react pour lucide, @tabler/icons-react pour tabler, etc. Ne supposez jamais lucide-react.
• resolvedPaths → destinations exactes du système de fichiers pour les composants, les utilitaires, les hooks, etc.
• framework → conventions de routage et de fichiers (par exemple Next.js App Router vs Vite SPA).
• packageManager → utilisez-le pour toutes les installations de dépendances non shadcn (par exemple pnpm add date-fns vs npm install date-fns).

Voir cli.md — commande info pour la référence complète des champs.

Documentation, exemples et utilisation des composants

Exécutez npx shadcn@latest docs <composant> pour obtenir les URL de la documentation, des exemples et de la référence API d'un composant. Récupérez ces URL pour obtenir le contenu réel.

npx shadcn@latest docs button dialog select

Lors de la création, de la correction, du débogage ou de l'utilisation d'un composant, exécutez toujours npx shadcn@latest docs et récupérez les URL en premier. Cela garantit que vous travaillez avec la bonne API et les bons modèles d'utilisation plutôt que de deviner.

Flux de travail

1. Obtenez le contexte du projet — déjà injecté ci-dessus. Exécutez à nouveau npx shadcn@latest info si vous avez besoin de l'actualiser.
2. Vérifiez d'abord les composants installés — avant d'exécuter add, vérifiez toujours la liste components du contexte du projet ou listez le répertoire resolvedPaths.ui. N'importez pas de composants qui n'ont pas été ajoutés et ne ré-ajoutez pas ceux déjà installés.
3. Trouvez des composants — npx shadcn@latest search.
4. Obtenez la documentation et les exemples — exécutez npx shadcn@latest docs <composant> pour obtenir les URL, puis récupérez-les. Utilisez npx shadcn@latest view pour parcourir les éléments du registre que vous n'avez pas installés. Pour prévisualiser les modifications apportées aux composants installés, utilisez npx shadcn@latest add --diff.
5. Installez ou mettez à jour — npx shadcn@latest add. Lors de la mise à jour de composants existants, utilisez --dry-run et --diff pour prévisualiser les modifications d'abord (voir Mise à jour des composants ci-dessous).
6. Corrigez les imports dans les composants tiers — Après avoir ajouté des composants à partir de registres communautaires (par exemple @bundui, @magicui), vérifiez les fichiers non-UI ajoutés pour les chemins d'import codés en dur comme @/components/ui/.... Ceux-ci ne correspondront pas aux alias réels du projet. Utilisez npx shadcn@latest info pour obtenir l'alias ui correct (par exemple @workspace/ui/components) et réécrivez les imports en conséquence. La CLI réécrit les imports pour ses propres fichiers UI, mais les composants de registre tiers peuvent utiliser des chemins par défaut qui ne correspondent pas au projet.
7. Examinez les composants ajoutés — Après avoir ajouté un composant ou un bloc à partir de n'importe quel registre, lisez toujours les fichiers ajoutés et vérifiez qu'ils sont corrects. Vérifiez les sous-composants manquants (par exemple SelectItem sans SelectGroup), les imports manquants, la composition incorrecte ou les violations des Règles critiques. Remplacez également tous les imports d'icônes par iconLibrary du projet à partir du contexte du projet (par exemple, si l'élément du registre utilise lucide-react mais que le projet utilise hugeicons, échangez les imports et les noms d'icônes en conséquence). Corrigez tous les problèmes avant de continuer.
8. Le registre doit être explicite — Lorsque l'utilisateur demande d'ajouter un bloc ou un composant, ne devinez pas le registre. Si aucun registre n'est spécifié (par exemple, l'utilisateur dit "ajouter un bloc de connexion" sans spécifier @shadcn, @tailark, etc.), demandez quel registre utiliser. Ne prenez jamais de décision par défaut concernant un registre au nom de l'utilisateur.
9. Changement de presets — Demandez d'abord à l'utilisateur : réinstaller, fusionner ou ignorer ?
   • Réinstaller : npx shadcn@latest init --preset <code> --force --reinstall. Écrase tous les composants.
   • Fusionner : npx shadcn@latest init --preset <code> --force --no-reinstall, puis exécutez npx shadcn@latest info pour lister les composants installés, puis pour chaque composant installé, utilisez --dry-run et --diff pour le fusionner intelligemment individuellement.
   • Ignorer : npx shadcn@latest init --preset <code> --force --no-reinstall. Met à jour uniquement la configuration et le CSS, laisse les composants tels quels.
   • Important : Exécutez toujours les commandes de preset dans le répertoire du projet de l'utilisateur. La CLI préserve automatiquement la base actuelle (base vs radix) de components.json. Si vous devez utiliser un répertoire temporaire (par exemple pour les comparaisons --dry-run), passez --base <base-actuelle> explicitement — les codes de preset n'encodent pas la base.

Mise à jour des composants

Lorsque l'utilisateur demande de mettre à jour un composant à partir de la source en amont tout en conservant ses modifications locales, utilisez --dry-run et --diff pour fusionner intelligemment. NE récupérez JAMAIS les fichiers bruts de la source ; utilisez toujours npx shadcn@latest add --diff --dry-run pour voir ce qui a changé en amont. Ensuite :

1. Pour chaque fichier du composant, différenciez le source amont de votre version locale.
2. Appliquez les modifications amont aux parties que vous n'avez pas modifiées.
3. Conservez vos modifications locales dans les zones que vous avez intentionnellement modifiées.
4. Si un conflit est ambigu (par exemple, le source et les modifications locales modifient la même ligne), demandez à l'utilisateur quoi faire.
5. Ne passez pas outre les modifications de l'utilisateur sauf si elles sont clairement incorrectes.

# Prévisualisez d'abord ce qui a changé
npx shadcn@latest add <composant> --diff --dry-run

Commandes CLI de référence

# Initialiser shadcn/ui (cherche --preset dans la demande)
npx shadcn@latest init

# Initialiser avec un preset
npx shadcn@latest init --preset <code>

# Ajouter des composants (peut être plusieurs)
npx shadcn@latest add button
npx shadcn@latest add button card dialog

# Ajouter des composants d'un registre communautaire
npx shadcn@latest add button --registry <nom-du-registre>

# Ajouter un bloc complet d'un registre
npx shadcn@latest add --block --registry <nom-du-registre> <nom-du-bloc>

# Rechercher des composants dans tous les registres
npx shadcn@latest search

# Obtenir les URL de documentation et d'exemples
npx shadcn@latest docs <composant>

# Afficher les informations du projet
npx shadcn@latest info

# Afficher un élément du registre avant l'installation
npx shadcn@latest view <composant>

# Mettre à jour un composant sans confirmer
npx shadcn@latest add <composant> --yes

# Aperçu des modifications sans installer
npx shadcn@latest add <composant> --dry-run

# Afficher un diff des modifications
npx shadcn@latest add <composant> --diff