Agent Skills : configurer .claude/skills et .agents/skills

Pour un dépôt utilisé avec Claude Code, Codex, Cursor et Gemini CLI, conservez les fichiers des skills partagées dans .agents/skills/<skill-name>/. Rendez chaque skill accessible à Claude Code avec un lien symbolique relatif vers son dossier, placé sous .claude/skills/. Vérifiez ensuite sa détection et son invocation dans chaque client avant d’adopter cette structure pour toute l’équipe.

Cette configuration permet de modifier une seule copie des instructions tout en respectant les règles de recherche propres à chaque client. Une équipe qui utilise uniquement Claude Code peut conserver sa structure actuelle dans .claude/skills/ ; déplacer les dossiers devient utile lorsqu’un autre client doit utiliser les mêmes skills.

L’AAIF a-t-elle normalisé le nom du dossier ?

L’AAIF héberge la norme, mais les clients continuent de choisir où rechercher les skills. Anthropic a annoncé le don le 22 octobre 2026, et la fondation a accueilli Agent Skills parmi les projets qu’elle héberge.

Le guide d’implémentation pour les clients précise que l’emplacement des dossiers de skills ne fait pas partie des exigences de la spécification. Il recommande d’envisager .agents/skills/ pour l’interopérabilité, en complément du dossier propre au client. Cette recommandation ne signifie pas que tous les clients existants parcourent déjà ce chemin.

L’unité portable est un dossier contenant un fichier SKILL.md doté d’un en-tête de métadonnées YAML, appelé frontmatter, puis d’instructions en Markdown. La spécification du format exige name et description ; des ressources facultatives peuvent les accompagner. La syntaxe d’invocation, les environnements d’exécution des scripts et les permissions dépendent toujours du client. En particulier, allowed-tools reste expérimental et sa prise en charge varie selon l’implémentation : ce champ ne constitue donc pas une politique de permissions commune à tous les clients.

Où les quatre outils recherchent-ils les skills ?

Utilisez les dossiers de recherche locaux documentés dans le tableau ci-dessous. Les chemins et les commandes de ce guide correspondent à la documentation officielle au 2026-10-26 ; ajoutez <skill-name>/SKILL.md à chaque chemin pour obtenir la structure utilisée ici.

Outil	Dossiers dans le dépôt	Dossiers utilisateur	Choix pour un dépôt partagé
Claude Code	`.claude/skills/`	`~/.claude/skills/`	Ajoutez un lien par skill depuis `.claude/skills/` vers le dossier partagé.
Codex CLI et extension pour IDE	`.agents/skills/`	`~/.agents/skills/`	Lisez directement le dossier partagé.
Cursor Agent	`.agents/skills/`, `.cursor/skills/` ; également `.claude/skills/` et `.codex/skills/` pour la compatibilité	Les mêmes quatre noms de dossier sous `~/`	Utilisez `.agents/skills/` ; aucun lien supplémentaire n’est nécessaire pour Cursor.
Gemini CLI	`.agents/skills/` et `.gemini/skills/`	`~/.agents/skills/` et `~/.gemini/skills/`	Lisez directement `.agents/skills/`. À portée égale, ce chemin est prioritaire sur `.gemini/skills/`.

Le guide actuel de Claude Code ne mentionne pas de détection native dans .agents/skills/, et la demande de fonctionnalité #31005 reste ouverte. À l’inverse, les guides de Codex et de Gemini cités ci-dessus ne mentionnent pas .claude/skills/ comme dossier de recherche. Utilisez les chemins documentés sans considérer ces deux dossiers comme interchangeables dans tous les clients.

Ces chemins concernent la détection locale. Une skill placée dans le dossier personnel de votre ordinateur portable n’est pas automatiquement disponible dans un worker distant ou un nouveau conteneur ; cet environnement doit lui aussi recevoir les fichiers.

Créez une skill partagée et un lien pour Claude Code

Placez la skill complète sous .agents/skills/ et créez un lien vers son dossier entier, afin d’inclure les éventuels scripts ou documents de référence ajoutés plus tard. Un lien par skill laisse aussi de la place aux skills existantes propres à Claude.

Vous devez disposer de Git et d’un client installé et authentifié, déjà capable de travailler dans votre dépôt. Cette configuration du système de fichiers ne nécessite aucun nouvel identifiant d’API ; les conditions habituelles d’accès au client et les permissions des outils restent applicables.

Rédigez une skill portable

Créez .agents/skills/review-staged/SKILL.md dans votre éditeur, ainsi que ses dossiers parents si nécessaire. Si cette skill existe déjà, choisissez un autre nom et modifiez-le de façon cohérente dans le dossier, le frontmatter et les commandes.

Collez le contenu complet suivant :

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

