Agent Skills : construire le chargeur, écrire et tester des skills

L'assistant interne d'une entreprise de 900 personnes a commencé avec un prompt système de 300 lignes. Six mois plus tard, la finance y a ajouté le barème des notes de frais, les RH les règles de congés, le support sa matrice de priorité : 40 000 tokens envoyés à chaque question, y compris « quelle est la différence entre la médiane et la moyenne ? ». La facture suit, la latence aussi, et une modification du barème de frais casse le tri des tickets sans que personne ne s'en aperçoive.

Les Agent Skills règlent ce problème par une convention simple : chaque savoir-faire vit dans son dossier (SKILL.md, scripts, références), le modèle ne voit au départ que le nom et la description de chacun, et le harness charge le reste quand le modèle en a besoin. Le format est ouvert (agentskills.io), lu notamment par Claude, Gemini Enterprise et Google ADK. Ce projet vous fait écrire le chargeur vous-même, puis le comparer à celui d'ADK, et surtout mesurer : le bon skill est-il choisi, la réponse est-elle meilleure, combien de tokens a-t-on économisé.

Démo réelle du 2026-10-15 : la note de frais active un skill, son script calcule 140,00 € remboursables, 3 fichiers de niveau 3 chargés

Ce que vous livrez

Un dépôt prêt à cloner (files/) :

six skills conformes à la spécification, dont trois repris de la bibliothèque de skills Gemini Enterprise (meeting-notes-to-actions, hr-policy-qa, ticket-triage) et trois nouveaux avec scripts et références (expense-report-checker, leave-balance-calculator, csv-data-profiler) ;
un validateur strict de SKILL.md et un verrou de versions (skills.lock.json) qui refuse un skill modifié sans changement de version ;
un chargeur à divulgation progressive : catalogue, activation, ressources à la demande, avec liste blanche des fichiers ;
un bac à sable de scripts : copie jetable, environnement vidé, réseau coupé par unshare -rn, limites CPU, mémoire et taille de fichier, délai ;
une boucle d'agent google-genai à trois modes (progressif, tout charger, sans skill) et le même agent en Google ADK 2.10 avec SkillToolset ;
deux bancs d'essai : 30 requêtes de déclenchement (modèle contre similarité d'embeddings) et 3 cas notés par grille, avec skill, sans skill et tout chargé ;
39 tests sans clé ni réseau, un make e2e réel, une démo web.

Architecture

flowchart LR
  Q["Question"] --> A["Boucle agent (harness.py)"]
  C["Catalogue : nom + description des 6 skills, 1 208 tokens"] --> A
  A <-->|"function calling"| M["Gemini (google-genai)"]
  A -->|"activate_skill"| L2["Corps SKILL.md (411 à 1 423 tokens)"]
  A -->|"read_skill_file"| L3["references/, assets/"]
  A -->|"run_skill_script"| S["Bac à sable : sans réseau, sans clé, délai 10 s"]
  V["Validateur + skills.lock.json"] --> C
  E["Évals : 30 requêtes, grille + juge"] --> A

Les mesures du 2026-10-15

Mesure	Résultat
Catalogue (niveau 1) contre tout charger	1 208 contre 9 261 tokens par requête, rapport 7,7
Déclenchement par le modèle, `gemini-3.5-flash`, 30 requêtes x 2 passages	60 / 60 décisions justes, 0 faux déclenchement
Déclenchement par le modèle, `gemini-3.5-flash-lite`	29 / 30, 1 faux déclenchement
Déclenchement par similarité d'embeddings (`gemini-embedding-2`)	24 / 24 positifs justes, mais 6 / 6 requêtes hors sujet déclenchent un skill
Grille de qualité, avec skill contre sans skill	16 / 16 contre 11 / 16 critères

Stack, coût, durée


Langage	Python 3.10+, `google-genai` 2.31, `google-adk` 2.10, `numpy`, `PyYAML`, `FastAPI` pour la démo
Modèles	`gemini-3.5-flash` (variable `MODEL`), `gemini-3.5-flash-lite`, `gemini-embedding-2`
Coût mesuré	`make e2e` : environ 40 000 tokens d'entrée ; `make eval` : environ 160 000. Moins de 0,30 $au total au tarif Gemini 3.6 Flash (0,75$ / 3,75 $ par million, page de tarifs du 2026-10-15)
Ressources cloud	aucune
Durée	6 h : 4 h 30 de leçons et de code, 1 h 30 d'exercices
Système	Linux pour l'isolation réseau des scripts ; ailleurs, le bac à sable refuse de démarrer sauf dérogation explicite

Prérequis

Python professionnel et function calling : le projet Construire son harness d'agent de code en donne la boucle de base.
Une clé Gemini API (Google AI Studio) pour make run, make e2e et make eval.

Programme

Module	Leçon	À la fin, cette commande marche
1. Le standard et le chargeur	Le format SKILL.md	`python run.py validate` : 6 skills OK
	La divulgation progressive	`python run.py tokens` : 1 208 contre 9 261
2. Choisir et exécuter	Qui choisit le skill ?	`pytest tests/test_loader.py`
	Scripts et bac à sable	`pytest tests/test_sandbox.py`, réseau coupé
	Le même chargeur avec Google ADK	`python run.py adk "…"`
3. Tester et versionner	Tester le déclenchement	`python run.py eval-trigger`
	Tester la qualité, versionner, livrer	`make e2e` vert, `make lock`

Démarrage

cd files
make setup        # .venv, dépendances, .env
make test         # validation des 6 skills + 39 tests, sans clé ni réseau
make run          # démo web sur http://localhost:8791
make e2e          # vrai modèle : 2 skills à script, 1 requête hors sujet, 1 passage par ADK
make eval         # tokens, 30 requêtes de déclenchement, grille de qualité
make clean        # supprime sorties/ et les caches