stealth-engine/skills

agents-md-setup

Faire de AGENTS.md la source de vérité unique pour les instructions de l'agent/projet, et pointer chaque outil vers ce fichier via un lien symbolique (symlink). Un seul fichier, lu par tous les agents — pas de duplication, pas de dérive.

Pourquoi cette disposition

• AGENTS.md est la norme inter-outils émergente (Cursor, Codex et d'autres le lisent).
• Claude Code lit CLAUDE.md. Vous ne pouvez pas forcer le harnais à lire AGENTS.md via un prompt ou une compétence — mais un lien symbolique CLAUDE.md → AGENTS.md fait que Claude ouvre CLAUDE.md et obtient le contenu de AGENTS.md. C'est le mécanisme ; rien d'autre n'est nécessaire.
• Résultat : éditez AGENTS.md uniquement ; chaque agent reste synchronisé.

Décision : que trouve-t-on déjà ?

1. Aucun des deux fichiers → créez AGENTS.md à partir du modèle ci-dessous.
2. Uniquement CLAUDE.md (un vrai fichier) → faites-en la source de vérité :

   git mv CLAUDE.md AGENTS.md       # préserver l'historique (ou : mv si non suivi)
   

3. Uniquement AGENTS.md → conservez-le tel quel (bon).
4. Les deux existent en tant que vrais fichiers → ne les écrasez pas aveuglément. Comparez-les ; fusionnez dans AGENTS.md (il gagne comme fichier canonique), confirmez avec l'utilisateur si les contenus diffèrent, puis supprimez le CLAUDE.md autonome.
5. CLAUDE.md est déjà un lien symbolique vers AGENTS.md → déjà fait ; arrêtez.

Créer le lien symbolique

ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md        # git le stocke comme un vrai lien symbolique (mode 120000)

Vérifiez qu'il a bien été commité comme lien symbolique, pas comme copie :

git ls-files -s CLAUDE.md          # le mode doit être 120000

Optionnellement, pointez d'autres outils vers le même fichier :

ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md

Monorepos (Turborepo / workspaces)

Conservez un AGENTS.md racine pour les conventions à l'échelle du dépôt (avec le lien symbolique CLAUDE.md comme ci-dessus), puis ajoutez un AGENTS.md spécifique dans chaque workspace qui a besoin de ses propres règles — apps/<app>/AGENTS.md, packages/<pkg>/AGENTS.md — chacun avec son propre lien symbolique frère créé depuis ce répertoire pour que la cible soit relative :

cd apps/web && ln -s AGENTS.md CLAUDE.md   # CLAUDE.md -> ./AGENTS.md (même dossier)

• Claude Code lit le CLAUDE.md le plus proche pour les fichiers sur lesquels il travaille, donc les fichiers imbriqués complètent la racine plutôt que de la remplacer. Placez les éléments à l'échelle du dépôt à la racine ; mettez uniquement le delta spécifique au package dans chaque workspace — ne dupliquez pas la racine.
• Faites toujours en sorte que chaque lien symbolique soit relatif à son propre dossier (ln -s AGENTS.md CLAUDE.md en étant cd dans le workspace), ne pointez jamais vers la racine — les liens relatifs dans le même dossier survivent aux extractions/déplacements.
• Turborepo lui-même ne lit pas ces fichiers (ils sont destinés aux agents), donc aucune modification de turbo.json n'est nécessaire. Si vous voulez les rendre visibles, vous pouvez toujours mentionner la convention dans AGENTS.md racine.

README

S'il n'y a pas de README.md, créez-en un minimal (nom du projet, description en une ligne, commandes de configuration/lancement). Conservez la documentation destinée aux humains dans README.md et les instructions pour les agents dans AGENTS.md — ne fusionnez pas les deux.

Avertissement Windows / CI (important)

Les liens symboliques Git nécessitent core.symlinks=true et peuvent casser sur les extractions Windows ou certains exécuteurs CI (le lien symbolique atterrit comme un fichier texte contenant AGENTS.md). Si le projet cible Windows, préférez la solution de repli : un minuscule CLAUDE.md réel dont tout le contenu est un pointeur —

Voir [AGENTS.md](./AGENTS.md) pour les instructions du projet et de l'agent.

— en acceptant qu'il doive être maintenu manuellement (ou via une vérification). Le lien symbolique est meilleur partout où les liens symboliques sont fiables.

Ne l'annulez pas plus tard

Si vous voyez CLAUDE.md comme un lien symbolique vers AGENTS.md, c'est intentionnel — éditez AGENTS.md, ne remplacez jamais le lien symbolique par une copie.

Modèle AGENTS.md

# AGENTS.md

Instructions pour les agents AI et les humains travaillant dans ce dépôt.
`CLAUDE.md` est un lien symbolique vers ce fichier ; ce fichier est la source de vérité.

## Aperçu du projet
<ce que c'est, en 1 à 3 phrases>

## Commandes
- install : `…`
- dev : `…`
- build : `…`
- test / lint / format : `…`

## Conventions
- <style de code, langage/runtime, formatage>
- Messages de commit : <par ex. Conventional Commits>
- <tout ce qu'un agent ne doit pas faire, ou doit toujours faire>

## Structure
<répertoires clés et ce qui se trouve où>