Cette procédure examine l’index Git, c’est-à-dire les modifications préparées pour le prochain commit. La documentation de git diff décrit --cached pour cette comparaison et --check pour les erreurs liées aux caractères d’espacement et les marqueurs de conflit. L’exemple demande à l’agent d’exécuter des commandes ordinaires, sans dépendre de mécanismes d’expansion du prompt propres à un client.

Ajoutez le lien avec Bash sous macOS ou Linux

Créez un lien symbolique relatif pour cette skill. Claude Code documente explicitement la prise en charge des dossiers de skills accessibles par lien symbolique.

Exécutez ce bloc dans Bash, depuis n’importe quel emplacement à l’intérieur du dépôt Git concerné :

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

La sortie attendue est ../../.agents/skills/review-staged, avec un code de sortie 0. Les deux composants .. sont relatifs au dossier qui contient le lien, .claude/skills/, et remontent jusqu’à la racine du dépôt.

Si une entrée existe déjà au chemin du lien, examinez-la avant toute modification. Conservez un lien existant s’il est correct ; s’il s’agit d’un véritable dossier de skill, comparez son contenu à la copie principale et décidez comment les réunir. Le bloc refuse de remplacer aussi bien un dossier qu’un lien dont la cible n’existe plus.

Créez le lien équivalent sous Windows

Utilisez PowerShell 7.1 ou une version ultérieure pour le lien relatif vers un dossier ci-dessous. La documentation Microsoft de New-Item précise cette exigence de version. Sous Windows, la création de liens symboliques nécessite généralement des privilèges élevés, ou une version compatible de Windows avec le mode développeur activé.

Une fois le fichier SKILL.md principal enregistré, exécutez ce bloc depuis la racine du dépôt :

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

La valeur de LinkType doit être SymbolicLink, et la vérification du fichier doit renvoyer True. Si la création échoue faute de privilèges, utilisez la procédure approuvée par votre organisation pour activer le mode développeur ou effectuer la configuration avec des droits élevés.

Ne supposez pas que Git Bash natif se comporte comme sous Linux : Git for Windows indique que ln -s crée des copies par défaut. Utilisez la procédure PowerShell et examinez le lien obtenu.

Un autre problème peut apparaître après le clonage. Avec core.symlinks=false, Git crée dans l’arborescence de travail un fichier ordinaire contenant le texte de la cible du lien symbolique. Diagnostiquez ce cas dans PowerShell :

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

Si le lien est devenu un fichier texte, examinez son contenu avant de remplacer précisément ce fichier par un véritable lien. Configurez la prise en charge des liens symboliques lors du checkout pour les prochains clones. Modifier uniquement le paramètre Git ne transforme pas un fichier texte déjà présent dans l’arborescence de travail en lien vers un dossier.

Vérifiez la détection, l’activation et le résultat

Consultez d’abord le catalogue du client, puis invoquez explicitement la skill. La présence d’un fichier sur le disque ne prouve pas que le client l’a détecté, et une entrée dans le catalogue ne prouve pas que ses instructions ont été chargées.

Ouvrez ou lancez chaque client à la racine du dépôt. Utilisez les commandes et contrôles suivants dans le client, et non dans une invite Bash ou PowerShell :

Client	Confirmer la détection	Invoquer l’exemple
Claude Code	Exécutez `/skills` ; utilisez `/reload-skills` si nécessaire, comme l’indique la référence des commandes.	Envoyez `/review-staged`.
Codex CLI ou extension pour IDE	Ouvrez `/skills` ou le sélecteur de skills `$`.	Envoyez `$review-staged Review my staged changes.`
Cursor Agent	Ouvrez Customize → Skills, puis recherchez la skill dans le sélecteur `/`.	Sélectionnez `review-staged` et demandez une revue des modifications préparées pour le commit.
Gemini CLI	Exécutez `/skills list` ; utilisez `/skills reload` après avoir ajouté des fichiers.	Demandez : `Use the review-staged skill to review my staged changes.`

Le processus d’activation documenté de Gemini utilise activate_skill et une demande de consentement interactive. Autorisez le dossier de la skill voulue lorsque cette demande apparaît. Le guide de gestion décrit les commandes de liste et de rechargement.

La réponse attendue commence par Skill loaded: review-staged, puis présente les problèmes relevés et les vérifications suggérées, ou No staged changes. si l’index est vide. Examinez aussi la trace d’activation ou de lecture du fichier et les commandes Git, en plus de ce marqueur. Cela permet de vérifier que les instructions ont été chargées ; cela ne garantit pas que chaque observation de la revue est correcte.

Cursor lit les deux chemins de cette structure. Ses notes de version IDE 3.25, datées du 14 octobre 2026, indiquent que des skills portant le même nom peuvent apparaître sur des lignes distinctes du menu. Vérifiez les doublons dans votre version installée ; ne supposez pas que tous les clients dédupliquent les liens de la même manière.

