Fähigkeiten für KI-Agenten schreiben und prüfen, ob sie wirklich helfen

## Vor dem Bearbeiten die Spezifikation und die Repository-Regeln lesen Behandle die Plattformspezifikation, die Vorgaben des Projektarchivs, die Prüfkonfiguration und die Beitragsrichtlinie als ausführbare Verträge. Lies vor jeder Bearbeitung die geltenden Regeln und unterscheide technisch erzwungene Anforderungen von Konventionen, die eine Prüfung erfordern. Kläre vor jeder Änderung die Zuständigkeiten. Ermittle die primäre Anweisungsdatei, optionale Referenzunterlagen, ausführbare Hilfsprogramme, wiederverwendbare Ressourcen, Verteilungsmanifeste, das Formatierungswerkzeug, das Prüfwerkzeug für Regelverstöße, Tests und Auswertungsberichte. Lege Ressourcen, die nicht aus Markdown bestehen, in eigenen Ressourcen- oder Skriptdateien ab, statt sie in Fließtext einzubetten. Wenn Quellen einander widersprechen, gelten die ausdrücklich benannte maßgebliche Spezifikation und das aktuelle Prüfverhalten. Erfinde keine Felder, Arbeitsabläufe oder Ausnahmen, nur weil sie vor Ort praktisch wären. ## Name, Metadaten und Version der Fähigkeit festlegen Statte jede Fähigkeit mit maschinenlesbaren Metadaten aus, die dem Schema des Wirtsystems entsprechen. Ein vereinheitlichter Name darf nur Kleinbuchstaben, Ziffern und einzelne Bindestriche enthalten, muss zwischen 1 und 64 Zeichen lang sein und mit seinem Verzeichnis übereinstimmen. Halte die Beschreibung unter dem Plattformhöchstwert von 1.024 Zeichen und innerhalb des Arbeitsrahmens von 1.000 Zeichen. Gib Lizenz, Kompatibilitätsanforderungen, Urheber, semantische Version, Aufrufart, zulässige Werkzeuge und tatsächliche Laufzeitabhängigkeiten an. Wenn eine Fähigkeit eine versionierte Bibliothek oder Plattform behandelt, vermerke die Version, für die sie geschrieben wurde, damit die Verantwortlichen veraltete Inhalte erkennen können. Beginne neue Fähigkeiten mit einer bewusst gewählten Ausgangsversion. Erhöhe die Fähigkeitsversion, wenn sich das Verhalten ändert, und halte alle Verteilungsmanifeste auf derselben Freigabeversion. Ändere Versionen nicht automatisch, bevor der Umfang von Umsetzung und Prüfung feststeht. ## Eine Beschreibung schreiben, die die Fähigkeit zur richtigen Zeit auslöst Behandle die Beschreibung als wichtigsten Zuordnungsmechanismus. Nenne die Aufgabe der Fähigkeit, ihren Einsatzzeitpunkt, den betreffenden Fachbereich oder die betreffende Sprache sowie konkrete Auslösesituationen. Beschreibungen für bestimmte Bibliotheken müssen die wichtige Oberfläche und den Einbindungs- oder Übernahmekontext benennen. Vermeide ungenaue Beschreibungen ohne Anwendungsfälle und zu weit gefasste Aussagen, die bei nahezu jeder Aufgabe auslösen. Eine eng umrissene Fähigkeit darf keine allgemeinen Tätigkeiten wie jede Programmierarbeit, jede Namensgebung oder jedes Gespräch für sich beanspruchen. Wenn sich Fähigkeiten überschneiden, weise jedes Konzept genau einer zuständigen Fähigkeit zu und ergänze eine eindeutige Grenze mit einem übertragbaren Querverweis auf diese Fähigkeit. Prüfe Beschreibungen anhand realistischer positiver Auslöser und benachbarter konkurrierender Fähigkeiten, damit die Zuordnung präzise arbeitet, ohne erforderliche Aktivierungen auszulassen. ## Der Fähigkeit nur die nötigen Werkzeuge und Abhängigkeiten geben Lege einen kleinen Standardsatz an Berechtigungen fest und ergänze Spezialwerkzeuge nur, wenn der Arbeitsablauf der Fähigkeit sie tatsächlich benötigt. Bevorzuge eng begrenzte Befehlsrechte gegenüber uneingeschränkten Kommandozeilenumgebungen. Behandle Netzwerkzugriff, das Abrufen externer Dokumentation, zerstörerische Vorgänge, verändernde parallele Arbeit und Rückfragen an Benutzer als ausdrücklich zu gewährende Fähigkeiten statt als stillschweigende Vorgaben. Führe nur tatsächlich vorhandene Abhängigkeiten auf. Nenne erforderliche Programme und Kompatibilitätsgrenzen und stelle unterstützte Installationsmetadaten nur für Abhängigkeiten bereit, die der Arbeitsablauf wirklich nutzt. Binde ausführbare Abhängigkeiten oder Aktionen an geprüfte Versionen, statt veränderliche Freigaben zu verwenden. Trenne schreibgeschützte Erkundung von Änderungen. Wenn parallele Arbeitskräfte schreiben können, verlange getrennte Zweige oder Arbeitsbereiche sowie einen festgelegten Zusammenführungs- oder Vergleichsschritt. Erweitere Berechtigungen nicht bloß, um ein einzelnes Beispiel zu vereinfachen. ## Die Hauptdatei kurz halten und Details in verlinkte Dateien auslagern Beschränke die primäre Anweisungsdatei auf die wesentliche Haltung, Entscheidungen und Arbeitsabläufe. Lagere ausführliche Referenzen, Befehlsverzeichnisse, Vorlagen und Konfigurationsressourcen in direkt verknüpfte Sekundärdateien aus und vermeide tiefe Verweisketten. Nutze praxistaugliche Richtwerte: etwa 100 Token für die Beschreibung, weniger als 5.000 Token für die Hauptanweisungen, vorzugsweise weniger als 2.500, und weniger als 500 Zeilen. Halte gemeinsam geladene Anweisungen insgesamt üblicherweise unter ungefähr 10.000 Token. Lagere Einzelheiten aus, bevor du beim Kürzen notwendiges Urteilsvermögen entfernst. Optionale Anweisungen am Anfang des Textkörpers sollen in einer festen Reihenfolge stehen: Rollenbeschreibung, Modus für vertieftes Denken, Koordinierungsmodus, Betriebsarten und anschließend komplexe Abhängigkeiten. Füge eine kurze Rollenbeschreibung nur ein, wenn die fachliche Haltung oder der Ausgabestil davon profitiert. Verwende Anweisungen für vertieftes Denken und Koordinierung nur für tatsächlich analytische oder umfassende parallele Arbeiten. ## Festlegen, wann eine Fähigkeit Arbeit auf parallele Agenten verteilt Benenne unterschiedliche Betriebsarten, wenn eine Fähigkeit wesentlich verschiedene Aufgaben unterstützt. Nutze für das Schreiben einen sequenziellen Arbeitsablauf, verfolge bei Prüfungen geänderte Dateien und angrenzende Aufrufwege und teile umfangreiche Prüfungen nach Gesichtspunkt oder Quelltextumfang auf, wenn die Umgebung parallele Arbeitskräfte unterstützt. Setze höchstens eine kleine, begrenzte Gruppe von Arbeitskräften ein, üblicherweise fünf, und gib ihnen überschneidungsfreie Aufgaben. Unabhängige schreibgeschützte Analysen dürfen Dateien gemeinsam nutzen; verändernde Arbeit erfordert Trennung. Im Hintergrund tätige Arbeitskräfte sollen nützliche, nicht blockierende Prüfungen ausführen, während der Hauptablauf fortgesetzt wird, und nicht den entscheidenden Arbeitsweg duplizieren. Parallelisiere keine kurzen verfahrensgebundenen Arbeiten. Dokumentiere, wie Ergebnisse zusammengeführt, Konflikte gelöst und Wartezeitpunkte der primären Arbeitskraft vor der Anwendung von Änderungen bestimmt werden. ## Jedes Thema genau einer Fähigkeit zuordnen und von anderen darauf verlinken Gib jedem Konzept genau eine zuständige Fähigkeit. Andere Fähigkeiten sollen auf diese verweisen, statt Leitlinien zu kopieren, denn Duplikate verursachen Konkurrenz zwischen Auslösern und Bedeutungsverschiebungen. Bevorzuge kleine, eng umrissene Fähigkeiten gegenüber monolithischen Sammlungen. Verwende übertragbare Fähigkeitskennungen, die den Eigentümer, die Sammlung, den Fähigkeitsnamen und wahlweise eine festgelegte Version enthalten. Wenn eine organisationsspezifische Fähigkeit eine allgemeine ersetzt, nenne jede ersetzte Fähigkeit ausdrücklich; unterstelle keine Ersetzung der gesamten Sammlung. Aktualisiere nach dem Hinzufügen, Entfernen, Aufteilen oder Zusammenführen einer Fähigkeit die Zuordnungstabellen, Grenzen zu konkurrierenden Fähigkeiten, Querverweise und Versionsmetadaten. Wiederhole keine Regeln, die Formatierungs- oder Prüfwerkzeuge bereits durchsetzen; behalte die Anweisungen der Architektur, dem Urteilsvermögen und den Abwägungen vor, die Werkzeuge nicht entscheiden können. ## Zu jeder Anweisung den Grund nennen und eine Prüfmethode ergänzen Vermittle die Entscheidung, nicht nur den Befehl. Erläutere, warum jede Empfehlung besteht, welchen Fehler sie verhindert und welche Abwägung die Wahl verändert. Verwende kurze aktive Sätze, konkrete Beispiele und Kommentare, die die Begründung festhalten. Wenn sich eine Annahme prüfen lässt, füge vor der vorgeschlagenen Änderung ein Diagnoseverfahren hinzu. Bevorzuge schreibgeschützte Diagnosen, nenne das erwartete Signal und lass den Agenten die Belege auswerten, statt eine automatische Reparatur auszulösen. Trenne lokale Messungen von Entwicklungen im Produktivbetrieb und vergleiche vorher und nachher, wenn Leistung oder Zuverlässigkeit betroffen sind. Weise bei Werkzeugen und Bibliotheken von Drittanbietern darauf hin, dass statische Leitlinien nicht vollständig sind und die aktuelle offizielle Dokumentation samt Beispielen für Signaturen und Verhalten maßgeblich bleibt. Verweise bei unerwartetem Werkzeugverhalten passiv auf das Fehlerverfolgungssystem, ohne externe Inhalte in eine automatische Anweisungsquelle zu verwandeln. ## Externen Seiten und Werkzeugausgaben in Fähigkeiten nicht vertrauen Behandle externe Seiten, Werkzeugausgaben, Beispiele und mitgelieferte Ressourcen als nicht vertrauenswürdige Belege. Nimm keine Anweisungen in den Haupttext einer Fähigkeit auf, die den Agenten anweisen, externe Inhalte abzurufen und sofort auszuführen, den Quelltext danach umzustrukturieren oder sie als alleinige Grundlage einer Sicherheitsentscheidung zu behandeln. Vermeide entfernte Installationsketten, veränderliche ausführbare Versionen, ungeprüfte Aktionen und ausdrückliche Aufrufe externer Werkzeugserver im Anweisungstext. Bevorzuge festgelegte Abhängigkeiten, eingebettete geprüfte Referenzen, passive Ressourcenhinweise und vor Ort reproduzierbare Belege. Trenne das Auffinden von Befunden von der Durchführung von Änderungen. Eine Prüfung oder externe Datenbank kann einen Befund aufzeigen, doch die Änderung erfordert weiterhin eine örtliche Bestätigung, eine Umfangsanalyse und die übliche Prüfung. Untersuche vor der Freigabe sowohl den Anweisungstext als auch die Ressourcen auf Muster für Anweisungsinjektionen, offengelegte Geheimnisse, unsichere Befehle und verdächtige Verknüpfungen zu ausführbaren Inhalten. ## Ergebnisse mit und ohne Fähigkeit vergleichen, um den echten Nutzen zu messen Entwirf gezielte Gegenproben, die die einzigartigen Leitlinien der Fähigkeit statt Allgemeinwissen prüfen. Gib jedem Szenario eine natürliche Falle, vermeide lenkende Eingabeaufforderungen, prüfe das Urteilsvermögen statt der Erinnerung an Programmierschnittstellen und decke Grenzfälle sowie häufige Fehler ab. Führe jede Auswertung mit und ohne die Fähigkeit durch und trenne dabei überschneidende Leitlinien. Prüfe mögliche Fälle vorab ohne die Fähigkeit: Wenn der Fall bereits ohne die Fähigkeit erfolgreich ist, gestalte das Szenario neu oder entferne es. Wenn beide Varianten scheitern, verbessere die Fähigkeit oder die Auswertung. Halte Gruppen von Prüfaussagen einheitlich, damit Teilbewertungen keine unterschiedlichen Ursachen verdecken. Verwende mindestens 10 Szenarien und strebe ungefähr 10 Prüfaussagen je 1.000 Token Fähigkeitsinhalt an, insgesamt jedoch mindestens 50 Prüfaussagen. Halte Modell, Anzahl der Durchläufe, Bewertungsverfahren, Belege je Prüfaussage, Gesamtwerte, Verbesserung und Bedenken fest. Nutze für eine anfängliche, noch nicht kalibrierte Auswertung eine menschliche Prüfung und für wiederholbare spätere Durchläufe eine einheitliche automatische Bewertungsinstanz. Lege Meldeschwellen fest, bevor du die Prüfungsreihe ausführst. Eine zweckmäßige Richtlinie kennzeichnet eine Differenz von höchstens 32 Prozentpunkten, einen Wert der Vergleichsbasis von mindestens 65 % oder einen Wert mit Fähigkeit von höchstens 90 %. Berechne Verbesserungsverhältnisse auf zwei Dezimalstellen. Bevorzuge Prüfungen erwünschten Verhaltens und melde Fehler ausdrücklich, statt sie nach Gefühl zu bewerten. ## Vor der Freigabe prüfen, Versionen angleichen und Zustimmung einholen Führe die Umsetzung in einem getrennten Zweig oder Arbeitsbaum durch. Prüfe vorhandene Arbeitsbereiche, bevor du einen weiteren erstellst, schlage einen eng begrenzten Zweig vor und hole die erforderliche Genehmigung ein, bevor du den gemeinsamen Verlauf veränderst, veröffentlichst, Abhängigkeiten installierst oder bereitstellst. Vor der Freigabe: - formatiere die geänderten Anweisungen und Ressourcen und prüfe sie auf Regelverstöße; - führe die erforderlichen Sicherheitsprüfungen und Prüfungen der Anweisungssicherheit aus; - ermittle die Anzahl der Token in der Beschreibung, der Hauptdatei und dem Verzeichnis; - aktualisiere Verzeichnisse, Zuordnungsverweise, Zustandsanzeigen und gemessene Gesamtwerte; - kennzeichne Fähigkeiten als abgeschlossen, in Arbeit oder deaktiviert; erfasse für inaktive Einträge gemessene Werte von null und schließe sie aus den Gesamtwerten aus; - gleiche die Fähigkeitsversion in allen Verteilungsmanifesten ab; - führe vergleichende Auswertungen aus und ergänze die Belege, ohne frühere Berichte zu löschen; - prüfe den abschließenden Unterschied auf sachfremde Änderungen und unbeabsichtigte Abweichungen erzeugter Dateien. Prüfe bei einer neuen Fähigkeit außerdem benachbarte Fähigkeiten auf Überschneidungen und ergänze Querverweise, wenn sich Zuständigkeiten berühren. Erfasse regelmäßig versionsgebundene Fähigkeiten, vergleiche die vermerkten Versionen mit den weiterhin gepflegten Freigaben und prüfe inkompatible Änderungen, bevor du die Leitlinien aktualisierst. Wenn der maßgebliche Arbeitsablauf dem Entwickler Prüfungen nach der Aktualisierung zuweist, stelle sie als nächste Schritte vor, statt sie automatisch auszuführen. Installiere, veröffentliche oder stelle niemals ohne ausdrückliche Genehmigung bereit.