AGENTS.md — Développer ce dépôt de Skills

Ce fichier s'adresse à tout agent IA (et à tout humain) qui modifie ce dépôt. Il décrit la structure, les commandes, les conventions et les pièges. Lisez-le avant d'écrire quoi que ce soit.

Pour utiliser les Skills (et non les développer), voir README.md et le dossier docs/ de chaque Skill.

Documents d'appui dans .agents/ :

1. Ce qu'est ce dépôt

Une bibliothèque de Skills pour agents IA : des dossiers autonomes contenant un SKILL.md (frontmatter YAML + instructions) et, si utile, des scripts/ déterministes, des references/, des assets/ et un docs/ en français.

Principe directeur — le chargement progressif. L'agent ne garde en contexte que name + description (~30 tokens). Il charge le corps du SKILL.md seulement si la tâche correspond, et n'ouvre references/ ou n'exécute scripts/ qu'en cas de besoin. Chaque décision d'écriture découle de ça : tout token doit gagner sa place.

2. Structure

Skills/
├── AGENTS.md                  # ce fichier
├── README.md                  # vitrine et catalogue
├── CONTRIBUTING.md            # procédure de contribution
├── catalogue.json             # index généré — NE PAS ÉDITER À LA MAIN
├── .agents/                   # documentation de développement
├── bundles/<role>.json        # regroupements de Skills par métier
├── docs/                      # documentation transverse du dépôt
├── skills/<nom>/              # un Skill = un dossier
│   ├── SKILL.md               # frontmatter + instructions (obligatoire)
│   ├── docs/README.md         # guide FR agent + utilisateur (obligatoire)
│   ├── scripts/               # Python 3.9+, stdlib uniquement
│   ├── references/            # profondeur, chargée à la demande
│   └── assets/                # gabarits, exemples, données
├── templates/SKILL.template.md
└── tools/                     # outillage du dépôt
    ├── skilllib.py            # bibliothèque partagée (parsing, découverte)
    ├── validate_skills.py     # validateur (--strict en CI)
    ├── build_catalogue.py     # génère catalogue.json
    ├── skills_cli.py          # CLI : list/search/show/bundles/install
    └── new_skill.py           # génère le squelette d'un nouveau Skill

3. Commandes essentielles

# Créer un nouveau Skill (squelette complet : SKILL.md, docs/, scripts/)
python3 tools/new_skill.py mon-skill --title "Mon Skill" --tags data,quality

# Valider — DOIT passer avant toute PR
python3 tools/validate_skills.py --strict

# Régénérer l'index après toute modification de frontmatter, script ou docs
python3 tools/build_catalogue.py

# Explorer la bibliothèque
python3 tools/skills_cli.py list
python3 tools/skills_cli.py search "requête lente"
python3 tools/skills_cli.py show sql-query-optimizer

# Installer chez un agent
python3 tools/skills_cli.py install --bundle backend-engineer --dry-run

Boucle de travail standard : modifier → validate_skills.py --strict → build_catalogue.py → commit.

4. Règles non négociables

Ces règles sont vérifiées par la CI ; une PR qui les viole est rejetée.

4.1 Structure d'un Skill

1. skills/<kebab-case>/SKILL.md — le champ name du frontmatter doit être identique au nom du dossier.
2. Frontmatter obligatoire : name, description, version (semver), license, tags (liste non vide).
3. description — 3ᵉ personne, en anglais, ≤ 1024 caractères, disant ce que fait le Skill et quand l'utiliser (Use when …). C'est le seul texte que l'agent voit avant de charger le Skill : c'est le champ le plus important du dépôt.
4. Corps du SKILL.md sous 500 lignes. La profondeur va dans references/.
5. Un dossier docs/README.md en français par Skill.

4.2 Contenu

