writing-great-skills

Une skill existe pour extraire du déterminisme d'un système stochastique. La prévisibilité — l'agent suivant le même processus à chaque exécution, non en 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 ; consultez-les là pour la signification complète.

Invocation

Deux choix, échangeant des coûts différents :

• Une skill invoquée par le modèle conserve une description, pour que l'agent puisse la déclencher de manière autonome et que d'autres skills puissent la atteindre (vous pouvez toujours taper son nom aussi). Elle contribue à la charge de contexte — la description s'assoit dans la fenêtre à chaque tour. Mécaniques : omettez disable-model-invocation, et écrivez une description orientée modèle avec un phraséage riche de déclencheurs (« Utiliser quand l'utilisateur veut…, mentionne…»).
• Une skill invoquée par l'utilisateur 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. Charge de contexte nulle, mais cela dépense de la charge cognitive : vous êtes l'index qui doit vous souvenir qu'elle existe. Mécaniques : définissez disable-model-invocation: true ; la description devient orientée humain — un résumé d'une ligne, listes de déclencheurs supprimées.

Choisissez l'invocation par modèle uniquement quand l'agent doit atteindre la skill de lui-même, ou qu'une autre skill doit le faire. Si elle ne se déclenche jamais qu'à la main, faites-la invoquée par l'utilisateur et ne payez aucune charge de contexte.

Quand les skills invoquées par l'utilisateur se multiplient au-delà de ce que vous pouvez retenir, cette charge cognitive accumulée est guérie par une skill routeur : une skill invoquée par l'utilisateur qui nomme les autres et quand les atteindre.

Rédiger la description

Une description invoquée par modèle fait deux travaux — exposer ce qu'est la skill, et énumérer les branches qui devraient la déclencher. Chaque mot augmente la charge de contexte, donc une description mérite un élagage encore plus dur que le corps :

• Mettez le mot clé de la skill en avant — la description est où elle fait son 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. Fusionnez-les ; conservez uniquement les branches véritablement distinctes.
• Coupez l'identité déjà dans le corps. Gardez la description aux déclencheurs, plus toute clause de portée « quand une autre skill a besoin… ».

Hiérarchie de l'information

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

1. Étape en skill — une action ordonnée dans SKILL.md, le palier primaire : ce que l'agent fait, dans l'ordre. Chaque étape se termine par 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 en skill — une définition, règle ou fait dans SKILL.md, consulté à la demande. Souvent un ensemble d'égaux légitime et plat (chaque règle d'un examen sur un palier) — un arrangement correct, non un indicateur. Cette skill n'est que référence.
3. Référence externe — la référence poussée hors de SKILL.md dans un fichier séparé, atteinte par un pointeur de contexte, chargée seulement quand le pointeur se déclenche. (S'étend de la référence divulguée — un fichier frère comme GLOSSARY.md, toujours partie de la skill — jusqu'à la référence complètement 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 pousse le travail approfondi — le creusement que l'agent fait au sein du travail — que la skill ait des étapes ou non, puisque « chaque règle appliquée » lie la référence plate tout autant que « chaque étape faite » lie une séquence.

Pousser trop peu vers le bas et le sommet s'enfle ; pousser trop et vous cachez le matériel que l'agent a réellement besoin. Cette tension est toute la décision.

La divulgation progressive est le mouvement vers le bas de l'échelle — hors de SKILL.md vers un fichier lié — pour que le sommet reste lisible. Mécaniques : un fichier .md lié dans le dossier de la 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 manière, et chaque façon distincte est une branche — différentes exécutions prenant des chemins différents à travers la skill. La création de branches est le test de divulgation le plus propre : intégrez ce que chaque branche doit avoir, et poussez derrière un pointeur ce que seules certaines branches atteignent. La formulation d'un pointeur de contexte, non sa cible, décide quand et à quelle fréquence l'agent atteint le matériel.

Où l'échelle décide de quelle profondeur une pièce s'assoit, la co-location décide de ce qui s'assoit à côté une fois là : gardez la définition, les règles et les mises en garde d'un concept sous un même titre plutôt que dispersés, pour que lire une partie apporte ses voisins avec.

Quand diviser

La granularité est la finesse avec laquelle vous divisez les skills, et chaque coupure dépense l'une des deux charges, donc divisez uniquement quand la coupure le mérite. Deux coupures :

• Par invocation — divisez une skill invoquée par modèle quand vous avez un mot clé distinct qui devrait la déclencher de lui-même, ou qu'une autre skill doit l'atteindre. Vous payez la charge de contexte pour la nouvelle description toujours chargée, donc cette portée indépendante doit en valoir la peine.
• Par séquence — divisez une suite d'étapes quand les étapes encore à venir (les étapes post-achèvement d'une étape) tentent l'agent de précipiter celle devant lui (achèvement prématuré). Les garder hors de vue encourage l'agent à faire plus de travail approfondi sur la tâche actuelle.

