Elites Skills Architect

Verwandelt eine grobe Idee in einen funktionierenden Skill: Entdeckung, Spezifikation, Validierung, Testläufe, menschliche Überprüfung, Beschreibungsoptimierung und Paketierung. Jede Behauptung über einen Skill wird durch ein Skript oder einen bewerteten Durchlauf untermauert, nicht durch einmaliges Lesen und ein gutes Bauchgefühl.

Wo anfangen

Acht Phasen. Finde heraus, wo der Benutzer steht, und starte dort:

Entdeckung: Ein konkretes Problem und die Fakten beschaffen, die für die Spezifikation nötig sind
Probleme erkennen: zu einfach, zu breit, Überschneidungen, Widersprüche
Kategorisieren: Dokumentenerstellung, Workflow-Automatisierung oder MCP-Erweiterung
Erstellen und validieren: Frontmatter, Body, Ordner, Evals, scripts/validate_spec.py
Testen und überprüfen: Evals ausführen, Ausgaben zeigen, bewerten, jede vom Skill durchgesetzte Regel unter Druck testen
Verbessern: Das Muster hinter dem Feedback beheben, nicht den Einzelfall
Beschreibungsoptimierung: Triggertests und scripts/optimize_description.py
Paketieren: scripts/package_skill.py

Passe dein Tempo dem Benutzer an. Jemand, der ohne Aufforderung „MCP-Server“ und „Frontmatter“ sagt, will Geschwindigkeit. Jemand, der sagt „Ich möchte, dass Claude meine Rechnungen macht“, will Schritt für Schritt geführt werden. Verständliches Deutsch, kein Jargon, den sie nicht zuerst verwendet haben.

Alle Skripte benötigen Python 3.9 oder neuer (nur Standardbibliothek) und werden aus dem Skill-Stammverzeichnis ausgeführt:

cd <pfad-zu-elites-skills-architect>
python3 scripts/validate_spec.py <skill-ordner>

Phase 1: Entdeckung

Lies references/discovery-questions.md für den Fragenkatalog und die Nachfragen bei schwachen Antworten. Frage in Zweier- oder Dreierbatches, baue auf den Antworten auf, zitiere niemals die gesamte Liste.

Batch 1, Problem: das eine Ergebnis, das der Skill liefern muss; 5 bis 10 Phrasen, die Benutzer wirklich sagen würden; was der Skill NICHT behandeln darf. Batch 2, Daten: Eingaben und ihr Format; was der Benutzer in der Hand hat, wenn es funktioniert hat; was häufig mit der Eingabe schiefgeht. Batch 3, Workflow: Reihenfolge der Schritte; Abhängigkeiten; Wenn/Dann-Pfade; was mit Schritt 1 und 2 passiert, wenn Schritt 3 fehlschlägt. Batch 4, Integrationen: MCP-Server, APIs, Claude Built-ins, Authentifizierung und Ratelimits. Batch 5, Resilienz: die drei wahrscheinlichsten Laufzeitfehler; die Meldung bei Totalausfall.

Höre auf zu fragen, wenn du alle vier Dinge ohne Raten kannst: die Beschreibung mit echten Triggerphrasen schreiben, jeden Schritt in der richtigen Reihenfolge auflisten, drei Fehlermodi mit ihrer Behandlung benennen und den Skill gut genug erklären, dass ein anderer Entwickler ihn bauen kann.

Wenn der Benutzer das Wissen bereits aufgeschrieben hat (ein Handbuch, API-Dokumentation, ein Styleguide, gespeicherte Webseiten), importiere es, statt es neu zu tippen:

python3 scripts/import_sources.py <dateien-oder-ordner> --skill <skill-ordner> --dry-run

Es wandelt Markdown, Text und gespeichertes HTML in Referenzdateien um, teilt lange Dateien an Überschriften, schreibt ein sources-index.md daneben und gibt die „lies X wenn Y“-Zeilen für den Body aus. Es lädt niemals etwas herunter; speichere die Seiten zuerst.

Phase 2: Probleme erkennen, bevor du baust

Zu einfach: Claude macht es bereits. Ein Skill verdient seinen Platz, wenn es eine Fachlogik oder ein Format gibt, das jedes Mal durchgesetzt werden muss. Frage, ob das der Fall ist.
Zu breit: Mehrere nicht zusammenhängende Workflows. Schlage eine Aufteilung vor; kleine Skills werden zuverlässiger getriggert. Frage, welcher zuerst kommt.
Überschneidung: Ähnlich zu docx, pptx, xlsx, pdf oder Frontend-Design. Sage es und frage, ob erweitert oder etwas anderes gebaut werden soll.
Unmöglich oder unsicher: Sage es deutlich und biete die nächstgelegene machbare Version an.
Widerspruch: „vollautomatisch“ vorher, „frag mich zuerst“ jetzt. Kläre es, bevor du eine Zeile schreibst.

