xufang5219/agent-skills

Ask Matt

Vous ne vous souvenez pas de chaque compétence, alors demandez.

Avant de dire ce qu'une compétence fait ou de recommander de sauter une étape, lisez le SKILL.md de cette compétence : les résumés ici ne sont qu'à titre indicatif.

Un flux est un chemin à travers les compétences. La plupart des chemins suivent un flux principal, et deux voies d'accès s'y greffent. Tout le reste est autonome, ou une couche de vocabulaire qui s'exécute en dessous.

Le flux principal : idée → livraison

Le chemin que la plupart des travaux empruntent. Vous avez une idée et vous voulez la concrétiser.

1. /grill-with-docs affine l'idée par un entretien. Commencez ici chaque fois que vous travaillez dans un répertoire de travail : il est avec état, conservant ce qu'il apprend dans GLOSSARY.md et les ADR. (Pas de répertoire de travail ? Utilisez /grill-me à la place, couvert dans la section Autonome. Les deux exécutent la même primitive /grilling ; grill-with-docs est celui qui laisse une trace écrite, ce qui en fait le meilleur des deux chaque fois qu'un dépôt est là pour la recevoir.)

2. Branchement : pouvez-vous résoudre chaque question par la conversation ? Si une question nécessite une réponse exécutable (état, logique métier, une UI que vous devez voir), faites un détour par un prototype, ponté par /handoff dans les deux sens (un prototype vit dans son propre répertoire, ce qui est exactement le but de /handoff ; voir Limites de phase) :

   • /handoff vers l'extérieur, puis ouvrez une nouvelle session sur ce fichier,
   • /prototype pour répondre à la question avec du code jetable,
   • /handoff de retour de ce que vous avez appris, et référencez-le depuis le fil d'idée original.

3. Branchement : s'agit-il d'une construction multi-session ?

   • Oui → /to-spec (transformez le fil en spécification), puis /to-tickets pour le diviser en tickets traceurs, chacun déclarant ses dépendances bloquantes. Travaillez ensuite les tickets de l'une des deux manières suivantes :
     • /implement par ticket, en /clearant le contexte entre chaque. Sur un tracker local, c'est un fichier par ticket sous .scratch/<feature>/issues/, travaillé d'abord sur les bloquants à la main ; sur un vrai tracker, les dépendances deviennent des liens de blocage natifs, donc n'importe quel ticket dont les bloquants sont terminés peut être pris. Chaque ticket est autonome, donc le contexte du dernier est jetable.
     • /implement-spec pour toute la spécification en une seule exécution. Il lit les tickets comme un graphe de tâches, exécute des sous-agents d'implémentation sur la frontière prête en parallèle, et place tout sur une branche d'intégration unique. Utilisez-le lorsque vous préférez orchestrer la construction plutôt que de piloter chaque ticket vous-même.
   • Non → /implement ici même, dans la même fenêtre de contexte.

   Dans les deux cas, le code est construit en pilotant /tdd (une tranche rouge-vert à la fois) et se termine par /code-review, une revue sur deux axes (Normes + Spécification) du diff. /implement exécute les deux par ticket ; les implémenteurs de /implement-spec pilotent chacun /tdd, et il exécute une /code-review sur la branche d'intégration. Utilisez /tdd seul lorsque vous voulez simplement construire un comportement concret en mode test-first sans spécification complète, et /code-review seul chaque fois que vous voulez revoir une branche ou une PR par rapport à un point de référence.

   Lorsque le travail est soumis sous forme de pull request, /pr façonne le corps : le plus petit visuel montrant le changement, les preuves avant/après qu'il fonctionne, et un appel à décision unidirectionnelle ou bidirectionnelle. Il est invoqué par le modèle, donc l'agent l'utilise chaque fois qu'il écrit une PR.

4. /retro boucle la boucle. Après une construction, et surtout une qui a mal tourné, il examine la session et suggère des changements à l'environnement de l'agent, pas au code : pointeurs de navigation, vérifications automatisées, les normes de codage que /code-review applique, fichiers de pilotage, outils. Les erreurs mécaniques deviennent des vérifications déterministes ; les jugements deviennent des normes de codage. La construction suivante commence alors à partir d'un meilleur environnement.

Hygiène du contexte

Gardez les étapes 1 à 3 dans une seule fenêtre de contexte ininterrompue (ne compactez ni n'effacez avant /to-tickets) afin que le grillage, la spécification et les tickets reposent tous sur la même réflexion. Chaque /implement commence ensuite frais, en travaillant à partir du ticket. Exécutez /retro dans la session qu'il examine, avant d'effacer ; après effacement, pointez-le vers le journal de cette session à la place.

La limite est la zone intelligente : la fenêtre (~150k tokens sur les modèles de pointe) dans laquelle le modèle raisonne encore finement. Si une session s'en approche avant /to-tickets, ne continuez pas sur un modèle dégradé ; utilisez /compact à la limite de phase la plus proche et poursuivez (voir Limites de phase).

Voies d'accès

Une situation de départ qui génère du travail, puis rejoint le flux principal.

• Accumulation de bugs et de demandes → /triage. Il déplace les problèmes à travers les rôles de triage et produit des problèmes prêts pour l'agent, que /implement prendra ensuite en charge.

  Le triage est uniquement pour les problèmes que vous n'avez pas créés : rapports de bugs, demandes de fonctionnalités entrantes, tout ce qui arrive brut. Les tickets produits par /to-tickets sont déjà prêts pour l'agent, donc ne les triez pas.

• Quelque chose est cassé → /diagnosing-bugs. Pour les cas difficiles : le bug qui résiste à un premier coup d'œil, l'instabilité intermittente, la régression qui s'est glissée entre deux états connus bons. Il refuse de théoriser avant d'avoir une boucle de rétroaction serrée (une commande qui devient déjà rouge sur ce bug), puis corrige avec un test de régression. Une fois le correctif en place, exécutez /retro dans la même session pour demander ce qui aurait pu empêcher le bug ; lorsque la vraie conclusion est qu'il n'y a pas de bonne couture pour le verrouiller, c'est un travail pour /improve-codebase-architecture.

• Un effort énorme et flou : un projet greenfield ou une construction de fonctionnalité massive, trop grande pour une session → /wayfinder, le flux le plus exigeant cognitivement ici. Lorsque le chemin d'ici à la destination n'est pas encore visible, il trace une carte partagée de tickets de décision sur le tracker de problèmes et les résout un par un, produisant des décisions, pas des livrables, jusqu'à ce que le brouillard soit repoussé et que la voie soit claire. Là où /grill-with-docs affine une idée que vous pouvez tenir dans une session, wayfinder est pour l'idée que vous ne pouvez pas, et il est plus lent et plus dense, alors réservez-le exactement pour cela, jamais pour une fonctionnalité bien délimitée.

  Lorsque la carte s'éclaircit, il transmet, il ne construit pas : rejoignez le flux principal à /to-spec, qui condense les décisions liées de la carte en un plan constructible, puis /to-tickets et /implement comme d'habitude. Boucler la carte directement dans /implement saute cette condensation et jette les détails liés, alors allez directement à /implement uniquement lorsque l'effort s'est avéré vraiment petit.

Santé du codebase

Pas du travail fonctionnel, juste de l'entretien.

• /improve-codebase-architecture s'exécute chaque fois que vous avez un moment libre pour garder le codebase propice au travail des agents. Il fait remonter des opportunités d'approfondissement ; en choisir une génère une idée que vous pouvez amener dans le flux principal à /grill-with-docs. C'est l'enquête qui trouve les candidats ; /codebase-design (ci-dessous) est l'atelier sur lequel vous concevez celui choisi.

Vocabulaire sous-jacent

Deux références invoquées par le modèle qui s'exécutent sous les autres compétences, chacune étant la source unique de vérité pour son vocabulaire. Utilisez-les directement lorsque les mots, et non le processus, sont le problème ; ou laissez les compétences ci-dessus les appeler.

• /domain-modeling : affine le langage domaine du projet : contester un terme flou, résoudre un mot surchargé ("compte" faisant trois jobs), enregistrer une décision difficile à inverser comme ADR. C'est la discipline active que /grill-with-docs pilote pour garder GLOSSARY.md un glossaire propre.
• /codebase-design est le vocabulaire des modules profonds (module, interface, profondeur, couture, adaptateur, levier, localité) pour concevoir la forme d'un module : beaucoup de comportement derrière une petite interface à une couture propre. /tdd et /improve-codebase-architecture parlent tous les deux ce langage.

Limites de phase

Une phase est un morceau de travail à l'intérieur d'une session : le grillage, l'implémentation, le QA. À la limite entre deux d'entre elles, vous avez cinq options, et choisir entre elles est la décision la plus floue de toute cette carte :

• Continuer : restez où vous êtes. Ne coûte rien, ne perd rien.
• /clear : videz la fenêtre, quand rien ici n'importe pour la suite.
• /handoff écrit un fichier markdown portable. Étroit : uniquement pour un nouveau harnais, un nouveau répertoire, un collègue, ou pour bifurquer une tâche secondaire en milieu de phase. Ce qu'il apporte, c'est la portabilité.
• Sous-agent : envoyez une tâche étroitement délimitée à sa propre fenêtre et recevez un rapport.
• /compact compresse ce contexte et amorce une nouvelle session avec lui. Le par défaut, en bas de l'arbre plutôt que le premier recours.

Lisez PHASE-BOUNDARIES.md pour l'arbre ordonné : les cinq questions, le raisonnement derrière chaque branche, et pourquoi le coût de la source primaire fait de Continuer celui à écarter en premier. Prenez la décision à une limite ; en milieu de phase, continuez ou divisez le reste en sous-agents.

Autonome

Hors du flux principal.

• /grill-me : le même entretien incessant que /grill-with-docs, mais sans état : il ne sauvegarde rien localement et ne construit pas de GLOSSARY.md. Utilisez-le lorsque vous ne travaillez pas dans un répertoire de travail (affiner un plan, un design, un écrit, tout ce qui n'a pas de dépôt en dessous). Si vous êtes dans un répertoire de travail, utilisez /grill-with-docs à la place : il exécute le même entretien et laisse une trace écrite, donc il est strictement meilleur.
• /grilling est la primitive d'entretien elle-même : les tours, la frontière, les faits sont le travail de l'agent et les décisions sont les vôtres. /grill-me et /grill-with-docs sont les deux voies nommées, et /triage, /wayfinder et /improve-codebase-architecture l'exécutent toutes en interne. Utilisez-le directement uniquement lorsque vous voulez l'entretien sans emballage.
• /prototype est un petit programme jetable qui répond à une question de conception : ce modèle d'état est-il approprié, ou à quoi devrait ressembler cette UI. Jetable est une contrainte sur la façon dont le code est écrit, pas une promesse de le détruire : la réponse est intégrée dans le code réel, et le prototype lui-même est conservé comme source primaire sur une branche prototype/<nom> issue de main, référencée depuis le problème d'implémentation. C'est le détour à l'étape 2 du flux principal, mais utilisez-le chaque fois qu'une question de conception est difficile à trancher sur le papier.
• /research : déléguez le travail de lecture à un agent d'arrière-plan : il enquête sur une question à partir de sources primaires, puis laisse un fichier Markdown cité dans le dépôt. Continuez à travailler pendant qu'il lit. Le fichier qu'il produit est quelque chose à amener dans le flux principal à /grill-with-docs, car la recherche alimente la réflexion plutôt que de la remplacer.
• /to-questionnaire intervient lorsque ce qui vous bloque n'est pas dans votre tête ou le codebase mais dans celle de quelqu'un d'autre, et il leur écrit un questionnaire à remplir. C'est l'inverse de /grill-me : au lieu de vous interviewer sur le sujet, il vous interview sur l'envoi (à qui il est destiné, ce dont vous avez besoin en retour) et vise les questions sur l'écart. Ce qui revient est du matériel pour /grill-with-docs ou /to-spec.
• /wizard est pour les étapes que seul un humain peut prendre : provisionner une infrastructure, configurer des identifiants ou des secrets CI, naviguer dans un tableau de bord tiers inconnu, exécuter une migration ou un basculement ponctuel. Il génère un script bash interactif qui ouvre chaque URL, capture chaque valeur et l'écrit dans .env et les secrets GitHub, de sorte que la procédure cesse d'être quelque chose que vous réexpliquez à un agent à chaque fois. Invoqué par le modèle, donc l'agent l'utilise dès qu'il rencontre un mur que seul vous pouvez franchir. Si l'agent pouvait le faire lui-même, il devrait le faire ; c'est pour là où un humain est véritablement dans la boucle.
• /wait-what est le correctif pour un message qui n'a pas été compris. Utilisez-le en cours de conversation, à l'intérieur de n'importe quelle autre compétence, et l'agent reformule ce qu'il vient de dire avec le contexte qui vous manquait, en français simple, en utilisant le vocabulaire de GLOSSARY.md. Il fonctionne après coup ; /grill-with-docs est le remède préventif, car un langage partagé convenu tôt empêche le jargon d'arriver du tout.
• /teach : apprenez un concept sur plusieurs sessions, en utilisant le répertoire actuel comme espace de travail avec état.
• /writing-for-agents est la référence pour écrire des documents que les agents consomment : compétences, AGENTS.md, docs pointés.

Précondition

/setup-matt-pocock-skills : exécutez avant votre premier flux d'ingénierie pour configurer le tracker de problèmes, les étiquettes de triage et la disposition des documents que les autres compétences supposent. Les trackers de problèmes personnalisés fonctionnent aussi.