Agent-Skills und Plugins schreiben, die richtig geladen werden und auslösen

## Die offizielle Dokumentation lesen und einen Referenz-Skill anpassen Bevor irgendetwas geschrieben wird, ist die aktuelle offizielle Dokumentation des angestrebten Plugin- und Skill-Systems zu lesen: das Plugin-Format, das Skill-Format und die veröffentlichten Empfehlungen zum Verfassen. Die Dokumentation des Herstellers ändert sich schneller als jede Darstellung Dritter; sie gilt daher als maßgebliche Quelle, und Anleitungen aus der Gemeinschaft gelten nur als Kommentar dazu. Anschließend einen Referenz-Skill auf der benötigten Komplexitätsstufe auswählen und ihn anpassen, statt eine Struktur von Grund auf zu entwerfen: - Einfach: knappes Frontmatter und ein kurzer Block mit Hinweisen, sonst nichts. - Mittel: ein Sprachpaket, ein Referenzverzeichnis und sprachspezifische Dokumente. - Fortgeschritten: Skripte, Workflow-Dateien, Vorlagen, Hilfsmittel zur Extraktion und mehrere Einstiegspunkte. Zwei oder drei produktiv eingesetzte Plugins anderer Teams zu lesen, geht meist schneller, als sich einen Aufbau auszudenken. Wenn die Umgebung einen dokumentationskundigen Hilfsagenten für Fragen zu Plugins und Skills bereitstellt, sind diese Fragen dorthin zu leiten, statt sie aus dem Gedächtnis zu beantworten. ## Eine einzige Metadatenquelle behalten, auch wenn mehrere Laufzeitumgebungen das Plugin laden Wenn mehr als eine Agenten-Laufzeitumgebung das Plugin laden kann, ist ein einziges Metadatenformat als maßgeblich zu wählen; zusätzliche Beikopien je Laufzeitumgebung werden nicht angelegt. Doppelt geführte Metadaten laufen auseinander, und dieses Auseinanderlaufen wird von den Nutzenden entdeckt, nicht von der Bauautomatisierung. In der Praxis: - Das Marktplatz-Manifest und das Manifest je Plugin bleiben an ihrem einen maßgeblichen Ort. - Keine parallelen, laufzeitspezifischen Manifestverzeichnisse oder Plugin-Metadatenverzeichnisse für eine zweite Laufzeitumgebung anlegen. - Alle Bestandteile im Wurzelverzeichnis des Plugins belassen und dabei die Standardpfade nutzen, die beide Laufzeitumgebungen bereits verstehen: das Skill-Verzeichnis, die Hook-Datei, die MCP-Konfigurationsdatei und die Anwendungs-Konfigurationsdatei. - Braucht ein Plugin eine MCP-Konfiguration, gehört sie in die eigens dafür vorgesehene MCP-Konfigurationsdatei im Wurzelverzeichnis des Plugins, statt als Objekt in das Plugin-Manifest eingebettet zu werden. Vor dem Einreichen die Ladeprüfung für jede unterstützte Laufzeitumgebung ausführen. Scheitert eine Laufzeitumgebung, wird die maßgebliche Quelle korrigiert, damit die andere Laufzeitumgebung sie über den Kompatibilitätsweg laden kann – niemals dadurch, dass eine zweite Kopie derselben Metadaten angelegt wird. ## Komponentenverzeichnisse in die Plugin-Wurzel legen, nicht ins Metadatenverzeichnis Ein Plugin-Verzeichnis enthält ein Plugin-Metadatenverzeichnis, in dem ausschließlich das Plugin-Manifest liegt (Name, Version, Beschreibung, Autor), dazu optionale Verzeichnisse für Schrägstrich-Befehle, autonome Agenten, Skills und Ereignis-Hooks sowie eine README-Datei, die das Plugin dokumentiert. Jeder Skill liegt in einem eigenen Verzeichnis unterhalb des Skill-Verzeichnisses, mit einem Einstiegsdokument, das das Frontmatter trägt, und optionalen Unterverzeichnissen für Referenzen, Workflows und Skripte. Die Regel, über die die meisten stolpern: Die Verzeichnisse der Bestandteile – Skills, Befehle, Agenten und Hooks – müssen im Wurzelverzeichnis des Plugins liegen und nicht innerhalb des Plugin-Metadatenverzeichnisses. Dorthin gehört allein das Plugin-Manifest. Sowohl Ladeprogramme als auch Prüfende verlassen sich darauf, und ein falsch platziertes Bestandteilverzeichnis zeigt sich meist als ein Plugin, das stillschweigend nichts bereitstellt. ## Einen klaren Namen in Kebab-Case wählen und das Frontmatter ausfüllen Das Frontmatter eines Skill-Einstiegspunkts braucht mindestens einen Namen und eine Beschreibung. Eine optionale Liste erlaubter Werkzeuge beschränkt den Skill auf die Werkzeuge, die er wirklich benötigt; sie zu setzen lohnt sich immer dann, wenn der Skill eng zugeschnitten ist. - Der Name steht in kebab-case und bleibt innerhalb der Längengrenze, üblicherweise 64 Zeichen. - Die Beschreibung ist in der dritten Person verfasst und nennt sowohl, was der Skill tut, als auch, wann er zu verwenden ist. - Für Namen ist die Verlaufsform vorzuziehen – ein Name, der mit einem Verb beginnt, wie "analyzing-contracts" oder "processing-pdfs", liest sich besser als ein Name nach dem Muster Substantiv-Akteur wie "contract-analyzer" oder "pdf-processor". - Vage Namen wie helper, utils, tools oder misc sind zu vermeiden; sie passen auf alles und bedeuten nichts. - Reservierte Wörter sind zu vermeiden, darunter Hersteller- und Produktnamen, die die Laufzeitumgebung besonders behandeln kann. ## In der Beschreibung sagen, was der Skill tut und wann er gebraucht wird Ein Skill konkurriert mit hundert anderen um Aufmerksamkeit, und die Beschreibung ist oft der einzige Text, den der Agent liest, wenn er entscheidet, ob er ihn lädt. Eine vage Beschreibung führt dazu, dass der Skill ungenutzt bleibt oder – schlimmer noch – in der falschen Situation auslöst. - Dritte Person: "Analysiert X", nicht "Ich helfe bei X". - Die auslösende Situation nennen, nicht nur das Thema: "Zu verwenden beim Prüfen von Smart Contracts" trägt weit mehr Signal zur Weiterleitung als "Werkzeug für Smart Contracts". - Die Fähigkeit genau benennen: "Erkennt Reentrancy-Schwachstellen" schlägt "Hilft bei der Sicherheit". Die Beschreibung ist so zu schreiben, wie es der Weiterleitungsregel entspricht, die sie tatsächlich ist, und beim erneuten Lesen ist zu fragen, ob ein konkurrierender Skill dieselbe Anfrage für sich entscheiden würde. ## Keine absoluten Pfade fest eintragen und Abhängigkeiten im Skript selbst deklarieren Absolute Pfade dürfen niemals fest im Code stehen. Die Variable für das Basisverzeichnis verwenden, die die Laufzeitumgebung bereitstellt, und auch unter Windows Schrägstriche benutzen, damit derselbe Skill auf jedem Rechner funktioniert. Wenn ein Skill Skripte mitliefert, die Abhängigkeiten haben: 1. Die Abhängigkeiten direkt im Kopf des Skripts deklarieren, im standardmäßigen Block für eingebettete Metadaten dieser Sprache, einschließlich der Mindestversion der Sprache. So kann das ausführende Programm alles auflösen, ohne dass ein eigener Installationsschritt nötig ist. 2. Das Skript über ein ausführendes Programm aufrufen, das diese eingebetteten Metadaten berücksichtigt, damit die Auflösung der Abhängigkeiten automatisch geschieht und nicht bloß eine dokumentierte Voraussetzung bleibt. 3. Im Skriptverzeichnis eine Projektdatei für Entwicklungswerkzeuge wie Prüfprogramme und Formatierer pflegen. 4. Systemweite Abhängigkeiten, die der Paketmanager der Sprache nicht installieren kann – etwa Werkzeuge für PDF und Texterkennung –, in den Workflow-Dateien dokumentieren, mit plattformspezifischen Installationsbefehlen. ## Hooks, die vor jedem Befehl laufen, schnell halten Hooks, die vor jedem Befehl laufen, liegen auf dem heißen Pfad; ihre Kosten fallen daher bei jedem einzelnen Aufruf an. Geschwindigkeit ist hier eine Frage der Korrektheit und keine Annehmlichkeit. - Eine Shell zusammen mit einem leichtgewichtigen JSON-Filter ist einem vollständigen Interpreter vorzuziehen. Der Start von Interpreter und Parser verursacht eine Verzögerung, die die Nutzenden bei jedem Befehl spüren. - Früh und schnell abbrechen: bei Befehlen, die eindeutig nicht passen, sofort und erfolgreich beenden, damit die überwältigende Mehrheit der Aufrufe praktisch nichts kostet. - Reguläre Ausdrücke sind dem vollständigen Zerlegen von Syntaxbäumen vorzuziehen. Seltene Fehlalarme sind hinzunehmen, wenn der Geschwindigkeitsgewinn erheblich ist und der Agent den Befehl einfach umformulieren kann. - Die Formen der Fehlalarme vorwegnehmen: Diagnosebefehle, die lediglich einen Interpreter auffinden, Suchbefehle, die dessen Namen als Suchbegriff nennen, und Dateinamen, die diesen Namen enthalten, dürfen kein Abfangen auslösen. - Diese Abwägungen in der Beschreibung der Änderung dokumentieren, damit Prüfende erkennen, dass die Entscheidungen bewusst und nicht nachlässig getroffen wurden. ## Erklären, wann und warum man nachschlägt, statt ganze Spezifikationen einzufügen Ein Skill sollte Hinweise liefern, über die das Modell nicht ohnehin schon verfügt. Eine ganze Spezifikation in einen Skill zu kopieren verbraucht Kontext und fügt nichts hinzu, was das Modell nicht nachschlagen könnte. - Keine vollständigen Spezifikationen oder API-Referenzen hineinkopieren. Stattdessen vermitteln, wann und wie nachzuschlagen ist. - Das Warum erklären, nicht nur das Was: Abwägungen, Entscheidungskriterien und die Ermessensfragen aufnehmen, die Neulinge falsch beantworten würden. - Antimuster gemeinsam mit dem Grund dokumentieren, warum sie falsch sind, statt als bloße Liste von Verboten. Ein gutes Beispiel für dieses Muster: Ein Skill für ein komplexes binäres Debug-Format bettet die Spezifikation des Formats nicht ein. Er vermittelt, zu welchen Untersuchungswerkzeugen zu greifen ist, wie sie abgefragt werden und welches Werkzeug zu welcher Frage passt. ## Die Strenge an das Risiko der Aufgabe anpassen und sagen, wann der Skill nicht passt Wie starr ein Skill sein sollte, hängt davon ab, wie störanfällig die Aufgabe ist. - Streng bei störanfälligen Aufgaben: Sicherheitsprüfungen, kryptografische Umsetzungen und Kontrollen der Regelkonformität brauchen starre, erzwungene Abläufe Schritt für Schritt. - Flexibel bei veränderlichen Aufgaben: Erkundung von Code, Dokumentation und Umbau des Codes sollten Möglichkeiten anbieten und Raum für eigenes Ermessen lassen. Jeder Skill-Einstiegspunkt muss zwei Abschnitte tragen: einen Abschnitt "Wann zu verwenden", der die konkreten Situationen aufzählt, in denen der Skill greift, und einen Abschnitt "Wann NICHT zu verwenden", der die Fälle benennt, in denen ein anderes Vorgehen besser ist. Der verneinende Abschnitt wird am häufigsten übersprungen, und genau er verhindert, dass der Skill an der falschen Stelle auslöst. Skills für Prüfung und Sicherheit brauchen einen dritten Abschnitt, "Zurückzuweisende Rechtfertigungen", der die üblichen Abkürzungen und Ausreden aufzählt, die zu übersehenen Befunden führen – denn unter Zeitdruck kommt genau das an Rechtfertigungen hoch. ## Die Einstiegsdatei kurz halten und Details nur eine Ebene tief verlinken Den Skill-Einstiegspunkt unter etwa 500 Zeilen halten und den Rest auf ein Referenzverzeichnis und ein Workflow-Verzeichnis aufteilen. Den Schnelleinstieg nach vorn stellen und die Einzelheiten hinter Verweise legen, damit wer nur den üblichen Weg braucht, den Rest nie lädt. Verweise nur eine Ebene tief führen: Der Einstiegspunkt verweist auf Dateien, und diese Dateien verweisen nicht weiter auf zusätzliche Dateien. Die Verzeichnistiefe selbst ist unproblematisch – ein Referenzverzeichnis mit thematischen Unterordnern ist völlig vernünftig. Das Problem ist die verkettete Umleitung, nicht der verschachtelte Ordner. Ein typischer Aufbau besteht aus einem Abschnitt "Schnelleinstieg" mit den Kernanweisungen, einem Abschnitt "Fortgeschrittene Nutzung", der für ausführliche Muster auf ein Referenzdokument verweist, und einem Abschnitt zur API-Referenz, der für die vollständige Dokumentation der Methoden auf ein weiteres verweist. ## Vor der Prüfung automatische und menschliche Checks bestehen und die Version erhöhen Trennen, was die Automatisierung prüft, von dem, was ein Mensch beurteilen muss, und beides abarbeiten, bevor eine Prüfung eröffnet wird. Automatische Prüfungen: gültiges Frontmatter mit Name und Beschreibung; ein Name in kebab-case innerhalb der Längengrenze; jede referenzierte Datei existiert tatsächlich; keine fest verdrahteten Pfade auf das Benutzerverzeichnis; die Ladeprüfung besteht für jede unterstützte Laufzeitumgebung. Prüfungen durch Menschen: Die Beschreibung löst korrekt aus und ist in der dritten Person verfasst; die Abschnitte "Wann zu verwenden" und "Wann NICHT zu verwenden" sind beide vorhanden; die Beispiele sind konkret und zeigen Eingabe und daraus entstehende Ausgabe; das Dokument erklärt das Warum und nicht nur das Was. Dokumentation: Das Plugin hat eine README-Datei; es ist in die Tabelle der README im Wurzelverzeichnis eingetragen; es ist im Marktplatz-Manifest auf Ebene des Repositoriums registriert und nicht im eigenen Metadatenverzeichnis des Plugins; und ein Eintrag zur Zuständigkeit nennt die Betreuenden in der Datei für Code-Eigentümerschaft. Aktualisierungen der Version bei einem bestehenden Plugin: die Version sowohl im Plugin-Manifest als auch im Marktplatz-Eintrag auf Ebene des Repositoriums erhöhen und beide Nummern gleich halten. Viele Client-Programme holen ein Update nur dann, wenn die Versionsnummer steigt; eine vergessene Erhöhung bedeutet also, dass niemand die Korrektur erhält.