Phase 3: Kategorisieren

Lies references/categories-and-patterns.md. Wähle eine aus:

Kategorie 1, Dokument- und Asset-Erstellung: erstellt Dateien mit Claude Built-ins. Entdeckungsbatches 1 und 2 reichen aus.
Kategorie 2, Workflow-Automatisierung: geordnete Schritte über mehrere Tools, Validierungsgates, teilweiser Fehlschlag oder Rollback. Alle fünf Batches.
Kategorie 3, MCP-Erweiterung: kapselt einen bestehenden MCP-Server mit Urteilsvermögen und Standardwerten. Batches 1, 2 und 4.

Teile dem Benutzer die Kategorie und den Grund mit. Mischformen sind in Ordnung; wähle die primäre für die Beschreibung und das Ordnerlayout.

Phase 4: Erstellen und validieren

Lies references/worked-example.md einmal, bevor du etwas generierst, damit deine Ausgabe diesem Detailgrad entspricht. Verwende references/spec-output-template.md als Grundgerüst.

4a: Frontmatter

Lies references/yaml-rules.md. Was der Validator prüft (Fehler, außer wenn anders vermerkt):

name: Kebab-Case, kein „claude“ oder „anthropic“; stimmt mit dem Ordnernamen überein (Warnung, Fehler mit --portable)
description: 1 bis 1024 Zeichen; Aktionsverb, was es erstellt, wann es verwendet wird, 3 bis 8 Triggerphrasen in doppelten Anführungszeichen, ein negativer Gültigkeitsbereich (die Länge ist ein Fehler; Verb, Phrasen und negativer Bereich sind Warnungen)
keine spitzen Klammern, Tabs, typografischen Anführungszeichen oder anderen Gedankenstriche als der Bindestrich
keine Apostrophe in der Beschreibung (Warnung; einige Upload-Parser haben sie abgelehnt)
Tags als ein String, tags: „a, b, c“, niemals [a, b, c] (Warnung); Metadatenwerte, die wie Zahlen aussehen, in Anführungszeichen setzen, version: „1.0“

Mach die Beschreibung aufdringlich. In unseren Tests bleibt ein Skill von Claude häufiger ungenutzt, als dass er fälschlicherweise ausgewählt wird. Füge daher „triggert auch, wenn jemand … erwähnt“ für die indirekten Anfragen hinzu.

4b: Body

Maximal 500 Zeilen, imperativ, und es erklärt das Warum, nicht nur das Was. Reihenfolge: einzeiliger Zweck; wann verwenden und wann nicht; nummerierte Schritte mit einer Prüfung nach jedem; zwei oder drei Beispiele (Phrase, Aktionen, Ergebnis); Fehlerbehandlung mit Ursache und Reaktion; kurze Best Practices. Verschiebe alles Größere in references/ und verweise mit „lies X wenn Y“ darauf.

4c: Ordner

skill-name/
  SKILL.md
  evals/evals.json        Testfälle, siehe references/schemas.md
  scripts/                deterministische Logik, die das Modell nicht neu ableiten soll
  references/             tiefgehendes Material, das bei Bedarf geladen wird
  assets/                 Vorlagen und Beispiele

Kein README.md innerhalb des Skill-Ordners; die Dokumentation lebt in SKILL.md und references/.

4d: Testplan und Evals

Schreibe 5 oder mehr sollte-triggern-Abfragen und 5 oder mehr sollte-nicht-triggern-Abfragen. Gute Abfragen sind spezifisch und klingen wie eine Person: „ok, kicke den Checkout-Redesign am Montag an, richte den Sprint in Linear ein, 2 Wochen, Frontend-Team“. Die besten negativen teilen sich Wörter mit den positiven, wollen aber etwas anderes: Rat statt Aktion, Berichterstattung statt Erstellung.

Schreibe 2 oder 3 Evals in evals/evals.json (Format in references/schemas.md). Jede Erwartung ist ein überprüfbarer Satz. Zeige sie dem Benutzer, bevor du etwas ausführst.

4e: Validieren

python3 scripts/validate_spec.py <skill-ordner>
python3 scripts/validate_spec.py <skill-ordner> --json     # für Tooling
python3 scripts/validate_spec.py <skill-ordner> --strict   # Warnungen werden auch zu Fehlern
python3 scripts/validate_spec.py <skill-ordner> --portable # für andere Agenten als Claude

