xufang5219/agent-skills

Frage Matt

Du erinnerst dich nicht an jeden Skill, also frage.

Bevor du sagst, was ein Skill tut oder empfiehlst, einen Schritt zu überspringen, lies die SKILL.md des Skills: Die Zusammenfassungen hier dienen nur der Orientierung.

Ein Flow ist ein Pfad durch die Skills. Die meisten Pfade verlaufen entlang eines Hauptflusses, und zwei Auffahrten münden in ihn ein. Alles andere ist eigenständig oder eine Vokabularschicht, die darunter liegt.

Der Hauptfluss: Idee → Auslieferung

Der Weg, den die meiste Arbeit nimmt. Du hast eine Idee und möchtest sie umgesetzt haben.

1. /grill-with-docs schärft die Idee durch ein Interview. Beginne hier, immer wenn du in einem Arbeitsverzeichnis arbeitest: Es ist zustandsbehaftet und behält das Gelernte in GLOSSARY.md und ADRs. (Kein Arbeitsverzeichnis? Verwende stattdessen /grill-me, unter Eigenständig beschrieben. Beide nutzen dieselbe /grilling-Primitive; grill-with-docs ist diejenige, die einen Papierpfad hinterlässt, was sie immer dann zur besseren der beiden macht, wenn ein Repository vorhanden ist, um ihn zu hinterlassen.)

2. Verzweigung: Kannst du jede Frage im Gespräch klären? Wenn eine Frage eine ausführbare Antwort benötigt (Zustand, Geschäftslogik, eine UI, die du sehen musst), mache einen Umweg über einen Prototypen, der in beide Richtungen durch /handoff überbrückt wird (ein Prototyp lebt in einem eigenen Verzeichnis, wofür /handoff genau da ist; siehe Phasengrenzen):

   • /handoff raus, dann öffne eine neue Sitzung für diese Datei,
   • /prototype um die Frage mit Wegwerfcode zu beantworten,
   • /handoff zurück, was du gelernt hast, und referenziere es aus dem ursprünglichen Ideenfaden.

3. Verzweigung: Ist dies ein Multi-Session-Build?

   • Ja → /to-spec (wandle den Faden in eine Spezifikation um), dann /to-tickets um ihn in Tracer-Bullet-Tickets aufzuteilen, die jeweils ihre blockierenden Kanten deklarieren. Dann arbeite die Tickets auf eine von zwei Arten ab:
     • /implement pro Ticket, mit /clear des Kontextes zwischen jedem. Bei einem lokalen Tracker als eine Datei pro Ticket unter .scratch/<feature>/issues/, zuerst von Hand nach Blockierern sortiert; bei einem echten Tracker werden die Kanten zu nativen Blockier-Links, sodass jedes Ticket, dessen Blockierer erledigt sind, aufgegriffen werden kann. Jedes Ticket ist in sich abgeschlossen, also ist der Kontext des letzten Tickets wegwerfbar.
     • /implement-spec für die gesamte Spezifikation in einem Durchlauf. Es liest die Tickets als Task-Graph, führt Implementierer-Subagenten parallel über die bereite Frontier aus und führt alles auf einem Integrationsbranch zusammen. Greife darauf zu, wenn du den Build lieber orchestrieren möchtest, anstatt jedes Ticket selbst zu fahren.
   • Nein → /implement direkt hier, im selben Kontextfenster.

   So oder so wird der Code durch /tdd (eine Rot-Grün-Scheibe nach der anderen) gebaut und mit /code-review abgeschlossen, einer zweiachsigen Überprüfung (Standards + Spezifikation) des Diffs. /implement führt beides pro Ticket aus; die Implementierer von /implement-spec treiben jeweils /tdd an, und es führt eine /code-review über den Integrationsbranch durch. Greife auf /tdd allein zu, wenn du einfach ein konkretes Verhalten test-first bauen möchtest, ohne eine vollständige Spezifikation, und auf /code-review allein, wann immer du einen Branch oder PR gegen einen festen Punkt überprüfen möchtest.

   Wenn die Arbeit als Pull Request hochgeht, formt /pr den Body: die kleinste visuelle Darstellung der Änderung, Vorher/Nachher-Belege dafür, dass es funktioniert, und ein One-Way- oder Two-Way-Door-Aufruf. Es ist modellgesteuert, also greift der Agent darauf zu, wann immer er einen PR schreibt.

