Le Gap de Connaissance
Les modèles IA sont entraînés sur des données avec une date de coupure. Ils ne connaissent pas :
- Les conventions et l'architecture spécifiques de votre projet
- Les versions récentes des frameworks et les changements d'API
- Les critères de qualité et les patterns de votre équipe
- L'état actuel de votre codebase
Sans injection explicite de connaissance, les agents devinent. Ils produisent du code qui semble correct mais qui viole subtilement vos conventions, utilise des API dépréciées, ou ignore vos décisions architecturales. Les skills éliminent les devinettes.
Anatomie d'un Skill
Un skill est un document structuré — pas de la prose, pas un prompt de chat. Il comporte quatre sections qui définissent ce qu'un agent doit savoir et faire.
Les skills ne sont pas de la documentation. Ce sont des contrats de connaissance exécutables — concis, directifs, et conçus pour être consommés par des machines.
Trois Types de Skills
Les skills sont organisés par portée et longévité :
Skills de Transition
Chaque transition entre agents est médiatisée par un skill qui définit la connaissance nécessaire à l'agent et la qualité attendue de sa sortie.
Skill de Spécification
Agent Architect — Besoin → Intention Document + Contrat
Guide l'Architect dans la production d'Intention Documents structurés avec des requirements vérifiables. Définit les champs obligatoires, s'assure que les critères de validation sont automatisables, et empêche les requirements vagues ou non testables.
Skill de Développement
Agent Maker — Contrat → Code
Définit la stack technique, les conventions de code, les patterns obligatoires et les anti-patterns interdits. S'assure que le Maker produit du code conforme aux standards de votre projet — pas des "best practices" génériques issues des données d'entraînement.
Skill d'Audit
Agent Breaker — Code → Rapport d'Audit
Liste les critères de validation, les vérifications de sécurité et les portes qualité que le Breaker doit vérifier. Définit le format du rapport d'audit avec des sections obligatoires : statut, findings, localisations, et recommandations actionnables.
Skill de Rétro-Spécification
Agent Witness — Code → Rétro-Spécification
Guide le Witness dans l'analyse objective du code. Définit ce qu'il faut inventorier (fonctionnalités, dépendances, écarts, dette), impose l'observation factuelle plutôt que l'interprétation, et structure la sortie pour que le prochain Architect puisse la consommer.
Skill de Correction
Agent Maker — Rapport d'Audit → Code corrigé
Encadre la façon dont le Maker traite les findings d'audit. Exige une analyse des causes profondes (pas juste la correction du symptôme), des tests de régression obligatoires pour chaque correction, et une traçabilité du finding au commit.
Skills de Domaine
L'innovation v2 : au lieu d'agents Maker/Breaker généralistes, le Conductor invoque des paires spécialisées par domaine. Chaque domaine a un skill Maker et un skill Breaker dédiés.
| Domaine | Skill Maker | Skill Breaker |
|---|---|---|
| Base de données | Normalisation, RLS, journalisation, indexation, patterns temporels | Normalisation manquante, RLS, index, contraintes, cascade |
| API | Conventions REST, validation Zod, pagination, rate limiting | Validation manquante, auth, CORS, requêtes N+1 |
| Frontend | Architecture composants, gestion d'état, accessibilité | Performance, taille du bundle, accessibilité, XSS |
| Sécurité | OIDC/JWKS, RBAC, AES-256-GCM, mTLS, headers | OWASP Top 10, escalade de privilèges, secrets |
| Infrastructure | Docker multi-stage, Compose, Terraform, secrets | Exécution en root, healthchecks, secrets en dur, SPOF |
Écrire vos propres Skills
Les skills fournis sont des templates. Vos vrais skills viennent des points de friction de votre projet :
- Identifiez les frictions — Où l'agent se trompe régulièrement ? Que corrigez-vous sans cesse ?
- Documentez le gap — Quelle connaissance manque à l'agent ? Écrivez-la comme des faits, pas de la prose.
- Structurez en règles — Convertissez la connaissance en directives impératives. "DOIT utiliser", "NE JAMAIS faire", "TOUJOURS vérifier".
- Testez et itérez — Lancez un cycle avec le skill. Si l'agent fait encore des erreurs, le skill est incomplet. Affinez.
Cycle de vie des Skills
Les skills sont des artefacts vivants — ils évoluent avec votre projet.
Versionnez vos skills avec votre code. Ils appartiennent au repository, pas à un wiki ou un drive partagé. Quand la stack technique change, les skills changent. Quand les conventions évoluent, les skills évoluent.
Structure de répertoire
skills/
public/ # Framework docs, language best practices
project/ # Your conventions, architecture decisions
delta/ # Temporary patches (new versions, hotfixes)Les MADD Boilerplates implémentent cette structure avec des templates de skills prêts à l'emploi pour chaque domaine et transition.