Jude Gao de Vercel présente les résultats d'une évaluation comparative entre deux approches pour transmettre aux agents IA les connaissances spécifiques aux frameworks : les skills (récupération active) et AGENTS.md (contexte passif). Le constat est sans appel : la méthode la plus simple surpasse largement la plus sophistiquée.

Le problème : Next.js 16 introduit de nouvelles APIs (use cache, connection(), forbidden()) absentes des données d'entraînement des modèles IA. Sans documentation actualisée, les agents génèrent du code incorrect dans 47% des cas.

Skills : échec de la récupération active : Les skills, standard ouvert pour packager les connaissances invocables à la demande, se révèlent fragiles. Dans 56% des cas d'évaluation, l'agent n'a jamais invoqué la skill disponible, produisant un taux de réussite identique à la baseline (53%). Même en ajoutant des instructions explicites forçant le déclenchement (95%+ d'invocation), le taux ne monte qu'à 79%, et les résultats varient dramatiquement selon la formulation exacte des instructions.

AGENTS.md : victoire du contexte passif : Un fichier markdown statique injecté dans le prompt système à chaque tour atteint 100% de réussite (build, lint et tests). Cette approche élimine trois sources de fragilité : le point de décision (l'agent n'a pas à choisir d'invoquer), les problèmes de disponibilité (l'information est toujours présente) et les enjeux d'ordonnancement (pas de séquençage d'actions nécessaire).

Compression agressive : L'équipe Vercel a réussi à compresser 40 Ko de documentation en un index de 8 Ko (réduction de 80%) utilisant un format délimité par des pipes, tout en maintenant le taux de réussite à 100%. Cette compression est essentielle car AGENTS.md consomme de la fenêtre de contexte à chaque interaction.

Implications pour l'écosystème : Les résultats suggèrent que pour les connaissances générales de framework, le contexte passif (toujours disponible) surperforme la récupération active (à la demande). Les skills conservent toutefois leur utilité pour les workflows d'actions explicites. Vercel propose une commande d'installation (npx @next/codemod@canary agents-md) qui détecte automatiquement la version de Next.js et génère l'AGENTS.md correspondant.

Recommandations : Ne pas attendre l'amélioration des skills, compresser agressivement la documentation dans les index, et construire des évaluations ciblant spécifiquement les APIs absentes des données d'entraînement. Ces résultats ont des implications directes pour tous les mainteneurs de frameworks et bibliothèques cherchant à optimiser la compatibilité avec les agents de codage IA.