Leçon 003 · Optimisation du contexte
Tu as 173 skills. Le problème n'est pas d'en avoir peu — c'est que chacun te coûte du contexte. Voici les 3 leviers de Matt Pocock, appliqués à ta config réelle.
Chaque document que tu ajoutes à ton agent dépense l'un de deux budgets :
| Charge | Qui la paie | Ce que c'est | Comment on l'évite |
|---|---|---|---|
| Context load | L'agent | Le coût du matériel chargé en permanence : une ligne d'AGENTS.md, une description de skill. Des tokens et de l'attention, que le skill se déclenche ou non. | Mettre le matériel derrière un pointeur. |
| Cognitive load | Toi | Le coût de savoir quels documents existent et quand aller les chercher. Toi, tu es l'index. | Ça, on ne le minimise pas : c'est le prix de ton autonomie. |
« Le matériel atteint uniquement via un pointeur échappe à la context load, au prix de la ligne du pointeur. Le matériel sans aucun pointeur repose entièrement sur la cognitive load. »
Un pointeur de contexte est une référence gardée en mémoire par l'agent qui nomme un matériel hors-contexte et encode la condition pour aller le chercher. La description d'un skill en est un. Une ligne d'AGENTS.md qui nomme un doc en est un autre.
« C'est la formulation du pointeur, pas sa cible, qui décide de la fiabilité avec laquelle l'agent y va. »
Autrement dit : un matériel indispensable derrière un pointeur mal formulé = bug de variance. Le remède n'est pas de tout inliner — c'est de renforcer le pointeur d'abord.
Tu veux qu'un agent charge automatiquement le skill « Proxy residential » avant toute connexion web. Quelle formulation de pointeur est la plus fiable ?
Tout document est construit de deux types de contenu : des étapes (les actions ordonnées) et de la référence (définitions, règles, faits consultés à la demande).
La décision est : où chaque morceau se place sur l'échelle de l'information.
| Rang | Type | Ce que ça veut dire |
|---|---|---|
| 1 | Étape dans le fichier | Ce que l'agent fait, dans l'ordre. Le rang principal. |
| 2 | Référence dans le fichier | Consultée à la demande. Souvent un ensemble plat (toutes les règles d'une revue sur un même rang) — c'est correct, pas une odeur. |
| 3 | Référence divulguée | Poussée dans un fichier séparé, atteinte par un pointeur, chargée seulement quand le pointeur se déclenche. |
« Inline ce que toutes les branches ont besoin, et pousse derrière un pointeur ce que seules certaines branches atteignent. »
Si tu pousses trop peu, le haut gonfle. Si tu pousses trop, tu caches du matériel dont l'agent a réellement besoin. Cette tension est toute la décision.
Regarde ton /root/.hermes/AGENTS.md réel. Il fait 2 400 caractères et contient 3 blocs : logging, wiki, discussion multi-bots. Analyse-le avec les 3 leviers :
| Ce qu'il contient | Diagnostic | Ce qu'il faut faire |
|---|---|---|
| Bloc « Logging » avec la commande bash complète | Cache. Il répète ce que l'environnement sait déjà (le script est sur le disque, lisible en 1 commande). Dupliqué dans les 5 AGENTS.md de profils. | Réduire à une ligne : « Log avant chaque réponse (voir ~/.hermes/agents/_shared/LOGGING_POLICY.md) ». Le détail est déjà dans le fichier pointé. |
| Bloc « Wiki » : 3 commandes + « JAMAIS de config inventée » + la liste des fiches clés | Le cœur. Condition (« à CHAQUE début de session ») + cible (« wiki index ») + les branches. La négation (« JAMAIS de config inventée ») est une interdiction. | Transformer la négation en positif : « une config système vient toujours d'une fiche wiki lue, jamais d'une supposition ». Et pointer vers wiki rules pour le reste. |
| Bloc « Discussion multi-bots » | Excellent. Condition explicite (« si tu vois un message d'un autre bot ») → skill nommé → règles résumées. | Ne rien changer. C'est le modèle à copier. |
| Bloc « Notes » : 3 lignes (identité, nom minuscule, proxy) | Dupliqué dans les 5 profils. Une règle qui s'applique à tous n'a pas besoin d'être dans chaque AGENTS.md. | Le cas typique de la divulgation : une source de vérité (le fichier partagé), pointé depuis chaque profil. |
« Steerer par la prohibition fait entrer le comportement interdit dans le contexte et le rend plus disponible, pas moins. Ne pense pas à un éléphant — et l'éléphant est tout ce qu'il y a. »
Donc : prompts le positif (« écris des commentaires d'une ligne ») pour que le comportement banni ne soit jamais prononcé. Une interdiction ne se justifie que comme garde-fou impossible à formuler positivement — et même là, il faut l'accompagner de la cible positive.
Chaque étape se termine par un critère d'achèvement : la condition qui dit à l'agent que le travail est fini. Deux propriétés en font un levier.
L'agent peut-il distinguer « fini » de « pas fini » ? Une borne vague (« compréhension atteinte ») invite à la complétion prématurée.
Combien la chose exige. « Chaque modèle modifié accounted for » force un travail rigoureux là où « produis une liste de changements » ne le fait pas. La demande génère le legwork — le creusement que l'agent fait dans le travail, latent dans la formulation.
Et une nuance importante : la demande n'est pas liée à l'étape. « Chaque règle appliquée » lie aussi un document tout-référence, pas seulement une séquence. C'est comme ça qu'un document de règles peut porter une barre d'exhaustivité.
| Formulation faible | Formulation forte | Pourquoi |
|---|---|---|
| « Cite les sources » | « Chaque affirmation porte un lien, et une source primaire est nommée par leçon » | La seconde est vérifiable (on peut compter les lignes sans lien) et exhaustive (elle interdit la leçon sans citation). |
| « Sois bref » | « Une action par message » | « Bref » est une intention, pas un critère. « Une action par message » estvérifiable. |
| « Réponds bien » | « Tu vérifies par la source primaire avant de valider » | Vérifiable : la vérification est-elle faite ? |
Un leading word est un concept compact déjà présent dans le pré-entraînement du modèle, que l'agent utilise comme thinking token. Répété comme jeton, jamais comme phrase, il accumule une définition distribuée et ancre une région entière de comportement en quelques tokens.
| Répétition | Mot-clé | Gain |
|---|---|---|
| « rapide, déterministe, léger » | tight | 3 mots → 1 token |
| « une boucle à laquelle tu crois » | red | Une garde floue devient un état observable binaire : la boucle passe red sur le bug, ou pas. |
| « une leçon » | lesson | Le concept existe déjà dans le pré-entraînement → recrutement gratuit. |
« Un mot inventé ne recrute aucun priori : tu paies en tokens de définition ce qu'un mot pré-entraîné donne gratuitement. Cherche un mot existant d'abord. »
Et : un mot trop faible pour battre le défaut (« sois rigoureux » quand l'agent est déjà rigoureux) est un no-op. Le remède n'est pas une autre technique — c'est un mot plus fort.
Le test qui vaut plus que tous les autres : « cette phrase change-t-elle le comportement par rapport au défaut ? »
① « Use your agent name in lowercase for logging » — répété dans les 5 profils, et l'agent l'a déjà fait.
② « Agent identity is set per-channel via discord.channel_prompts » — l'agent voit sa propre identité dans le prompt système, c'est un fait d'environnement.
③ La liste des 3 fiches wiki clés — c'est de la référence qui n'a rien à faire dans un pointeur toujours chargé : elle va dans le fichier wiki, où elle est déjà.
J'ai lu les 27 skills promus du repo. Voici les 5 qui ont le plus d'impact dans ton cas, avec ce qu'il faut adapter :
| Skill | Ce qu'il fait | Adaptation nécessaire chez nous |
|---|---|---|
| writing-for-agents | La référence d'écriture pour tout document lu par un agent : skills, AGENTS.md, specs, prompts. Contient les 3 leviers de cette leçon. | Déjà model-invoked → installer tel quel, en adaptant « CLAUDE.md » → « AGENTS.md » et en remplaçant « the Skill tool » par skill_view. C'est le meilleur investissement de la liste. |
| wait-what | Trois lignes. Quand tu n'as pas compris, l'agent re-pitch avec le contexte manquant. Le mot-clé wait porte tout le skill. | user-invoked (déclenché par toi). Adapte : ASD-STE100 → français simple, et GLOSSARY.md → ton wiki crew. « Stop, j'ai pas suivi » devient un réflexe. |
| diagnosing-bugs | Une discipline de diagnostic en phases pour les bugs durs. « Skip phases only when explicitly justified. » | model-invoked (il doit se déclencher sur « debug ce truc »). Très pertinent chez toi : tu as 5 agents qui bosses sur du code en parallèle (Vintrack, LBC, DataProxy…). |
| research | Lance un agent en arrière-plan pour lire des sources primaires, écrit un fichier Markdown cité. « Spin up a background agent … Start it with a fresh context window. » | model-invoked. Directement l'équivalent de delegate_task chez nous. À porter en priorité : c'est le skill qui rapporte le mieux les sources citées — le défaut récurrent de l'agent. |
| tdd | Le cycle red → green. La référence qui fait que le cycle produit des tests qui valent la peine d'être gardés. | model-invoked. Utile pour Dev. Moins urgent que les 4 autres si tu ne codes pas en TDD. |
Quand les skills user-invoked s'accumulent au-delà de ce que tu peux retenir, le remède est un skill routeur : un skill user-invoked qui nomme les autres et dit quand aller les chercher. Tu n'as plus à en retenir 10, tu en retiens 1.
Chez toi, c'est ce cours qui joue ce rôle. Il ne fait pas qu'être : chaque leçon est un routeur vers un sous-ensemble de skills.
Voici l'arbre que tes 173 skills devraient former :
Rang 1 — AGENTS.md (toujours chargé)
Règles de conduite de la crew, 3-4 lignes max
↓ pointeurs
Rang 2 — Description d'un skill (chargée en permanence, ~200 car.)
Ce que ça fait + QUAND l'atteindre
↓ pointeur
Rang 3 — SKILL.md (chargé au déclenchement)
Les étapes de la procédure
↓ pointeurs
Rang 4 — references/ (chargé à la demande)
Format de fichier, tableaux de référence, code source
① Ma description contient-elle la condition de déclenchement en français, avec tes mots ?
② Chaque étape a-t-elle un critère d'achèvement vérifiable ?
③ Y a-t-il une phrase que je peux supprimer sans changer le comportement ?
④ Est-ce que j'ai inventé un mot, ou est-ce que j could've utilisé un mot déjà connu du modèle ?
/tmp/mp_skills/skills/productivity/writing-for-agents/SKILL.md +
SKILL-MECHANICS.md (repo mattpocock/skills, commit 4ae2317 du 2026-10-31) ·
docs/productivity/*.md du même repo ·
aihero.dev/skills-writing-for-agents