Es prüft die Frontmatter-Regeln, die Körperlänge, die obigen Abschnitte, hinterlassene Platzhalter, evals.json, pressure-evals.json (falls vorhanden) und dass jeder scripts/...- oder references/...-Pfad, den der Körper erwähnt, existiert. Behebe jeden Fehler. Zeige niemals eine Spezifikation, die fehlschlägt. --portable fügt die Open Agent Skills Spec-Regeln hinzu (Ordnername muss übereinstimmen, Metadatenwerte müssen Text sein) für Skills, die auch in anderen Agenten laufen werden.

Phase 5: Testen und überprüfen

Eine Sequenz; höre nicht auf halbem Weg auf.

5a: Evals ausführen

Workspace-Layout (vollständiger Baum in references/schemas.md):

<skill-name>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

Schreibe eval_metadata.json in jeden eval-<id>/-Ordner. Führe dann jedes Eval aus:

Mit Subagenten (Claude Code, Cowork): Starte die mit-Skill- und ohne-Skill-Durchläufe für jedes Eval in derselben Runde. Jeder Executor liest den Skill, führt die Aufforderung aus, speichert Dateien in outputs/, schreibt outputs/user_notes.md für alles, worüber er sich unsicher war, und outputs/metrics.json. Speichere timing.json sofort aus der Task-Benachrichtigung; die Zahlen werden nirgendwo anders aufbewahrt.
Ohne Subagenten (claude.ai): Lies SKILL.md und führe jede Aufforderung selbst durch, eine nach der anderen, in denselben Ordnern.

5b: Behauptungen während der Läufe entwerfen

Füge messbare Erwartungen zu eval_metadata.json und evals/evals.json hinzu. Erkläre jede dem Benutzer in einem Satz. Überspringe Behauptungen für Geschmackssache; das beurteilt ein Mensch.

5c: Zeige die Ausgaben, bevor du sie beurteilst

python3 eval-viewer/review.py <skill-name>-workspace/iteration-1 --skill-name <name>

Die Seite öffnet sich im Browser, funktioniert offline und speichert Feedback in feedback.json im Workspace, während der Benutzer tippt. In Cowork oder wenn kein Server möglich ist, füge --static review.html hinzu; Feedback wird dann als Datei heruntergeladen. Öffne zuerst den Viewer und sieh dir dann selbst die Ausgaben an. Ändere den Skill nicht, bevor der Benutzer reagiert hat.

5d: Bewerten und benchmarken (Subagenten)

Bewerte jeden Durchlauf mit agents/grader.md. Verwende, wenn möglich, ein anderes Modell als das, das das Eval ausgeführt hat; ein Modell ist ein schlechter Richter seiner eigenen Arbeit.

Aggregieren:

python3 scripts/aggregate_benchmark.py <skill-name>-workspace/iteration-1 --skill-name <name>

Öffne den Viewer erneut mit --benchmark <iteration>/benchmark.json für den Benchmark-Tab. Für Muster, die die Durchschnitte verbergen, führe agents/analyzer.md Job 2 aus.

5e: Drucktest (Skills, die eine Regel durchsetzen)

Wenn der Wert des Skills in einer Regel besteht, die gelten muss (ein Format, eine Prüfung, ein Genehmigungsschritt), lies references/pressure-tests.md und schreibe 3 bis 5 Szenarien in evals/pressure-evals.json: eine konkrete Situation, zwei oder mehr Druckpunkte (Frist, ein Chef, der Kunde hat darum gebeten, bereits investierte Stunden) und eine erzwungene Wahl, die einen verlockenden Kompromiss beinhaltet.

python3 scripts/pressure_eval.py --skill-path <skill-ordner> \
  --scenarios <skill-ordner>/evals/pressure-evals.json --runs 3 --model <modell-id> \
  --output <skill-name>-workspace/pressure-results.json \
  --report <skill-name>-workspace/pressure-report.md --dry-run

Entferne --dry-run, nachdem der Benutzer die Aufrufanzahl genehmigt hat. Jedes Szenario wird ohne und mit Skill ausgeführt. „Skill hält nicht“ bedeutet, dass der Bericht die Ausreden enthält, die Claude gegeben hat: kontere jede im Skill (benenne sie, erkläre, warum sie falsch ist, sage, was zu tun ist), dann führe erneut aus. „Besteht, aber die Baseline besteht auch“ bedeutet, dass das Szenario zu einfach ist, um etwas zu beweisen.

Phase 6: Verbessern

Finde das Muster hinter dem Feedback und behebe es; drei Testaufforderungen sind nicht die ganze Welt. Lies die Transkripte, nicht nur die Ausgaben, und streiche Anweisungen, die das Modell unnötige Schritte machen ließen. Wenn du IMMER oder NIE in Großbuchstaben schreibst, höre auf und erkläre stattdessen den Grund; ein Modell mit dem Grund kommt weiter als ein Modell mit der Regel. Wenn jeder Durchlauf denselben Helfer geschrieben hat, lege ihn in scripts/ ab und sage es. Hüte dich vor einem Skill, der seine drei Evals besteht und sonst nichts.

