Skills Codex : emplacement, fonctionnement de l'invocation via $ et guide de rédaction

Un skill est un répertoire. Le seul fichier obligatoire est SKILL.md : un frontmatter YAML avec un name et une description, suivi d'instructions en Markdown. Autour, trois dossiers optionnels apportent un support sur lequel les instructions peuvent s'appuyer : scripts/ pour le code exécutable que le skill demande à Codex de lancer, references/ pour la documentation trop longue pour être intégrée, et assets/ pour les templates. Un fichier agents/openai.yaml optionnel ajoute des métadonnées d'interface et des dépendances pour la distribution.

---
name: apply-design-system
description: Apply the project design system when building or editing UI. Use for any component, page, or styling task; reads DESIGN.md and forbids colors, fonts, or spacing outside its tokens.
---

# Apply the design system

1. Read DESIGN.md at the repo root before writing any UI code.
2. Use only its semantic tokens for color, its type scale for text,
   and its spacing scale for layout.
3. If a needed value has no token, stop and say so instead of
   inventing one.

• .agents/skills/ dans le dépôt : skills de projet, partagés avec tous ceux qui le clonent.
• ~/.agents/skills/ : vos skills personnels, présents dans chaque projet.
• /etc/codex/skills : skills gérés par l'administrateur sur les machines partagées.
• Bundles système livrés avec le produit.
• Skills installés : $skill-installer récupère des skills sélectionnés ; les plugins permettent une distribution plus large.

L'emplacement dans le repo est celui qui modifie le comportement de l'équipe. Un skill dans .agents/skills/ suit le code source : chaque collaborateur, chaque exécution CI, chaque nouveau clone bénéficie des mêmes procédures sans configuration. Les contrats de projet, la manière dont l'UI est stylisée ou le processus de release ont leur place ici, plutôt que dans le répertoire personnel d'un individu.

L'invocation explicite est le cas le plus simple : tapez $ dans la CLI Codex et sélectionnez le skill ; il se charge quelle que soit sa description. Le cas intéressant est l'implicite : Codex garde le nom et la description de chaque skill à disposition, et charge le corps complet lorsqu'il juge que votre requête correspond. Ce jugement dépend entièrement de la description, qui devient alors la véritable interface. « Utiliser pour toute tâche de composant, de page ou de stylisation » donne au moteur de correspondance des verbes et des situations ; « assistant design » ne lui donne rien.

Codex lit AGENTS.md à chaque exécution : ce sont les ordres permanents du projet, les commandes de build, les conventions, les contraintes, et chaque ligne est comptabilisée à chaque requête. Les skills proposent le contrat inverse : coût quasi nul au repos, procédures complètes quand elles sont pertinentes. La répartition efficace consiste à mettre des règles courtes dans AGENTS.md, des procédures longues dans les skills, et des artéfacts durables (fichiers de tokens, DESIGN.md, schémas) dans le repo vers lesquels les deux peuvent pointer. La taxonomie complète des fichiers, incluant la place de CLAUDE.md et DESIGN.md, se trouve dans CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md.

L'exemple de skill ci-dessus ne contient que neuf lignes d'instructions, et c'est là sa force. Tout ce qu'il impose réside dans un seul artéfact : un fichier DESIGN.md à la racine du repo contenant le système réel, les design tokens de couleur sémantiques (clair et sombre), l'échelle typographique, l'espacement, les motifs et les règles d'interdiction. Codex est un excellent exécutant mais n'a aucune mémoire visuelle entre les sessions ; le fichier est sa mémoire. Les skills remplis d'adjectifs (« propre, moderne, cohérent ») sont inutiles, car il n'y a aucun point de référence pour vérifier le travail. Un skill pointant vers un fichier avec des valeurs exactes transforme chaque décision de style en une simple recherche.

npx --yes identityforge@latest apply ambient-sage

The SKILL.md convention grew into an open agent-skills standard: Claude Code discovers the same shape under .claude/skills/, and Cursor's Agent Skills load the same way next to its Rules. Discovery paths and invocation syntax differ per tool; the anatomy and the description-driven trigger do not. Write skills that reference artifacts in your repository rather than one tool's internals and they transfer almost verbatim; the Claude Code side of the same story is in Claude Code skills, explained.