Agent Skill, das technische Dokumentation in vereinfachtem ASD-STE100-Englisch erzwingt

 (github.com/AminBlg)
2 Punkte von GN⁺ 2 시간 전 | 1 Kommentare | Auf WhatsApp teilen
  • SimpleEnglish ist ein Agent Skill, der LLMs dazu bringt, kurze und eindeutige technische Dokumente nach der kontrollierten Sprache ASD-STE100 zu schreiben, die seit 1983 in der Luft- und Raumfahrt verwendet wird
  • Es wendet 53 Regeln an, darunter Satzlängenbegrenzungen, Aktiv, einfache Zeitformen, Bedingungen vor Anweisungen und genau eine Anweisung pro Satz, und unterstützt Dokumentation, Fehlermeldungen, Runbooks, Incident-Reports, Release Notes, Prompts und die Vorbereitung für Übersetzungen
  • In 96 Auswertungen mit 6 Claude-Modellen und 8 Aufgaben unter zwei Bedingungen gingen die STE-Verstöße pro 100 Wörter im Schnitt um 72,9 % zurück, und bei allen Modellen sank auch die Zahl der Ausgabetokens
  • Es lässt sich ohne Abhängigkeiten in Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI und anderen Umgebungen installieren, die den Agent-Skills-Standard unterstützen; in nicht unterstützten Umgebungen kann es per System-Prompt oder Benutzeranweisung angewendet werden
  • Die Ergebnisse sind keine offizielle ASD-Zertifizierung und gelten nicht für Marketing, Blogposts oder Brand-Tonalität. Der Standardmodus kombiniert Strukturregeln mit Domain-Vokabular, und für die Wortbewertung im strengen Modus wird der offizielle Standard benötigt

Welches Problem das Projekt löst

  • SimpleEnglish ist ein Agent Skill, der übertriebene und vage Sätze von LLMs in technische Sätze umwandelt, die ASD-STE100 Simplified Technical English näherkommen
  • ASD-STE100 ist eine kontrollierte Sprache, die seit 1983 in der Luft- und Raumfahrt eingesetzt wird, damit übermüdete Wartungstechniker Anweisungen nicht falsch verstehen
  • Der Unterschied zwischen dem von Claude erzeugten Original und dem Ergebnis mit Skill liegt in Konkretheit und Ausführbarkeit
    • Der Satz „nutzt eine robuste Architektur für nahtlose Synchronisierung“ wird in eine Aussage umgeschrieben, dass eine Postgres-Tabelle nach S3 kopiert wird und dafür eine Konfigurationsdatei nötig ist
    • Eine allgemeine Meldung über einen Verbindungsfehler wird in einen Passwortfehler für den Benutzer app und die Maßnahme zur Korrektur von DB_PASSWORD umgeschrieben
    • Eine Incident-Formulierung, nach der nicht näher bestimmte Nutzer betroffen gewesen sein könnten, wird in Ausfallzeit, 12 % fehlgeschlagene Anfragen, die Ursache durch ein Deployment und den Zeitpunkt des Rollbacks umgeschrieben
  • Weitere Vergleiche für README, Fehlermeldungen, Incident-Reports und Release Notes stehen in examples/before-after.md

Installation und unterstützte Umgebungen

  • Es funktioniert in rund 25 Harnesses, darunter Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose und OpenCode, die den Agent-Skills-Standard unterstützen
  • Das Projekt besteht aus einem einzigen Ordner, hat keine externen Abhängigkeiten und steht unter der MIT-Lizenz
  • Der Installationsbefehl lautet wie folgt
npx skills add AminBlg/SimpleEnglish
  • Die skills CLI erkennt installierte Agenten und installiert den Skill in das vom Nutzer gewählte Ziel
  • Vor der Installation lässt es sich mit folgendem Befehl testen
