Cohérence : README.md par skill vs linter agentskills.io (WARN)

[kaaloo]

Constat

Chaque skill officielle du dépôt contient un README.md à côté de SKILL.md :

skills/react-dsfr/README.md
skills/rgaa/README.md
skills/lasuite-ui-kit/README.md
skills/securite-anssi/README.md
skills/datagouv-apis/README.md

Cette pratique a été introduite par la PR #11 (« docs : ajouter un README par skill », mergée le 2026-04-09) et figure aussi dans skills/.experimental/README.md.

Tension avec la spécification agentskills.io

Le linter de référence dérivé de agentskills.io (implémentation vercel-labs / skill-linter) émet un WARN explicite lorsqu'un README.md est présent dans le dossier d'une skill :

README.md found inside skill folder - all docs should go in SKILL.md or references/

Reproduit localement avec la skill validate-skill.sh :

[PASS] SKILL.md exists
...
[WARN] README.md found inside skill folder - all docs should go in SKILL.md or references/
[PASS] Line count: 8/500
...
Result: 12 passed, 0 failed, 2 warnings
PASSED WITH WARNINGS

La spec agentskills.io elle-même ne liste que SKILL.md (requis) et les dossiers optionnels scripts/, references/, assets/ — pas de README.md. Le CLAUDE.md du dépôt reflète d'ailleurs cette structure :

skill-name/
├── SKILL.md
└── references/

Il y a donc une incohérence entre la structure documentée dans CLAUDE.md (pas de README.md), la pratique effective du dépôt (5 README.md mergés via #11), et la spec de référence (qui ne prévoit pas ce fichier).

Questions

1. La présence d'un README.md par skill est-elle désormais la politique officielle du dépôt ? Si oui, il faudrait :

   • mettre à jour la section Architecture de CLAUDE.md pour documenter explicitement ce fichier,
   • décider du rôle de ce README.md par rapport à SKILL.md (redondance ? cible : humains vs LLM ?),
   • évaluer l'impact sur les outils de validation consommateurs (Vercel Skills CLI, skill-linter, etc.).

2. Ou bien ces README.md sont-ils un héritage de la PR docs: ajouter un README par skill #11 à reconsidérer, en fusionnant leur contenu dans SKILL.md (ou references/) pour rester 100% conforme à la spec ?

3. Faut-il ajouter un workflow CI qui exécute le linter agentskills.io sur les skills de ce dépôt (à l'image du sync-datagouv.yml), pour détecter automatiquement ce type de divergence à l'avenir ?

Contexte

Le skill-linter de référence est disponible publiquement et configurable en pre-commit ou en GitHub Action. Une intégration minimale pourrait s'inspirer de l'exemple suivant :

- name: Lint skills
  run: |
    for skill in skills/*/; do
      [ -d "$skill" ] || continue
      skills-ref validate "$skill"
    done

Reproduction

# Avec un skill-linter conforme agentskills.io
./validate-skill.sh skills/react-dsfr
# → WARN: README.md found inside skill folder