Adoptez une structure prévisible pour les monorepos et la CI

Conservez les skills partagées à la racine du dépôt et lancez chaque client depuis cette racine lors de la première configuration. Pour une procédure propre à un package, nommez ce package dans la description et les instructions de la skill, sans dépendre de règles de recherche identiques dans les dossiers imbriqués. L’exemple précédent examine volontairement l’ensemble de l’index Git.

Une structure pratique attribue un rôle précis à chaque emplacement :

Emplacement	Rôle
`.agents/skills/review-staged/SKILL.md`	Copie des instructions partagées à maintenir.
`.agents/skills/review-staged/references/`	Documents d’accompagnement facultatifs distribués avec la skill.
`.claude/skills/review-staged`	Lien relatif vers le dossier complet de la skill partagée.
`packages/mobile/`	Code de l’application mentionnée dans la tâche demandée.

Les règles de portée diffèrent. Claude Code et Codex recherchent leurs dossiers de skills respectifs en remontant depuis le dossier de départ jusqu’à la racine du dépôt. Cursor documente aussi des skills dans les sous-dossiers du projet, dont la portée couvre les fichiers sous le dossier qui les contient. Le guide de gestion de Gemini décrit les skills de l’espace de travail par rapport au dossier courant. Démarrer les quatre clients à la racine évite de dépendre de ces différences.

Placez chaque skill partagée dans un sous-dossier directement sous le dossier racine des skills. Le guide de démarrage de Gemini limite la recherche à cette profondeur ; la recherche récursive de Cursor ne rend pas portable un niveau supplémentaire de dossiers de catégories.

Si l’espace de travail ne contient qu’un seul package, répétez la vérification de détection dans cet espace et installez-y la skill partagée ou ajoutez un lien si nécessaire. Ne réutilisez pas la cible ../../ du lien situé à la racine dans un emplacement plus profond sans la recalculer.

Incluez la copie principale et le lien symbolique relatif dans un commit si les environnements de checkout de votre équipe le permettent. Gardez la cible à l’intérieur du dépôt afin qu’un nouveau clone puisse la résoudre sans accéder au dossier personnel d’un développeur.

Après un checkout dans une CI sous Linux, cette vérification Bash contrôle les fichiers et le lien nécessaires :

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

Un code de sortie 0 signifie que ces vérifications du système de fichiers ont réussi. La détection et l’invocation dans le client nécessitent encore les contrôles décrits plus haut, dans l’environnement d’exécution réel.

Si la skill ne se charge toujours pas, identifiez l’étape qui échoue

Corrigez le problème à l’étape concernée plutôt que de modifier le prompt à répétition. Les cas suivants sont des branches de diagnostic distinctes, pas une suite de réglages que chacun doit changer.

La skill est absente du catalogue : vérifiez la racine de l’espace de travail, l’orthographe des dossiers et le nom exact SKILL.md. Lisez le fichier par le chemin que le client examine. Si le chemin principal fonctionne mais pas celui de Claude, réparez le lien ou le checkout.
Le fichier est trouvé, mais ses métadonnées sont refusées : vérifiez les délimiteurs YAML, une description non vide de 1024 caractères au maximum et un nom de dossier correspondant à name, composé de 1–64 lettres minuscules, chiffres ou traits d’union. Évitez les traits d’union au début, à la fin ou consécutifs.
Le nouveau fichier n’apparaît pas encore : rechargez les skills de Claude ou de Gemini avec les commandes ci-dessus. Codex documente la détection automatique et propose le redémarrage si elle ne suffit pas ; rouvrez Cursor lorsqu’il faut relancer la détection effectuée au démarrage.
Une skill de l’espace de travail manque dans Gemini : vérifiez la confiance accordée au dossier avec /permissions trust. La référence de configuration actuelle indique skills.enabled à true par défaut, mais une politique d’administration peut interdire les skills. Utilisez les contrôles appropriés pour corriger un réglage désactivé ou une décision de confiance.
La mauvaise skill est exécutée : examinez les copies personnelles et celles du projet portant le même nom. Claude donne la priorité aux skills personnelles sur celles du projet ; Codex peut afficher les deux ; Gemini donne la priorité aux skills de l’espace de travail sur celles de l’utilisateur. Choisissez des noms distincts pour des procédures réellement différentes.
La skill figure dans la liste, mais n’est pas sélectionnée automatiquement : invoquez-la d’abord explicitement. Si cela fonctionne, améliorez la description pour nommer la tâche qu’elle prend en charge. Une description plus claire facilite la sélection ; déplacer un fichier déjà correctement détecté n’y aide pas.
La skill est chargée, mais les commandes échouent : vérifiez la disponibilité de Git, le dossier de travail et l’erreur de permission signalée. La portabilité des dossiers n’installe pas d’environnement d’exécution et n’accorde pas le droit d’exécuter des commandes.