npx skills use AminBlg/SimpleEnglish@simple-english
  • In Umgebungen ohne Unterstützung für SKILL.md kann prompts/system-prompt.md als System-Prompt, in AGENTS.md oder in .cursorrules eingefügt werden
    • Es gibt auch eine Version mit etwa 60 Tokens für Umgebungen mit kleinem Token-Budget
    • Es kann verwendet werden, indem technische Dokumentation angefordert oder „rewrite this with simple-english“ als Anweisung gegeben wird

Nutzung in Umgebungen ohne Terminal

  • Claude.ai kostenpflichtige Pläne unterstützen Skills standardmäßig
    • SKILL.md speichern
    • Unter Settings → Capabilities die Code-Ausführung aktivieren
    • Unter Settings → Customize → Skills → Upload die Datei hochladen
    • Wenn der Skill aktiviert ist, wird er auf Anfragen zur technischen Dokumentation angewendet
  • ChatGPT unterstützt keine Skills, daher wird die Prompt-Version verwendet
    • Den Block aus prompts/system-prompt.md in Settings → Personalization → Custom Instructions, in ein Project oder in die Anweisungen eines Custom GPT einfügen
  • In Gemini ein Gem erstellen und denselben Prompt in die Anweisungen einfügen
  • In anderen Chatbots die Prompt-Datei anhängen oder den Inhalt einfügen und anweisen, ihn auf alle Ausgaben anzuwenden

Aus ASD-STE100 übernommene Schreibregeln

  • Der Skill wendet 53 Regeln in 9 Abschnitten, die 1983 entstanden sind, auf technische Dokumentation an
  • Zentrale Regeln sind die folgenden
    • Anweisungen sind auf maximal 20 Wörter begrenzt, erläuternde Sätze auf maximal 25 Wörter
    • Im gesamten Dokument darf ein Wort nur eine Bedeutung haben, damit Mischungen von Ausdrücken wie check, verify, confirm und validate vermieden werden
    • Es werden nur einfache Zeitformen verwendet, sodass statt „has been updated“ direkt geschrieben wird, wer was aktualisiert hat
    • Verbformen auf -ing und daran angehängte Nebensätze werden nicht verwendet
    • Es wird das Aktiv verwendet, um indirekte Formulierungen wie „it should be noted that“ zu entfernen
    • should, would, may und might sind verboten, can, will und must sind jedoch erlaubt
    • Bedingungen stehen vor der Anweisung, damit Nutzer Bedingungen nicht erst spät im Satz lesen
    • Ein Satz enthält nur eine Anweisung
    • Artikel und that bleiben erhalten; selbst kurze Sätze werden nicht telegrammartig gemacht
  • Die vollständigen Umschreibungsregeln einschließlich Softwarebeispielen stehen in SKILL.md
  • Marketing liegt außerhalb des STE-Anwendungsbereichs, daher werden die Marketingtexte im README nicht nach diesen Regeln umgeschrieben, und der Skill gilt nur für Dokumentation

Anwendungsbereich außerhalb technischer Dokumentation

  • use-cases.md enthält Regeln für mehrere Formate
    • Fehlermeldungen werden in der Reihenfolge geschrieben: was passiert ist, warum es passiert ist und was der Nutzer tun muss
    • Runbooks ähneln Wartungshandbüchern, daher wird STE direkt angewendet
    • Incident-Reports verwenden das einfache Präteritum, um unsichere und beschönigende Formulierungen zu entfernen
    • In Release Notes werden Breaking Changes als Warnungen formuliert, die zuerst die Anweisung und danach das Risiko nennen
    • AGENTS.md und System-Prompts werden als Verfahren für Leser behandelt, die keine Rückfragen stellen können, daher ist should verboten, weil Modelle es als optional auslegen können
    • Vor der Übersetzung werden Dokumente in eine Form gebracht, die für Nicht-Muttersprachler leichter lesbar ist und geringere Lokalisierungskosten verursacht
  • Marketingtexte, Blogstil und Brand Writing werden nicht unterstützt; der flache Stil ist eine beabsichtigte Eigenschaft