Élagage

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

Vérifiez chaque ligne pour la pertinence : a-t-elle toujours un rapport avec ce que la skill fait ?

Ensuite, traquezles non-opérations phrase par phrase, non juste ligne par ligne : exécutez le test de non-opération sur chaque phrase isolément, et quand l'une échoue, supprimez la phrase entière plutôt que d'en tailler des mots. Soyez agressif — la plupart des proses qui échouent doivent partir, non être réécrites.

Mots clés

Un mot clé est un concept compact déjà vivant dans le préentraînement du modèle avec lequel l'agent pense en exécutant la skill (par ex. leçon, brouillard de guerre, balles tracantes). Répété dans le texte (bien que pas nécessairement — un mot clé fort pourrait n'être besoin qu'une fois), il accumule une définition distribuée et ancre toute une région de comportement dans le moins de jetons possible, en recrutant des a priori que le modèle possède déjà.

Il sert la prévisibilité deux fois. Dans le corps il ancre l'exécution : l'agent atteint 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 la déclenche plus fiablement.

Cherchez des opportunités de refactoriser les skills pour utiliser des mots clés. Une triade épelée à trois endroits (duplication), une description dépensant une phrase pour faire un geste vers une idée — chacune est un passage suppliant à réduire en un seul jeton. Les exemples incluent :

• « rapide, déterministe, faible surcharge » -> serré — une qualité réaffirmée à travers une phase — en un seul mot préentraîné (une boucle serrée).
• « une boucle en laquelle vous croyez » -> rouge — convertit une porte floue en état observable binaire (la boucle devient rouge au bogue, ou elle ne l'est pas).

Vous gagnez deux fois : moins de jetons, et un crochet plus net pour l'agent d'y accrocher sa pensée. Supposez que chaque skill porte des réaffirmations que les mots clés 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 véritablement faite, l'attention glissant vers être fait. Défense, dans l'ordre : affinez d'abord le critère d'achèvement (bon marché, local) ; seulement si c'est irréductiblement flou et que vous observez la précipitation, cachez les étapes post-achèvement en divisant (la coupure de séquence).
• Duplication — le même sens à plus d'un endroit. Coûte la maintenance et les jetons, et gonfle la prominence d'un sens sur l'échelle au-delà de son rang réel.
• Sédiment — des couches obsolètes qui se déposent parce que l'ajout se sent sûr et la suppression se sent risquée. Le sort par défaut de toute skill sans discipline d'élagage.
• Débordement — une skill simplement trop longue, même quand chaque ligne est vivante et unique. Nuit à la lisibilité et maintenabilité et gaspille les jetons. La cure est l'échelle : divulguez la référence derrière des pointeurs, et divisez par branche ou séquence pour que chaque chemin porte seulement ce dont il a besoin.
• Non-opération — une ligne que le modèle obéit déjà par défaut, donc vous payez la charge pour ne rien dire. Le test : change-t-elle le comportement par rapport au défaut ? Un mot clé faible (soyez approfondi quand l'agent est déjà approfondi-ish) est une non-opération ; la correction est un mot plus fort (implacable), non une technique différente.
• Négation — diriger par interdiction échoue : ne pensez pas à un éléphant nomme l'éléphant et le rend plus disponible, non moins. Promptez le positif — exposez le comportement cible pour que celui interdit ne soit jamais prononcé ; gardez une interdiction seulement comme un garde-fou dur que vous ne pouvez pas exprimer positivement, et même alors associez-la à ce qu'il faut faire à la place.