4. /retro schließt den Kreis. Nach einem Build, insbesondere einem, der schiefgelaufen ist, blickt es auf die Sitzung zurück und schlägt Änderungen an der Umgebung des Agenten vor, nicht am Code: Navigationshinweise, automatisierte Prüfungen, die Codierungsstandards, die /code-review durchsetzt, Steuerungsdateien, Werkzeuge. Mechanische Fehler werden zu deterministischen Prüfungen; Ermessensentscheidungen werden zu Codierungsstandards. Der nächste Build beginnt dann in einer besseren Umgebung.

Kontexthygiene

Halte die Schritte 1–3 in einem ununterbrochenen Kontextfenster (nicht komprimieren oder löschen bis nach /to-tickets), damit die Befragung, die Spezifikation und die Tickets alle auf demselben Denken aufbauen. Jeder /implement beginnt dann frisch, ausgehend vom Ticket. Führe /retro in der Sitzung aus, auf die es zurückblickt, bevor du löschst; nach dem Löschen weise es stattdessen auf das Protokoll dieser Sitzung.

Die Grenze hierfür ist die Smart Zone: das Fenster (~150k Token bei modernen Modellen), in dem das Modell noch scharf denkt. Wenn eine Sitzung sich dieser Grenze vor /to-tickets nähert, treibe nicht auf degradiertem Niveau weiter; führe /compact an der nächsten Phasengrenze aus und fahre fort (siehe Phasengrenzen).

Auffahrten

Eine Startsituation, die Arbeit generiert und dann in den Hauptfluss mündet.

• Bugs und Anfragen häufen sich → /triage. Es bewegt Issues durch Triage-Rollen und erzeugt agentenbereite Issues, die /implement später aufnimmt.

  Triage ist nur für Issues, die du nicht erstellt hast: Bugmeldungen, eingehende Feature-Wünsche, alles, was roh ankommt. Tickets, die /to-tickets erzeugt hat, sind bereits agentenbereit, also triage sie nicht.

• Etwas ist kaputt → /diagnosing-bugs. Für die harten Fälle: der Bug, der einem ersten Blick widersteht, der intermittierende Flake, die Regression, die sich zwischen zwei bekannten guten Zuständen eingeschlichen hat. Es weigert sich zu theorisieren, bis es eine enge Rückkopplungsschleife hat (ein Befehl, der bereits auf diesen Bug rot wird), dann behebt es mit einem Regressionstest. Sobald der Fix drin ist, führe /retro in derselben Sitzung aus, um zu fragen, was den Bug verhindert hätte; wenn die eigentliche Erkenntnis ist, dass es keine gute Naht gibt, um ihn festzuzurren, ist das eine Aufgabe für /improve-codebase-architecture.

• Ein riesiges, verschwommenes Vorhaben: ein Greenfield-Projekt oder ein großer Feature-Build, zu groß für eine Sitzung → /wayfinder, der kognitiv anspruchsvollste Flow hier. Wenn der Weg von hier zum Ziel noch nicht sichtbar ist, zeichnet es eine gemeinsame Karte von Entscheidungstickets im Issue-Tracker und löst sie einzeln, wobei Entscheidungen, nicht Ergebnisse produziert werden, bis der Nebel sich gelichtet hat und der Weg klar ist. Wo /grill-with-docs eine Idee schärft, die du in einer Sitzung halten kannst, ist Wayfinder für die Idee, die du nicht halten kannst, und es ist langsamer und dichter, also hebe es dir genau dafür auf, niemals für ein gut abgegrenztes Feature.

  Wenn die Karte klar wird, übergibt es, es baut nicht: Münde in den Hauptfluss bei /to-spec ein, der die verknüpften Entscheidungen der Karte in einen baubaren Plan überführt, dann wie üblich zu /to-tickets und /implement. Die Karte direkt in /implement zu schleifen überspringt diese Überführung und wirft die verknüpften Details weg, also gehe nur dann direkt zu /implement, wenn sich das Vorhaben als wirklich klein herausgestellt hat.