Benchmark-Ergebnisse

  • In der Auswertung wurden 8 Schreibaufgaben mit 6 Claude-Modellen vor und nach Anwendung des Skills ausgeführt; gemessen wurden insgesamt 96 Generationsergebnisse
  • Die STE-Verstöße pro 100 Wörter gingen im Gesamtschnitt um 72,9 % zurück
    • claude-opus-4-8: von 1,05 auf 0,62, also 41 % Verbesserung
    • claude-opus-4-7: von 2,28 auf 0,42, also 82 % Verbesserung
    • claude-opus-4-6: von 2,24 auf 0,40, also 82 % Verbesserung
    • claude-opus-4-5: von 2,55 auf 0,57, also 78 % Verbesserung
    • claude-sonnet-5: von 2,67 auf 0,53, also 80 % Verbesserung
    • claude-sonnet-4-6: von 2,06 auf 0,52, also 75 % Verbesserung
  • Bei allen Modellen sank die Zahl der Ausgabetokens, und die durchschnittliche Satzlänge ging von 11,2 auf 9,7 Wörter zurück
  • Verwendet wurde ein deterministischer Regex-Linter, der auf beide Bedingungen dieselben Regeln anwendet; die vollständige Methode und ihre Grenzen stehen in evals/results/RESULTS.md
  • Mit einer angemeldeten Claude Code CLI lässt sich das mit folgendem Befehl reproduzieren
python3 evals/run_bench.py

Wie die Regeln geprüft wurden

  • Der Skill wurde testgetrieben anhand der Originalausgabe von Issue 9 aus dem Jahr 2025 entwickelt, nicht anhand von Blog-Zusammenfassungen
  • Der Basis-Agent ohne Skill schrieb Sätze mit 40 Wörtern und erfand sogar Regelnummern, die nicht existieren
    • Ein Ergebnis zitierte die Regel für kurze Sätze als „Rule 3.1“, aber die tatsächliche Rule 3.1 behandelt Verbformen
  • Anders als einige Sekundärquellen erlaubt das offizielle PDF can und will
  • Der Skill wurde so geschrieben, dass protokollierte Fehler des Basissystems einzeln verhindert werden; danach wurde erneut getestet, bis der Agent bestand. Szenarien und Ergebnisse stehen in evals/pressure-tests.md

Anwendungsgrenzen und Status des Standards

  • Die Ergebnisse sind keine STE-zertifizierten Dokumente
    • ASD zertifiziert keine Werkzeuge
    • Der Standardmodus kombiniert Strukturregeln mit dem Domain-Vokabular des Nutzers
    • Der strenge Modus kommt dem Standard näher, doch für Bewertungen auf Wortebene wird der offizielle Standard benötigt
  • Die Ergebnisse werden wie Airbus-Handbücher flach und schwer misszuverstehen geschrieben; ein persönlicher Stil bleibt für andere Einsatzzwecke wie Blogs vorgesehen
  • Anders als die subjektive Anweisung „Schreibe klar“ ist „Schreibe Sätze mit höchstens 20 Wörtern“ eine prüfbare Spezifikation, die ein Agent befolgen kann
  • ASD-STE100 ist ein mehr als 40 Jahre alter Standard, wird aber bis Issue 9 vom Januar 2025 gepflegt und aktualisiert, hat nummerierte Regeln und lässt sich testen

