writing-great-skills

Une skill existe pour maîtriser le déterminisme dans un système stochastique. La prévisibilité — l'agent suivant le même processus à chaque exécution, non pas produisant la même sortie — est la vertu fondamentale ; chaque levier ci-dessous la sert.

Les termes en gras sont définis dans GLOSSARY.md ; cherchez-y la signification complète.

Invocation

Deux choix, aux coûts différents :

• Une skill model-invoked conserve une description, permettant à l'agent de l'activer autonomiquement et à d'autres skills de l'atteindre (vous pouvez aussi taper son nom). Elle contribue à la context load — la description reste dans la fenêtre à chaque tour. Mécaniques : omettez disable-model-invocation, et écrivez une description orientée modèle avec une formulation riche des déclencheurs (« Utiliser quand l'utilisateur veut…, mentionne…»).
• Une skill user-invoked retire la description de la portée de l'agent : seul vous, en tapant son nom, pouvez l'invoquer — et aucune autre skill ne le peut. Zéro context load, mais elle consomme de la cognitive load : vous êtes l'index qui doit se souvenir qu'elle existe. Mécaniques : définissez disable-model-invocation: true ; la description devient orientée humain — un résumé en une ligne, listes de déclencheurs supprimées.

Choisissez model-invocation seulement quand l'agent doit atteindre la skill de son propre chef, ou quand une autre skill le doit. Si elle ne s'active que manuellement, rendez-la user-invoked et n'encourez aucune context load.

Quand les skills user-invoked se multiplient au-delà de ce que vous pouvez retenir, cette accumulation de cognitive load est résolue par une router skill : une skill user-invoked qui énumère les autres et quand les utiliser.

Rédiger la description

Une description model-invoked assume deux rôles — énoncé ce que la skill est, et énumère les branches qui devraient la déclencher. Chaque mot augmente la context load, donc une description mérite un élagage encore plus agressif que le corps :

• Priorité au mot principal de la skill — la description y fait le travail d'invocation.
• Un déclencheur par branche. Les synonymes qui renomment une branche unique sont une duplication — « construire des fonctionnalités avec TDD … demande le développement test-first » est une branche écrite deux fois. Collapsiez-les ; gardez seulement les branches véritablement distinctes.
• Supprimez l'identité déjà dans le corps. Réduisez la description aux déclencheurs, plus toute clause « quand une autre skill a besoin… » d'atteinte.

Hiérarchie de l'information

Une skill est construite à partir de deux types de contenu — étapes et référence — qui se mélangent librement : une skill peut être toutes étapes, toute référence, ou les deux. La décision clé est laquelle utiliser et où chacune se situe sur la hiérarchie de l'information, une échelle classée par l'immédiateté avec laquelle l'agent a besoin du matériel :

1. Étape in-skill — une action ordonnée dans SKILL.md, le niveau primaire : ce que l'agent fait, dans l'ordre. Chaque étape se termine sur un critère d'achèvement, la condition qui dit à l'agent que le travail est fait. Rendez-le vérifiable (l'agent peut-il distinguer fait de non-fait ?) et, là où cela compte, exhaustif (« chaque modèle modifié comptabilisé », non « produire une liste de changements ») — un critère vague invite l'achèvement prématuré.
2. Référence in-skill — une définition, règle, ou fait dans SKILL.md, consulté à la demande. Souvent un ensemble de pairs légitime ment plat (chaque règle d'une review sur un même niveau) — un arrangement fin, non un symptôme. Cette skill est toute référence.
3. Référence externe — référence poussée hors de SKILL.md dans un fichier séparé, accessible par un context pointer, chargée seulement quand le pointeur s'active. (Va de la référence divulguée — un fichier frère comme GLOSSARY.md, toujours partie de la skill — jusqu'à la référence entièrement externe qui vit en dehors du système de skills et que n'importe quelle skill peut pointer.)

Un critère d'achèvement exigeant pilote un legwork thorough — le travail que l'agent fait dans l'exécution — que la skill ait des étapes ou non, puisque « chaque règle appliquée » lie une référence plate tout comme « chaque étape faite » lie une séquence.

Pousser trop peu vers le bas gonfle le sommet ; pousser trop fait disparaître le matériel dont l'agent a réellement besoin. Cette tension est toute la décision.

La progressive disclosure est le mouvement vers le bas de l'échelle — hors de SKILL.md dans un fichier lié — pour que le sommet reste lisible. Mécaniques : un fichier .md lié dans le dossier skill, nommé pour ce qu'il contient (cette skill divulgue ses définitions complètes à GLOSSARY.md). Certaines skills sont utilisées de plus d'une façon, et chaque façon distincte est une branche — différentes exécutions empruntant différents chemins à travers la skill. Le branchement est le test de divulgation le plus net : insérez ce que chaque branche doit, et pointez derrière ce que seules certaines branches atteignent. La formulation d'un context pointer, non sa cible, détermine quand et avec quelle fiabilité l'agent atteint le matériel.

Là où l'échelle décide de quelle distance une pièce se situe, la co-location décide ce qui la côtoie une fois là : gardez la définition, règles, et mises en garde d'un concept sous un en-tête plutôt que dispersées, afin que lire une partie apporte ses voisines.

Quand scinder

La granularité est la finesse avec laquelle vous divisez les skills, et chaque coupure consomme une des deux charges, donc scindez seulement quand cela en vaut la peine. Deux coupures :

• Par invocation — séparez une skill model-invoked quand vous avez un mot principal distinct qui devrait la déclencher seul, ou quand une autre skill doit l'atteindre. Vous payez la context load pour la nouvelle description toujours chargée, donc cette atteinte indépendante doit en valoir la peine.
• Par séquence — scindez une série d'étapes quand les étapes encore à venir (les post-completion steps d'une étape) tentent l'agent de précipiter celle devant lui (achèvement prématuré). Les tenir hors de vue encourage l'agent à faire plus de legwork sur la tâche actuelle.

Élagage

Gardez chaque signification dans une source unique de vérité : un endroit faisant autorité, pour que changer le comportement soit une édition en un seul lieu.

Vérifiez chaque ligne pour la pertinence : compte-t-elle encore dans ce que la skill fait ?

Puis traquezles no-ops phrase par phrase, non seulement ligne par ligne : appliquez le test no-op à chaque phrase isolément, et quand une échoue, supprimez la phrase entière plutôt que d'en tailler les mots. Soyez agressif — la plupart de la prose qui échoue doit partir, non être réécrite.

Mots principaux

Un mot principal est un concept compact vivant déjà dans le préentraînement du modèle que l'agent utilise en exécutant la skill (p. ex. leçon, brouillard de guerre, tracer bullets). Répété partout le texte (bien que pas nécessairement — un mot principal solide ne peut être nécessaire qu'une fois), il accumule une définition distribuée et ancre toute une région de comportement dans les jetons les plus rares, en recrutant les priors que le modèle détient déjà.

Il sert la prévisibilité deux fois. Dans le corps il ancre l'exécution : l'agent cherche le même comportement chaque fois que le mot apparaît. Dans la description il ancre l'invocation : quand le même mot vit dans vos prompts, docs, et code, l'agent lie ce langage partagé à la skill et l'active plus fiablement.

Cherchez des occasions de refactoriser les skills pour utiliser les mots principaux. Un trio énoncé en trois endroits (duplication), une description dépensant une phrase pour désigner une idée — chacun est un passage implorant de se collapser en un seul token. Les exemples incluent :

• « rapide, déterministe, faible surcharge » -> tight — une qualité restate sur une phase — en un seul mot préentraîné (une boucle tight).
• « une boucle en laquelle vous croyez » -> red — convertit une porte floue en un état observable binaire (la boucle devient red sur le bug, ou elle ne le devient pas).

Vous gagnez deux fois : moins de tokens, et un crochet plus aiguisé pour que l'agent y accroche sa réflexion. Supposez que chaque skill porte des restatements que les mots principaux retirent — allez les trouver.

Modes de défaillance

Utilisez-les pour diagnostiquer les problèmes que l'utilisateur peut avoir avec la skill.

• Achèvement prématuré — terminer une étape avant qu'elle soit vraiment faite, l'attention glissant vers être fait. Défense, dans l'ordre : aiguisez d'abord le critère d'achèvement (bon marché, local) ; seulement si c'est irréductiblement flou et vous observez la précipitation, cachez les post-completion steps en scindant (la coupure de séquence).
• Duplication — le même sens en plus d'un endroit. Coûte maintenance et tokens, et gonfle la prominence d'un sens sur l'échelle au-delà de son rang réel.
• Sédiment — des couches stales qui s'accumulent parce qu'ajouter semble sûr et retirer semble risqué. Le destin par défaut de toute skill sans discipline d'élagage.
• Sprawl — une skill simplement trop longue, même si chaque ligne est vive et unique. Nuit à la lisibilité et maintenabilité et gaspille des tokens. La cure est l'échelle : divulguez la référence derrière des pointeurs, et scindez par branche ou séquence afin que chaque chemin porte seulement ce dont il a besoin.
• No-op — une ligne que le modèle obéit déjà par défaut, donc vous payez load pour ne rien dire. Le test : change-t-elle le comportement versus le défaut ? Un mot principal faible (soyez approfondi quand l'agent est déjà approximativement approfondi) est un no-op ; la solution est un mot plus fort (implacable), non une technique différente.