Codebasis-Gesundheit

Keine Feature-Arbeit, nur Instandhaltung.

• /improve-codebase-architecture wird immer dann ausgeführt, wenn du einen freien Moment hast, um die Codebasis für Agenten gut beherrschbar zu halten. Es zeigt Vertiefungsmöglichkeiten auf; eine auszuwählen erzeugt eine Idee, die du in den Hauptfluss bei /grill-with-docs einbringen kannst. Es ist die Umfrage, die die Kandidaten findet; /codebase-design (unten) ist die Werkbank, auf der du den ausgewählten entwirfst.

Vokabular darunter

Zwei modellgesteuerte Referenzen, die unter den anderen Skills laufen, jede die einzige Quelle der Wahrheit für ihr Vokabular. Greife direkt darauf zu, wenn die Wörter, nicht der Prozess, das Problem sind; oder lass die obigen Skills sie einbinden.

• /domain-modeling: Schärfe die Domänensprache des Projekts: Hinterfrage einen unscharfen Begriff, löse ein überladenes Wort auf („Konto“ macht drei Jobs), zeichne eine schwer umkehrbare Entscheidung als ADR auf. Es ist die aktive Disziplin, die /grill-with-docs antreibt, um GLOSSARY.md als sauberes Glossar zu erhalten.
• /codebase-design ist das Tiefenmodul-Vokabular (Modul, Schnittstelle, Tiefe, Naht, Adapter, Hebelwirkung, Lokalität) zum Entwerfen der Form eines Moduls: viel Verhalten hinter einer kleinen Schnittstelle an einer sauberen Naht. /tdd und /improve-codebase-architecture sprechen es beide.

Phasengrenzen

Eine Phase ist ein Arbeitsbrocken innerhalb einer Sitzung: die Befragung, die Implementierung, die Qualitätssicherung. An der Grenze zwischen zwei von ihnen hast du fünf Optionen, und zwischen ihnen zu wählen ist die unscharfste Entscheidung in dieser gesamten Karte:

• Weitermachen: bleib, wo du bist. Kostet nichts, verliert nichts.
• /clear: leere das Fenster, wenn nichts hier für das Nächste wichtig ist.
• /handoff schreibt eine portable Markdown-Datei. Eng: nur für eine neue Umgebung, ein neues Verzeichnis, einen Kollegen oder zum Abspalten einer Nebenaufgabe mitten in einer Phase. Was es kauft, ist Portabilität.
• Subagent: sende eine eng abgegrenzte Aufgabe an ein eigenes Fenster und erhalte einen Bericht zurück.
• /compact komprimiert diesen Kontext und startet eine frische Sitzung damit. Die Voreinstellung, am unteren Ende des Baums, nicht der erste Griff.

Lies PHASE-BOUNDARIES.md für den geordneten Baum: die fünf Fragen, die Begründung hinter jedem Zweig und warum die Primärquellenkosten Weitermachen zum ersten K.O.-Kandidaten machen. Triff die Entscheidung an einer Grenze; mitten in der Phase, mach weiter oder teile den Rest in Subagenten auf.

Eigenständig

Völlig abseits des Hauptflusses.