Lizenz und inoffizieller Status

  • Das gesamte Repository steht unter der MIT-Lizenz
  • Für Schulungszwecke werden die Regeln paraphrasiert; die Formulierungen der offiziellen Spezifikation oder Inhalte des Wörterbuchs werden nicht kopiert
  • Das Projekt ist weder mit ASD oder STEMG verbunden noch von ihnen genehmigt; ASD-STE100 ist eine eingetragene Marke von ASD

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2 시간 전
Hacker-News-Kommentare

  • Schon wenn man bei einem Beispiel nur den Satz „Schreibe es in ASD-STE100 Simplified Technical English um“ davorsetzt, kommt ein ausreichend gutes Ergebnis heraus. Ein oder zwei Anweisungssätze sollten reichen, daher frage ich mich, warum man einen riesigen Skill braucht, obwohl ASD-STE100 sehr wahrscheinlich bereits im Trainingsmaterial enthalten ist.

    • Ich verstehe die Erwartung, dass das Modell Wissen aus dem Pretraining selbstständig nutzen sollte, aber in den späteren Trainingsphasen scheint Pretraining-Datenmaterial stark durcheinandergeraten zu sein.

  • Ich habe einen Skill gebaut, der auf von LLMs erzeugte Sätze den The Economist Style Guide anwendet: https://github.com/TAJD/economist-style-guide-plugin
    Er erzeugt Texte mit relativ guter Struktur, die sich leicht redigieren lassen.

  • Es geht um Fehlanwendungen von STE und die begrenzte Einführung: https://en.wikipedia.org/wiki/Simplified_Technical_English#M...

    • Eindrucksvoll fand ich in dem kritischen Material den Satz: „Um korrekt in STE zu schreiben, braucht man sehr gute Englischkenntnisse und ausreichendes Wissen über das jeweilige Thema.“ Das sind schlicht die Voraussetzungen für gutes Schreiben auf Englisch in jedem Bereich, unabhängig davon, ob man STE verwendet.
    • LLMs sind gut im Übersetzen und sollten bei solcher Schreibarbeit daher besonders stark sein. Ich habe es in der vergangenen Woche auf alle Prompts angewendet, und es war wirksam dabei, stilistischen Ballast zu entfernen; übermäßige redundante modifizierende Ausdrücke habe ich überhaupt nicht gesehen.

  • Die Idee gefällt mir, aber beim Skill selbst bin ich nicht überzeugt. Stattdessen habe ich https://vale.sh und verschiedene Linter entdeckt und will sie ausprobieren.

    • STE ist bereits in den Trainingsdaten enthalten, daher ist der Skill redundant und verschmutzt nur das Kontextfenster.
    • Ich frage mich, wie sich Vale bei LLM-Dokumentationsarbeit nutzen lässt.

  • Es scheint zu viel zu tun, und eine einzige Zeile im System-Prompt funktioniert bereits gut genug: „Ausgabe-Tokens sind wertvoll, also antworte knapp und verwende ASD-STE100 Simplified Technical English.“

    • Ich frage mich, ob das in der Praxis dauerhaft gut funktioniert. Selbst wenn ich Regeln zum Benutzerprofil und zu CLAUDE.md hinzufügte, kam das Modell am Ende doch wieder vom Kurs ab und überschüttete Docstrings und Erklärungen mit technischem Fachjargon.
      Wenn das eine Möglichkeit ist, Code-Erklärungen einfacher und schlichter zu machen, probiere ich es gern aus, also macht mir auch das Hoffnung.

  • Schon im README ist ironischerweise der typische LLM-Stil voll da, etwa mit Formulierungen wie „9 Abschnitte und 53 Regeln, die 1983 von Menschen geschrieben wurden, bei denen ein Leser wegen eines einzigen mehrdeutigen Satzes sterben könnte“. Als Schreib-Skill ist das kein besonders vielversprechendes Signal.

    • Ich erkenne das an, aber der Stil des README gefällt mir wirklich nicht. Da stehen Dinge wie: „Dieses README verletzt die Hälfte der Regeln, aber Marketing liegt ausdrücklich außerhalb des STE-Bereichs, und der Skill weiß das und bleibt innerhalb der Dokumentation“ oder „Marketing-Sprache, Blog-Stil und Brand Writing werden abgelehnt; es wird absichtlich flach geschrieben“.
      An jedem Satz hingen außerdem Emojis, die auf HN entfernt wurden.
    • Ich habe eine Zeit lang einen normalen ASD-STE100-Prompt verwendet, und das vereinfachte Englisch des Agenten gefällt mir etwas besser, aber es ändert nicht einmal die Gesamtstruktur des Textes.
      Die Sätze werden kürzer, übertriebene Einleitungen oder leere Abschnittsüberschriften im Foliensatz-Stil werden seltener, und die Qualität wird deutlich besser, aber es ist nicht bahnbrechend und löst das Problem nicht vollständig.
    • Das README wirkt knapp und präzise, und als ich es selbst getestet habe, funktionierte es gut. Es ist besser als viele READMEs, die ich sonst so gesehen habe.

  • Schon das erste Beispiel in Standard Issue 9 ist in sich widersprüchlich. Test ist als Substantiv zugelassen, aber nicht als Verb, und doch lautet der STE-Beispielsatz „Test B is an alternative to test A“.
    Wenn man die STE-spezifischen Regeln nicht kennt, ist das offensichtlich ein mehrdeutiger Satz und damit weit von Klarheit entfernt. Da die offizielle Website den Download hinter einem Google Form versteckt, hier auch ein direkter Link: https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pd...

    • Ich sehe nicht, was daran mehrdeutig sein soll. Um das erste Test als Verb zu lesen, müsste man annehmen, dass in „prüfe, ob B eine Alternative zu A ist“ ein that ausgelassen wurde; dann wäre es vorne ein Verb und hinten ein Substantiv, also wäre die Parallelität gebrochen.
      Außerdem ist eine Deutung als Handlungsanweisung an jemanden an sich schon sehr unwahrscheinlich.

  • Ich frage mich, ob der plötzliche Hype um ASD-STE100 von einem viralen Tweet kommt. Ich habe die Spezifikation von einem Freund bekommen und sie vor ein paar Tagen hochgeladen: https://asd-web-be-prod.azurewebsites.net/media/wunhmi5y/asd...
    Das Kopieren aus dem PDF ist gesperrt, obwohl sich das leicht umgehen lässt; ich frage mich, warum man das so gemacht hat. Um nicht erlaubte Wörter zu blockieren, braucht man einen Linter wie ruff für Englisch, sonst wird der Agent eine einzeilige Anweisung fast sicher vergessen.

  • Ich frage mich, wie solche Anweisungen die Intelligenz oder Denkfähigkeit des Modells beeinflussen. Wenn sie die Ausgabe oder den Denkprozess verändern, könnten sich auch die Fähigkeiten des Modells ändern, besonders wenn es im Training nicht darauf konditioniert wurde, diese Sprache zu verwenden.

    • Das sollte man wohl eher als Post-Processing-Schicht umsetzen, statt es als Anweisung zu geben.

  • In https://youtu.be/uJblcC4lKYw wurden der STE-Skill und andere Skills/Prompts mit George Orwells 6 Schreibregeln verglichen und bewertet; insgesamt lieferte Orwell die besten Ergebnisse.
    Es kommen nicht viele zusätzliche Tokens in den Eingabekontext, und als ich Prosa-Prompts mit und ohne diese Regeln verglich, gefielen mir die Ergebnisse. Vermeide abgenutzte Metaphern, verwende kein langes Wort, wenn ein kurzes reicht, streiche jedes Wort, das man streichen kann, benutze Aktiv statt Passiv, vermeide Fremd-, wissenschaftliche oder Fachwörter, wenn es ein alltagssprachliches Äquivalent gibt, und brich lieber diese Regeln, als einen barbarischen Satz zu schreiben.

    • Vielleicht liegt es daran, dass ich zu viel AI-Text gelesen habe, aber sogar das Sprecher-Skript im Video klingt, als hätte Claude es geschrieben, ohne auch nur eine dieser Regeln anzuwenden.
      Es gibt zu viele Floskeln und typische AI-Formulierungen wie „Um ehrlich zu sein, die Verbesserungen bei der Übersetzung waren real, aber klein“, „Jetzt kommt der ehrliche Teil“, „Dieselbe Krankheit, aber andere Symptome“ und „Diese brutale Zahl von 3 % war kein Naturgesetz, sondern eine Eigenheit von Claude“.