La divulgation progressive

Six skills, c'est déjà 9 261 tokens si on colle tout dans le prompt système : les corps, les barèmes, les scripts. À soixante skills, l'ordre de grandeur passe à 90 000 tokens par question, avant même que l'utilisateur ait écrit un mot. La plupart des questions n'ont besoin d'aucun skill, les autres d'un seul. Le harness doit donc envoyer peu au départ et charger le reste au moment précis où le modèle le demande.

Le mécanisme

La spécification décrit trois niveaux. Le harness en est responsable ; le modèle n'en voit que les effets.

Nos descriptions font environ 700 caractères, avec phrases déclencheuses bilingues : 170 à 200 tokens chacune, au-dessus de la fourchette de la spécification. C'est un choix : la description porte tout le déclenchement (leçon suivante).

sequenceDiagram
  participant U as Utilisateur
  participant H as Harness
  participant M as Gemini
  participant B as Bac à sable
  U->>H: « Contrôle ma note de frais : … »
  H->>M: instructions + catalogue (niveau 1) + 3 outils
  M-->>H: activate_skill(expense-report-checker)
  H->>M: corps SKILL.md + liste des ressources (niveau 2)
  M-->>H: run_skill_script(scripts/check_expenses.py, --csv …)
  H->>B: copie jetable, sans réseau
  B-->>H: JSON : total_remboursable 140.0
  M-->>H: read_skill_file(assets/rapport.md) (niveau 3)
  M-->>H: réponse finale

La mise en œuvre

Le chargeur (loader.py) expose trois outils au modèle. Le nom du skill est une énumération dans le schéma JSON : le modèle reçoit la liste exacte des noms valides au lieu d'en deviner un, et le harness rejette tout nom absent du catalogue.

def tool(self) -> types.Tool:
    names = {"type": "string", "enum": sorted(self.skills)}
    return types.Tool(function_declarations=[
        types.FunctionDeclaration(name="activate_skill", ...,
            parameters_json_schema={"type": "object", "properties": {"name": names}, "required": ["name"]}),
        types.FunctionDeclaration(name="read_skill_file", ...),
        types.FunctionDeclaration(name="run_skill_script", ...),
    ])

L'activation renvoie le corps entouré de balises et liste les ressources sans les lire. Une seconde activation du même skill ne réinjecte rien.

def activate(self, name: str) -> str:
    s = self._get(name)
    if name in self.active:
        return f'<skill_content name="{name}">déjà chargé plus haut dans la conversation</skill_content>'
    self.active.append(name)
    res = "\n".join(f"  <file>{r}</file>" for r in s.resources)
    return (f'<skill_content name="{name}" version="{s.version}">\n{s.body}\n\n'
            f"<skill_resources>\n{res}\n</skill_resources>\n</skill_content>")

La lecture d'un fichier passe par une liste blanche : seul un chemin présent dans skill.resources est servi. ../hr-policy-qa/SKILL.md, /etc/passwd ou SKILL.md lui-même sont refusés, et la réponse d'erreur part au modèle au lieu de lever une exception. La boucle (harness.py) désactive l'exécution automatique des fonctions du SDK et cumule usage_metadata.prompt_token_count à chaque appel : c'est la seule mesure qui compte, car chaque tour renvoie tout l'historique.

Résultat obtenu

python run.py tokens, API count_tokens, gemini-3.5-flash, 2026-10-15 (extrait) :

{
 "niveau1_catalogue": 1208,
 "niveau2_corps": {"csv-data-profiler": 411, "expense-report-checker": 543, "hr-policy-qa": 1177,
                   "leave-balance-calculator": 538, "meeting-notes-to-actions": 1309, "ticket-triage": 1423},
 "tout_charger": 9261,
 "economie_par_requete_sans_skill": 8053,
 "ratio": 7.7
}

Tokens d'entrée cumulés sur des requêtes réelles du même jour (run.py eval-quality et run.py e2e) :

Le gain est d'un facteur 2 à 4 par requête, pas 7,7 : le mode progressif fait plus d'allers-retours, et chacun renvoie l'historique entier. Le cas de la note de frais le montre : cinq appels (activer, exécuter, lire le gabarit, lire la politique, répondre) contre trois.

Ce qui casse en production

La règle de décision

Utilisez la divulgation progressive dès que le total « tout charger » dépasse quelques milliers de tokens ou que la majorité des requêtes n'utilise aucun skill. Restez en chargement complet pour deux ou trois skills courts appelés presque à chaque requête : vous économisez un tour, et un préfixe stable profite du cache de prompt. Mesurez toujours les tokens cumulés d'une requête réelle, jamais seulement la taille du catalogue.

Pratique

Exercice. Ajoutez au résultat de SkillAgent.ask le nombre de tokens apportés par chaque niveau (catalogue, corps, ressources), en vous servant des réponses d'outils. Comparez-le aux tokens cumulés : quelle part vient de la répétition de l'historique ?

• Je sais expliquer les trois niveaux et ce qui déclenche chacun
• Je sais contraindre les noms de skills par une énumération
• Je sais servir les ressources par liste blanche
• Je sais mesurer les tokens cumulés d'une requête et pas seulement le prompt système