Dann: Wende die Änderungen an, führe alle Evals erneut in iteration-2/ aus, öffne den Viewer mit --previous-workspace iteration-1, damit der Benutzer alt und neu nebeneinander sieht, lies das Feedback, wiederhole. Höre auf, wenn der Benutzer zufrieden ist, das Feedback leer ist oder der Fortschritt stagniert.

Für einen rigorosen Alt-gegen-Neu-Vergleich verwende agents/comparator.md (ein blinder A/B-Richter mit einem Vertauschungscheck) und dann agents/analyzer.md Job 1, um das Ergebnis zu erklären. Optional; der Review-Loop reicht normalerweise aus.

Phase 7: Beschreibungsoptimierung

Die Beschreibung ist das, was Claude veranlasst, den Skill auszuwählen. Optimiere sie, sobald der Skill selbst funktioniert.

7a: Trigger-Abfragen

Schreibe 20 Abfragen in evals/trigger-evals.json: etwa die Hälfte sollte triggern, die Hälfte nicht. Beziehe lockere Sprache, Dateinamen, persönlichen Kontext ein. Die wertvollen negativen sind knappe Fehltreffer. Zeige die Liste dem Benutzer und ändere, was er ändern möchte; schlechte Abfragen erzeugen eine schlechte Beschreibung.

7b: Zählen, bevor du ausgibst

python3 scripts/trigger_eval.py --skill-path <skill-ordner> --eval-set <skill-ordner>/evals/trigger-evals.json --dry-run

Jeder Durchlauf ist ein claude -p-Aufruf. Teile dem Benutzer die Anzahl mit und hole ein Ja ein.

7c: Messen

python3 scripts/trigger_eval.py --skill-path <skill-ordner> \
  --eval-set <skill-ordner>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <modell-id> \
  --output <skill-name>-workspace/trigger-results.json --verbose

Das Skript installiert den Skill in einem Wegwerf-Projekt und führt Claude dort mit nur den Einstellungen dieses Projekts aus, sodass nichts das echte Projekt des Benutzers berührt und seine anderen Skills nicht stören können. Lies die Zusammenfassung: Verpasste Abfragen (falsch negative) bedeuten, dass die Beschreibung zu eng ist; fälschlich ausgelöste bedeuten, dass sie zu breit ist. Eine Abfrage, deren Durchläufe alle fehlgeschlagen sind, wird als unbekannt gemeldet, niemals als bestanden.

7d: Optimieren (nur Claude Code)

python3 scripts/optimize_description.py --skill-path <skill-ordner> \
  --eval-set <skill-ordner>/evals/trigger-evals.json --model <modell-id> \
  --max-iterations 4 --results-dir <skill-name>-workspace/description-runs --verbose

Es teilt die Abfragen einmalig in Trainings- und zurückgehaltene Sets auf, evaluiert, bittet Claude um eine bessere Beschreibung (nur basierend auf den Trainingsfehlern), validiert den Kandidaten mit denselben Regeln wie validate_spec.py und wiederholt. Der Gewinner ist die Iteration mit der besten Trainingspunktzahl; bei Gleichstand gewinnt der kürzere Text. Die Punktzahl des zurückgehaltenen Sets wird gemeldet, aber nie zur Auswahl verwendet, sodass sie eine ehrliche Prüfung bleibt: Wenn sie viel niedriger als die Trainingspunktzahl ist, ist die Beschreibung auf die Trainingsabfragen abgestimmt. Es schreibt results.json, report.md und best-description.txt und beendet sich nur mit 0, wenn der Gewinner jede Trainingsabfrage besteht. Auf claude.ai lies die Fehler und schreibe stattdessen von Hand um.

7e: Anwenden

Füge den Gewinner in SKILL.md ein, zeige dem Benutzer Vorher und Nachher mit den Punktzahlen und führe scripts/validate_spec.py erneut aus.

Phase 8: Paketieren

python3 scripts/package_skill.py <skill-ordner> --output dist/
python3 scripts/package_skill.py --inspect dist/<skill-name>.skill

Das Paketieren validiert zuerst und lehnt bei Fehlern ab (und bei Warnungen, sofern nicht --allow-warnings). Das Archiv ist reproduzierbar und gibt eine SHA-256-Prüfsumme aus. Gib dem Benutzer den Pfad oder die Datei selbst.

elitesalgorithm/elites-skills-architect

Was ist elites-skills-architect?

In Ihrer bevorzugten KI fragen

Dokumentation