6. Impératif à la 2ᵉ personne, agnostique du modèle et du fournisseur.
7. Tables de décision plutôt que de la prose.
8. Seuils concrets : « signaler les colonnes > 30 % de valeurs nulles », pas « vérifier les valeurs nulles ».
9. Sections attendues : quand utiliser / ne pas utiliser, workflow numéroté, exemple travaillé (entrée → sortie), checklist de qualité, modes d'échec.
10. Mots proscrits : simply, obviously, just use, as we all know. Ils minimisent la difficulté et n'apportent aucune information. (Dérogation possible via lint-ignore: [banned-words] quand le Skill cite ces mots.)

4.3 Scripts

11. Python 3.9+, bibliothèque standard uniquement. Aucune dépendance à installer, aucun accès réseau, aucun état persistant.
12. CLI argparse avec --help fonctionnel et --format obligatoire. md est toujours proposé et sert de valeur par défaut ; ajoutez text pour une sortie de terminal condensée et json dès que la sortie peut alimenter un autre outil ou une porte CI. La CI vérifie la présence de --format et de md sur les 17 scripts.
13. Ne jamais modifier un fichier d'entrée : écrire vers une nouvelle sortie.
14. Code de sortie ≠ 0 en cas de trouvaille bloquante, pour servir de porte CI.
15. La sortie doit dire explicitement que les résultats sont des pistes à confirmer, jamais des verdicts.

4.4 Sécurité et données

16. Aucun secret, aucune donnée personnelle, aucun contenu propriétaire scrapé.
17. Un script qui manipule des secrets masque ses sorties (préfixe/suffixe).
18. Un Skill à portée juridique, médicale ou financière doit porter un avertissement explicite : ce n'est pas un avis professionnel.

5. Ajouter un Skill — la version courte

python3 tools/new_skill.py mon-skill --title "Mon Skill" --tags data,quality
# éditer skills/mon-skill/SKILL.md puis skills/mon-skill/docs/README.md
python3 tools/validate_skills.py --strict
python3 tools/build_catalogue.py

Puis mettre à jour le tableau du README.md et ouvrir la PR.

La procédure détaillée, avec les décisions de conception, est dans .agents/workflows.md.

Avant de créer un Skill, vérifiez qu'il n'existe pas déjà :

python3 tools/skills_cli.py search "ce que fait mon skill"

Si un Skill proche existe, étendez-le plutôt que d'en créer un concurrent : deux Skills aux descriptions voisines dégradent la sélection de l'agent.

6. Le test décisif

Avant de proposer un Skill, répondez honnêtement :

Ce Skill rend-il un agent compétent mesurablement meilleur sur une tâche réelle ?

Si le contenu se résume à ce qu'un bon modèle sait déjà, ce n'est pas un Skill. Un Skill apporte au moins l'un de ces éléments :

• un processus que le modèle ne suit pas spontanément (ordre, vérifications) ;
• des seuils et tables de décision spécifiques à un domaine ;
• un script déterministe qui remplace du raisonnement coûteux et faillible ;
• des garde-fous qui évitent une erreur grave (destruction de données, avis juridique hasardeux, fuite de secret).

7. Pièges connus

8. Ce que la CI vérifie

Le workflow .github/workflows/validate.yml exécute, sur chaque PR :

1. validate_skills.py --strict — frontmatter, style, liens relatifs, présence des docs/.
2. build_catalogue.py --check — l'index est à jour.
3. Compilation de tous les scripts Python.
4. --help sur chaque script (l'interface CLI existe et ne plante pas).
5. Validation de tous les JSON (assets/, bundles/, catalogue.json).
6. Tests fonctionnels de fumée sur les scripts principaux.

Reproduire l'ensemble en local :

python3 tools/validate_skills.py --strict && \
python3 tools/build_catalogue.py --check && \
python3 -m py_compile $(find skills tools -name '*.py')

9. Langue

10. Commits et PR

Format conventionnel, vérifiable avec l'outillage du dépôt :

python3 skills/git-workflow-assistant/scripts/commit_helper.py --lint "feat(skills): add docker-compose-reviewer"

Une PR décrit la tâche que le Skill améliore et, si possible, un avant/après.