Leçon 003 · Optimisation du contexte

Le contexte est une ressource à optimiser

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.

L'idée centrale : un skill n'est pas gratuit. Chaque skill que tu installes achète de la découvrabilité et vend du contexte. Le vrai mouvement, c'est de payer le contexte là où il rapporte, et de le déplacer derrière un pointeur là où il ne sert qu Occasionally.

Les deux charges

Chaque document que tu ajoutes à ton agent dépense l'un de deux budgets :

ChargeQui la paieCe que c'estComment on l'évite
Context loadL'agentLe 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 loadToiLe 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.
La phrase qui change la manière de voir

« 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. »

Levier 1 — Le pointeur de contexte

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.

La phrase clé

« 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.

Les 4 règles d'écriture d'un pointeur

Tu veux qu'un agent charge automatiquement le skill « Proxy residential » avant toute connexion web. Quelle formulation de pointeur est la plus fiable ?

Levier 2 — La divulgation progressive

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.

RangTypeCe que ça veut dire
1Étape dans le fichierCe que l'agent fait, dans l'ordre. Le rang principal.
2Référence dans le fichierConsulté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.
3Référence divulguéePoussée dans un fichier séparé, atteinte par un pointeur, chargée seulement quand le pointeur se déclenche.
Le test de la divulgation

« 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.

Appliqué chez toi : ton AGENTS.md

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 contientDiagnosticCe qu'il faut faire
Bloc « Logging » avec la commande bash complèteCache. 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ésLe 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.
La négation : le mode d'échec à côté du mot-clé

« 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.

Levier 3 — Les critères d'achèvement

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.

Clarté

L'agent peut-il distinguer « fini » de « pas fini » ? Une borne vague (« compréhension atteinte ») invite à la complétion prématurée.

Demande

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.

Les critères les forts sont à la fois vérifiables et exhaustifs

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é.

Exemple appliqué à tes skills

Formulation faibleFormulation fortePourquoi
« 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 ?

Le mot-clé : l'arme la moins chère

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étitionMot-cléGain
« rapide, déterministe, léger »tight3 mots → 1 token
« une boucle à laquelle tu crois »redUne garde floue devient un état observable binaire : la boucle passe red sur le bug, ou pas.
« une leçon »lessonLe concept existe déjà dans le pré-entraînement → recrutement gratuit.
La règle d'or des mots-clés

« 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 du no-op

Le test qui vaut plus que tous les autres : « cette phrase change-t-elle le comportement par rapport au défaut ? »

Trois no-ops à traquer dans ton AGENTS.md

① « 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à.

Les 5 skills de Matt Pocock à installer chez toi

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 :

SkillCe qu'il faitAdaptation 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.
Et le « routeur » ?

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.

La hiérarchie d'information appliquée à tes 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
Le test rapide pour un skill que tu viens d'écrire

① 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 ?

Sources : /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