• /grill-me: dasselbe unerbittliche Interview wie /grill-with-docs, aber zustandslos: es speichert nichts lokal und erstellt kein GLOSSARY.md. Greife darauf zu, wenn du nicht in einem Arbeitsverzeichnis arbeitest (Schärfung eines Plans, eines Designs, eines Texts, alles ohne Repository darunter). Wenn du in einem Arbeitsverzeichnis bist, verwende stattdessen /grill-with-docs: es führt dasselbe Interview durch und hinterlässt einen Papierpfad, also ist es strikt besser.
• /grilling ist die Interview-Primitive selbst: Runden, die Frontier, Fakten sind die Aufgabe des Agenten und Entscheidungen sind deine. /grill-me und /grill-with-docs sind die zwei benannten Einstiege, und /triage, /wayfinder und /improve-codebase-architecture führen es alle intern aus. Greife direkt darauf zu, nur wenn du das Interview ohne Hülle darum haben möchtest.
• /prototype ist ein kleines, wegwerfbares Programm, das eine einzige Designfrage beantwortet: Fühlt sich dieses Zustandsmodell richtig an, oder wie sollte diese UI aussehen. Wegwerfbar ist eine Einschränkung, wie der Code geschrieben wird, kein Versprechen, ihn zu zerstören: Die Antwort fließt in den echten Code ein, und der Prototyp selbst wird als Primärquelle auf einem prototype/<name>-Branch von main aus aufbewahrt, auf den vom Implementierungs-Issue verwiesen wird. Es ist der Umweg in Schritt 2 des Hauptflusses, aber greife jederzeit darauf zu, wenn eine Designfrage schwer auf dem Papier zu klären ist.
• /research: Delegiere Lese-Arbeit an einen Hintergrundagenten: Er untersucht eine Frage anhand von Primärquellen und hinterlässt dann eine zitierte Markdown-Datei im Repository. Arbeite weiter, während er liest. Die Datei, die er erzeugt, ist etwas, das in den Hauptfluss bei /grill-with-docs eingebracht wird, da Recherche das Denken füttert, nicht ersetzt.
• /to-questionnaire kommt zum Einsatz, wenn das, was dich blockiert, nicht in deinem Kopf oder der Codebasis liegt, sondern in der von jemand anderem, und es schreibt einen Fragebogen für diese Person. Es ist die Umkehrung von /grill-me: Statt dich über das Thema zu interviewen, interviewt es dich über den Absender (an wen es geht, was du zurückbrauchst) und richtet die Fragen auf die Lücke. Was zurückkommt, ist Material für /grill-with-docs oder /to-spec.
• /wizard ist für die Schritte, die nur ein Mensch ausführen kann: Infrastruktur bereitstellen, Anmeldeinformationen oder CI-Secrets einrichten, durch ein unbekanntes Drittanbieter-Dashboard klicken, eine einmalige Migration oder Umstellung durchführen. Es erzeugt ein interaktives Bash-Skript, das jede URL öffnet, jeden Wert erfasst und in .env und GitHub-Secrets schreibt, sodass die Prozedur aufhört, etwas zu sein, das du einem Agenten jedes Mal neu erklären musst. Modellgesteuert, also greift der Agent darauf zu, sobald er auf eine Wand trifft, die nur du passieren kannst. Wenn der Agent es einfach selbst tun könnte, sollte er es tun; dies ist für den Fall, dass ein Mensch wirklich in der Schleife ist.
• /wait-what ist die Korrektur für eine Nachricht, die nicht angekommen ist. Verwende es mitten im Gespräch, innerhalb jedes anderen Skills, und der Agent wiederholt, was er gerade gesagt hat, mit dem Kontext, der dir fehlte, in einfachem Englisch und unter Verwendung des GLOSSARY.md-Vokabulars. Es funktioniert im Nachhinein; /grill-with-docs ist die vorbeugende Kur, denn eine früh vereinbarte gemeinsame Sprache verhindert, dass der Jargon überhaupt erst ankommt.
• /teach: Lerne ein Konzept über mehrere Sitzungen hinweg, wobei das aktuelle Verzeichnis als zustandsbehafteter Arbeitsbereich dient.
• /writing-for-agents ist die Referenz zum Schreiben von Dokumenten, die Agenten konsumieren: Skills, AGENTS.md, Dokumente, auf die verwiesen wird.

Vorbedingung

/setup-matt-pocock-skills: Führe es vor deinem ersten Engineering-Flow aus, um den Issue-Tracker, Triage-Labels und das Dokumentlayout zu konfigurieren, das die anderen Skills erwarten. Eigene Issue-Tracker funktionieren ebenfalls.