Eine Fähigkeit zur Schaffung neuer Fähigkeiten und deren iterativer Verbesserung.

Auf einer höheren Ebene läuft der Prozess zum Erstellen einer Fertigkeit wie folgt ab:

• Entscheiden Sie, was die Fertigkeit tun soll und wie sie dies ungefähr tun soll
• Schreiben Sie einen Entwurf des Skills
• Erstellen Sie einige Testaufforderungen und führen Sie „claude-with-access-to-the-skill“ darauf aus
• Helfen Sie dem Benutzer, die Ergebnisse sowohl qualitativ als auch quantitativ zu bewerten
  • Während die Läufe im Hintergrund stattfinden, entwerfen Sie einige quantitative Auswertungen, falls keine vorhanden sind (falls vorhanden, können Sie diese entweder unverändert verwenden oder ändern, wenn Sie das Gefühl haben, dass sich daran etwas ändern muss). Erklären Sie sie dann dem Benutzer (oder erklären Sie die bereits vorhandenen, falls sie bereits vorhanden sind).
  • Verwenden Sie daseval-viewer/generate_review.py-Skript, um dem Benutzer die Ergebnisse zur Ansicht anzuzeigen und ihm auch die Möglichkeit zu geben, die quantitativen Metriken anzuzeigen
• Schreiben Sie die Fertigkeit auf der Grundlage des Feedbacks aus der Bewertung der Ergebnisse durch den Benutzer neu (und auch, wenn aus den quantitativen Benchmarks offensichtliche Mängel hervorgehen).
• Wiederholen Sie den Vorgang, bis Sie zufrieden sind
• Erweitern Sie den Testsatz und versuchen Sie es erneut in größerem Maßstab

Wenn Sie diese Fähigkeit einsetzen, besteht Ihre Aufgabe darin, herauszufinden, wo sich der Benutzer in diesem Prozess befindet, und dann einzugreifen und ihm beim Durchlaufen dieser Phasen zu helfen. Vielleicht sagen sie zum Beispiel: „Ich möchte eine Fertigkeit für X entwickeln.“ Sie können helfen, ihre Bedeutung einzugrenzen, einen Entwurf zu schreiben, die Testfälle zu schreiben, herauszufinden, wie sie ausgewertet werden sollen, alle Eingabeaufforderungen auszuführen und den Vorgang zu wiederholen.

Andererseits haben sie möglicherweise bereits einen Entwurf des Skills. In diesem Fall können Sie direkt zum eval/iterate-Teil der Schleife übergehen.

Natürlich sollten Sie immer flexibel sein und wenn der Benutzer sagt: „Ich muss nicht viele Bewertungen durchführen, stimmen Sie mir einfach zu“, können Sie das stattdessen tun.

Nachdem der Skill fertig ist (aber auch hier ist die Reihenfolge flexibel), können Sie auch den Skill-Beschreibungsverbesserer ausführen, für den wir ein eigenes Skript haben, um das Auslösen des Skills zu optimieren.

Cool? Cool.

Kommunikation mit dem Benutzer

Der Skill-Creator wird wahrscheinlich von Personen verwendet, die über ein breites Spektrum an Kenntnissen im Programmierjargon verfügen. Wenn Sie es noch nicht gehört haben (und wie könnten Sie, es ist ja erst vor Kurzem passiert), gibt es einen Trend, bei dem die Kraft von Claude Klempner dazu inspiriert, ihre Terminals zu öffnen, und Eltern und Großeltern dazu inspiriert, bei Google nach „Wie installiert man NPM“ zu suchen. Andererseits verfügt die Mehrheit der Benutzer wahrscheinlich über ziemliche Computerkenntnisse.

Achten Sie also bitte auf Kontexthinweise, um zu verstehen, wie Sie Ihre Kommunikation formulieren! Im Standardfall, nur um Ihnen eine Vorstellung zu geben:

• „Bewertung“ und „Benchmark“ sind grenzwertig, aber ok
• Für „JSON“ und „Assertion“ möchten Sie ernsthafte Hinweise vom Benutzer sehen, dass er weiß, was diese Dinge sind, bevor er sie verwendet, ohne sie zu erklären

Im Zweifelsfall ist es in Ordnung, die Begriffe kurz zu erläutern. Wenn Sie nicht sicher sind, ob der Benutzer sie verstehen wird, können Sie die Begriffe auch mit einer kurzen Definition verdeutlichen.

---

Eine Fertigkeit erstellen

Absicht erfassen

Beginnen Sie damit, die Absicht des Benutzers zu verstehen. Die aktuelle Konversation enthält möglicherweise bereits einen Workflow, den der Benutzer erfassen möchte (z. B. sagt er „Daraus in eine Fertigkeit umwandeln“). Wenn ja, extrahieren Sie zunächst die Antworten aus dem Gesprächsverlauf – die verwendeten Tools, die Reihenfolge der Schritte, vom Benutzer vorgenommene Korrekturen, beobachtete Ein-/Ausgabeformate. Möglicherweise muss der Benutzer die Lücken füllen und sollte dies bestätigen, bevor er mit dem nächsten Schritt fortfährt.

1. Wozu soll diese Fähigkeit Claude befähigen?
2. Wann sollte diese Fähigkeit ausgelöst werden? (welche Benutzerphrasen/Kontexte)
3. Was ist das erwartete Ausgabeformat?
4. Sollten wir Testfälle einrichten, um zu überprüfen, ob der Skill funktioniert? Fähigkeiten mit objektiv überprüfbaren Ergebnissen (Dateitransformationen, Datenextraktion, Codegenerierung, feste Workflow-Schritte) profitieren von Testfällen. Fähigkeiten mit subjektiven Ergebnissen (Schreibstil, Kunst) benötigen sie oft nicht. Schlagen Sie basierend auf dem Fähigkeitstyp die entsprechende Standardeinstellung vor, überlassen Sie die Entscheidung jedoch dem Benutzer.

Interview und Recherche

Stellen Sie proaktiv Fragen zu Grenzfällen, Eingabe-/Ausgabeformaten, Beispieldateien, Erfolgskriterien und Abhängigkeiten. Warten Sie mit dem Schreiben von Testaufforderungen, bis Sie diesen Teil geklärt haben.

Überprüfen Sie die verfügbaren MCPs – wenn sie für die Recherche nützlich sind (Dokumente durchsuchen, ähnliche Fähigkeiten finden, nach Best Practices suchen), recherchieren Sie parallel über Subagenten, falls verfügbar, andernfalls inline. Bereiten Sie sich auf den Kontext vor, um die Belastung für den Benutzer zu verringern.

Schreiben Sie die SKILL.md

Füllen Sie basierend auf dem Benutzerinterview die folgenden Komponenten aus:

• Name: Skill-ID
• Beschreibung: Wann ausgelöst werden soll, was es bewirkt. Dies ist der primäre Auslösemechanismus – umfassen sowohl die Funktion der Fertigkeit als auch spezifische Kontexte für den Einsatzzeitpunkt. Alle Informationen zur Verwendungszeit finden Sie hier und nicht im Textkörper. Hinweis: Derzeit neigt Claude dazu, Fähigkeiten zu „unterauslösen“ – sie nicht dann einzusetzen, wenn sie nützlich wären. Um dem entgegenzuwirken, gestalten Sie die Fertigkeitsbeschreibungen bitte etwas „aufdringlich“. Anstelle von „So erstellen Sie ein einfaches, schnelles Dashboard zur Anzeige interner Anthropic-Daten.“ könnten Sie also schreiben: „So erstellen Sie ein einfaches, schnelles Dashboard zur Anzeige interner Anthropic-Daten. Stellen Sie sicher, dass Sie diese Fähigkeit verwenden, wenn der Benutzer Dashboards, Datenvisualisierung oder interne Metriken erwähnt oder Unternehmensdaten jeglicher Art anzeigen möchte, auch wenn er nicht ausdrücklich nach einem „Dashboard“ fragt.“
• Kompatibilität: Erforderliche Tools, Abhängigkeiten (optional, selten benötigt)
• der Rest der Fertigkeit:)

Leitfaden zum Fertigkeitenschreiben

Anatomie einer Fähigkeit

skill-name/
 SKILL.md (required)
    YAML frontmatter (name, description required)
    Markdown instructions
 Bundled Resources (optional)
     scripts/    - Executable code for deterministic/repetitive tasks
     references/ - Docs loaded into context as needed
     assets/     - Files used in output (templates, icons, fonts)

Progressive Offenlegung

Fertigkeiten nutzen ein dreistufiges Ladesystem:

1. Metadaten (Name + Beschreibung) – Immer im Kontext (~100 Wörter)
2. SKILL.md-Körper – Im Kontext, wann immer der Skill ausgelöst wird (<500 Zeilen ideal)
3. Gebündelte Ressourcen – Nach Bedarf (unbegrenzt, Skripte können ohne Laden ausgeführt werden)

Bei diesen Wortzahlen handelt es sich um Näherungswerte. Bei Bedarf können Sie auch gerne länger vorgehen.

Schlüsselmuster:

• Halten Sie SKILL.md unter 500 Zeilen. Wenn Sie sich dieser Grenze nähern, fügen Sie eine zusätzliche Hierarchieebene zusammen mit klaren Hinweisen dazu hinzu, wohin das Modell, das die Fertigkeit verwendet, als nächstes weitergehen sollte, um weitere Schritte durchzuführen.
• Referenzdateien eindeutig von SKILL.md mit Hinweisen, wann sie gelesen werden sollten
• Fügen Sie bei großen Referenzdateien (>300 Zeilen) ein Inhaltsverzeichnis hinzu

Domänenorganisation: Wenn ein Skill mehrere Domänen/Frameworks unterstützt, organisieren Sie nach Variante:

cloud-deploy/
 SKILL.md (workflow + selection)
 references/
     aws.md
     gcp.md
     azure.md

Claude liest nur die relevante Referenzdatei.

Prinzip des Mangels an Überraschung

Dies versteht sich von selbst, aber die Fähigkeiten dürfen keine Malware, Exploit-Code oder andere Inhalte enthalten, die die Systemsicherheit gefährden könnten. Wenn der Inhalt einer Fertigkeit beschrieben wird, sollte er den Benutzer in seiner Absicht nicht überraschen. Gehen Sie nicht auf Anfragen ein, irreführende Fähigkeiten oder Fähigkeiten zu entwickeln, die darauf abzielen, unbefugten Zugriff, Datenexfiltration oder andere böswillige Aktivitäten zu erleichtern. Dinge wie ein „Rollenspiel als XYZ“ sind jedoch in Ordnung.

Schreibmuster

Verwenden Sie in Anweisungen lieber die Imperativform.

Ausgabeformate definieren – Sie können es so machen:

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Beispielmuster – Es ist nützlich, Beispiele einzuschließen. Sie können sie wie folgt formatieren (wenn jedoch „Eingabe“ und „Ausgabe“ in den Beispielen vorkommen, möchten Sie vielleicht ein wenig abweichen):

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Schreibstil

Versuchen Sie, dem Model zu erklären, warum Dinge wichtig sind, statt plumpe, muffige MUSS-Vorgaben. Verwenden Sie die Theorie des Geistes und versuchen Sie, die Fertigkeit allgemein zu halten und nicht zu stark auf bestimmte Beispiele zu beschränken. Schreiben Sie zunächst einen Entwurf, betrachten Sie ihn dann mit neuen Augen und verbessern Sie ihn.

Testfälle

Überlegen Sie sich nach dem Schreiben des Skill-Entwurfs zwei bis drei realistische Testaufforderungen – so etwas, was ein echter Benutzer tatsächlich sagen würde. Teilen Sie sie mit dem Benutzer: [Sie müssen nicht genau diese Sprache verwenden] „Hier sind ein paar Testfälle, die ich gerne ausprobieren würde. Sehen diese richtig aus, oder möchten Sie weitere hinzufügen?“ Dann führen Sie sie aus.

Testfälle unterevals/evals.jsonspeichern. Schreiben Sie noch keine Behauptungen, sondern nur die Aufforderungen. Im nächsten Schritt entwerfen Sie Behauptungen, während die Läufe ausgeführt werden.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

Das vollständige Schema finden Sie unterreferences/schemas.md(einschließlich des Feldsassertions, das Sie später hinzufügen werden).

Testfälle ausführen und auswerten

Bei diesem Abschnitt handelt es sich um eine fortlaufende Abfolge – hören Sie nicht mittendrin auf. Verwenden Sie KEINEN/skill-testoder eine andere Testfähigkeit.

Fügen Sie die Ergebnisse in<skill-name>-workspace/als gleichgeordnetes Element zum Skill-Verzeichnis ein. Organisieren Sie die Ergebnisse innerhalb des Arbeitsbereichs nach Iteration (iteration-1/,iteration-2/usw.), und darin erhält jeder Testfall ein Verzeichnis (eval-0/,eval-1/usw.). Erstellen Sie dies nicht alles im Voraus, sondern erstellen Sie einfach nach und nach Verzeichnisse.

Schritt 1: Spawnen Sie alle Läufe (mit Fertigkeit UND Grundlinie) in derselben Runde

Für jeden Testfall werden in derselben Runde zwei Subagenten erzeugt – einer mit der Fertigkeit, einer ohne. Das ist wichtig: Spawnen Sie nicht zuerst die Läufe mit Fertigkeit und kehren Sie dann später für die Grundlinien zurück. Starten Sie alles auf einmal, damit alles ungefähr zur gleichen Zeit fertig ist.

Mit-Skill-Lauf:

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about - e.g., "the .docx file", "the final CSV">

Baseline-Ausführung (gleiche Eingabeaufforderung, aber die Baseline hängt vom Kontext ab):

• Eine neue Fertigkeit erstellen: überhaupt keine Fertigkeit. Gleiche Eingabeaufforderung, kein Skill-Pfad, Speichern unterwithout_skill/outputs/.
• Verbesserung einer vorhandenen Fertigkeit: die alte Version. Erstellen Sie vor der Bearbeitung einen Snapshot des Skills (cp -r <skill-path> <workspace>/skill-snapshot/) und richten Sie dann den Baseline-Subagenten auf den Snapshot. Speichern Sie unterold_skill/outputs/.

Schreiben Sie für jeden Testfall eineval_metadata.json(Assertions können vorerst leer sein). Geben Sie jeder Bewertung einen beschreibenden Namen basierend auf dem, was getestet wird – nicht nur „eval-0“. Verwenden Sie diesen Namen auch für das Verzeichnis. Wenn diese Iteration neue oder geänderte Evaluierungsaufforderungen verwendet, erstellen Sie diese Dateien für jedes neue Evaluierungsverzeichnis. Gehen Sie nicht davon aus, dass sie aus früheren Iterationen übernommen werden.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

Schritt 2: Erstellen Sie während der Ausführung Aussagenentwürfe

Warten Sie nicht nur, bis die Läufe zu Ende sind – Sie können diese Zeit produktiv nutzen. Entwerfen Sie quantitative Aussagen für jeden Testfall und erläutern Sie diese dem Benutzer. Wenn inevals/evals.jsonbereits Behauptungen vorhanden sind, überprüfen Sie diese und erläutern Sie, was sie prüfen.

Gute Behauptungen sind objektiv überprüfbar und haben beschreibende Namen – sie sollten im Benchmark-Viewer klar lesbar sein, damit jemand, der sich die Ergebnisse ansieht, sofort versteht, was jede einzelne überprüft. Subjektive Fähigkeiten (Schreibstil, Designqualität) werden qualitativ besser bewertet – zwingen Sie keine Behauptungen zu Dingen auf, die menschliches Urteilsvermögen erfordern.

Aktualisieren Sie die Dateieneval_metadata.jsonundevals/evals.jsonmit den einmal erstellten Behauptungen. Erklären Sie dem Benutzer außerdem, was er im Viewer sieht – sowohl die qualitativen Ergebnisse als auch den quantitativen Benchmark.

Schritt 3: Erfassen Sie nach Abschluss der Läufe die Zeitdaten

Wenn jede Subagentenaufgabe abgeschlossen ist, erhalten Sie eine Benachrichtigung mittotal_tokensundduration_ms. Speichern Sie diese Daten sofort intiming.jsonim Laufverzeichnis:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

Dies ist die einzige Möglichkeit, diese Daten zu erfassen – sie kommen durch die Aufgabenbenachrichtigung und werden nicht an anderer Stelle gespeichert. Verarbeiten Sie jede Benachrichtigung, sobald sie eintrifft, anstatt zu versuchen, sie zu stapeln.

Schritt 4: Bewerten, aggregieren und starten Sie den Viewer

Sobald alle Läufe abgeschlossen sind:

1. Bewerten Sie jeden Lauf – Erzeugen Sie einen Grader-Subagenten (oder eine Inline-Bewertung), deragents/grader.mdliest und jede Behauptung anhand der Ausgaben auswertet. Speichern Sie die Ergebnisse in jedem Laufverzeichnis untergrading.json. Das Erwartungsarray grading.json muss die Feldertext,passedundevidenceverwenden (nichtname/met/detailsoder andere Varianten) – der Viewer ist auf diese genauen Feldnamen angewiesen. Für Behauptungen, die programmgesteuert überprüft werden können, schreiben Sie ein Skript und führen Sie es aus, anstatt es nur im Auge zu behalten – Skripte sind schneller, zuverlässiger und können über Iterationen hinweg wiederverwendet werden.

2. In Benchmark aggregieren – Führen Sie das Aggregationsskript aus dem Skill-Creator-Verzeichnis aus:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   Dies erzeugtbenchmark.jsonundbenchmark.mdmit pass_rate, Zeit und Token für jede Konfiguration, mit mittlerem stddev und dem Delta. Wenn Sie benchmark.json manuell generieren, finden Sie unterreferences/schemas.mddas genaue Schema, das der Betrachter erwartet. Platzieren Sie jede with_skill-Version vor ihrem Basis-Gegenstück.

3. Machen Sie einen Analystentest – lesen Sie die Benchmark-Daten und entdecken Sie Muster, die die aggregierten Statistiken möglicherweise verbergen. Sehen Sie sichagents/analyzer.md(Abschnitt „Analysieren von Benchmark-Ergebnissen“) an, um zu erfahren, worauf Sie achten müssen – Dinge wie Behauptungen, die unabhängig vom Können immer erfolgreich sind (nicht diskriminierend), Auswertungen mit hoher Varianz (möglicherweise unzuverlässig) und Zeit-/Token-Kompromisse.

4. Starten Sie den Viewer mit qualitativen Ausgaben und quantitativen Daten:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   Übergeben Sie für Iteration 2+ auch--previous-workspace <workspace>/iteration-<N-1>.

   Cowork-/Headless-Umgebungen: Wennwebbrowser.open()nicht verfügbar ist oder die Umgebung keine Anzeige hat, verwenden Sie--static <output_path>, um eine eigenständige HTML-Datei zu schreiben, anstatt einen Server zu starten. Feedback wird alsfeedback.json-Datei heruntergeladen, wenn der Benutzer auf „Alle Bewertungen senden“ klickt. Kopieren Siefeedback.jsonnach dem Download in das Workspace-Verzeichnis, damit es von der nächsten Iteration übernommen werden kann.

Hinweis: Bitte verwenden Sie „generate_review.py“, um den Viewer zu erstellen. Es ist nicht erforderlich, benutzerdefiniertes HTML zu schreiben.

5. Sagen Sie dem Benutzer etwas wie: „Ich habe die Ergebnisse in Ihrem Browser geöffnet. Es gibt zwei Registerkarten – „Ausgaben“ ermöglicht es Ihnen, durch jeden Testfall zu klicken und Feedback zu hinterlassen, „Benchmark“ zeigt den quantitativen Vergleich. Wenn Sie fertig sind, kommen Sie hierher zurück und lassen Sie es mich wissen.“

Was der Benutzer im Viewer sieht

Auf der Registerkarte „Ausgaben“ wird jeweils ein Testfall angezeigt:

• Eingabeaufforderung: die Aufgabe, die gegeben wurde
• Ausgabe: Die vom Skill erstellten Dateien, soweit möglich inline gerendert
• Vorherige Ausgabe (Iteration 2+): reduzierter Abschnitt mit der Ausgabe der letzten Iteration
• Formelle Noten (falls eine Bewertung durchgeführt wurde): minimierter Abschnitt, der die Behauptung „bestanden/nicht bestanden“ zeigt
• Feedback: ein Textfeld, das während der Eingabe automatisch speichert
• Vorheriges Feedback (Iteration 2+): ihre Kommentare vom letzten Mal, angezeigt unter dem Textfeld

Auf der Registerkarte „Benchmark“ wird die Statistikzusammenfassung angezeigt: Erfolgsquoten, Timing und Token-Nutzung für jede Konfiguration, mit Aufschlüsselungen pro Bewertung und Analystenbeobachtungen.

Die Navigation erfolgt über die Schaltflächen „Vorher/Weiter“ oder die Pfeiltasten. Wenn Sie fertig sind, klicken Sie auf „Alle Bewertungen senden“, wodurch alle Rückmeldungen infeedback.jsongespeichert werden.

Schritt 5: Lesen Sie das Feedback

Wenn der Benutzer Ihnen mitteilt, dass er fertig ist, lesen Siefeedback.json:

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

Leeres Feedback bedeutet, dass der Benutzer dachte, es sei in Ordnung. Konzentrieren Sie Ihre Verbesserungen auf die Testfälle, bei denen der Benutzer spezifische Beschwerden hatte.

Beenden Sie den Viewer-Server, wenn Sie damit fertig sind:

kill $VIEWER_PID 2>/dev/null

---

Verbesserung der Fähigkeit

Dies ist das Herzstück der Schleife. Sie haben die Testfälle ausgeführt, der Benutzer hat die Ergebnisse überprüft und jetzt müssen Sie den Skill basierend auf seinem Feedback verbessern.

Wie man über Verbesserungen nachdenkt

1. Verallgemeinern Sie das Feedback. Das Gesamtbild, das hier passiert, ist, dass wir versuchen, Fähigkeiten zu schaffen, die millionenfach (vielleicht im wahrsten Sinne des Wortes, vielleicht sogar noch öfter, wer weiß) bei vielen verschiedenen Eingabeaufforderungen eingesetzt werden können. Hier wiederholen Sie und der Benutzer immer wieder nur einige wenige Beispiele, weil es hilft, schneller voranzukommen. Der Benutzer kennt diese Beispiele in- und auswendig und kann neue Ergebnisse schnell beurteilen. Aber wenn die Fähigkeit, die Sie und der Benutzer gemeinsam entwickeln, nur für diese Beispiele funktioniert, ist sie nutzlos. Anstatt fummelige, übertriebene Änderungen oder erdrückend einschränkende MUSS-Vorgaben einzuführen, könnten Sie bei hartnäckigen Problemen versuchen, andere Metaphern zu verwenden oder andere Arbeitsmuster zu empfehlen. Es ist relativ günstig, es auszuprobieren, und vielleicht landen Sie auf etwas Großartigem.

2. Halten Sie die Eingabeaufforderung schlank. Entfernen Sie Dinge, die nicht ihr Gewicht ziehen. Lesen Sie unbedingt die Transkripte und nicht nur die endgültigen Ergebnisse. Wenn es den Anschein hat, dass der Skill dazu führt, dass das Modell viel Zeit mit unproduktiven Dingen verschwendet, können Sie versuchen, die Teile des Skills zu entfernen, die dazu führen, dass das Modell dies tut, und sehen, was passiert.

3. Erklären Sie das Warum. Versuchen Sie, das Warum hinter allem, was Sie vom Modell verlangen, zu erklären. Die heutigen LLMs sind smart. Sie verfügen über eine gute theoretische Denkweise und können mit einem guten Geschirr über bloße Anweisungen hinausgehen und wirklich Dinge bewirken. Auch wenn das Feedback des Benutzers knapp oder frustrierend ist, versuchen Sie, die Aufgabe tatsächlich zu verstehen und zu verstehen, warum der Benutzer schreibt, was er geschrieben hat und was er tatsächlich geschrieben hat, und übertragen Sie dieses Verständnis dann in die Anweisungen. Wenn Sie feststellen, dass Sie IMMER oder NIE in Großbuchstaben schreiben oder sehr starre Strukturen verwenden, ist das eine gelbe Flagge – wenn möglich, formulieren Sie die Argumentation neu und erläutern Sie sie, damit das Modell versteht, warum das, wonach Sie fragen, wichtig ist. Das ist ein humanerer, wirkungsvollerer und effektiverer Ansatz.

4. Achten Sie auf wiederholte Arbeit in Testfällen. Lesen Sie die Transkripte der Testläufe und achten Sie darauf, ob die Subagenten alle unabhängig voneinander ähnliche Hilfsskripte geschrieben haben oder den gleichen mehrstufigen Ansatz für etwas gewählt haben. Wenn alle drei Testfälle dazu führten, dass der Subagent eincreate_docx.pyoder einbuild_chart.pyschrieb, ist das ein starkes Signal, dass der Skill dieses Skript bündeln sollte. Schreiben Sie es einmal, fügen Sie es inscripts/ein und weisen Sie den Skill an, es zu verwenden. Dies erspart jedem zukünftigen Aufruf, das Rad neu zu erfinden.

Diese Aufgabe ist ziemlich wichtig (wir versuchen hier, einen wirtschaftlichen Wert in Milliardenhöhe pro Jahr zu schaffen!) und Ihre Bedenkzeit ist nicht das Hindernis; Nehmen Sie sich Zeit und denken Sie gründlich darüber nach. Ich würde vorschlagen, einen Überarbeitungsentwurf zu schreiben, ihn dann erneut zu prüfen und Verbesserungen vorzunehmen. Geben Sie wirklich Ihr Bestes, um in den Kopf des Benutzers einzudringen und zu verstehen, was er will und braucht.

Die Iterationsschleife

Nach Verbesserung der Fertigkeit:

1. Wenden Sie Ihre Verbesserungen auf die Fertigkeit an
2. Führen Sie alle Testfälle erneut in einem neueniteration-<N+1>/-Verzeichnis aus, einschließlich Baseline-Läufen. Wenn Sie einen neuen Skill erstellen, ist die Basislinie immerwithout_skill(kein Skill) – das bleibt über alle Iterationen hinweg gleich. Wenn Sie eine vorhandene Fertigkeit verbessern, entscheiden Sie nach Ihrem Ermessen, was als Basis sinnvoll ist: die Originalversion, die der Benutzer bereitgestellt hat, oder die vorherige Iteration.
3. Starten Sie den Prüfer, wobei--previous-workspaceauf die vorherige Iteration zeigt
4. Warten Sie, bis der Benutzer überprüft und Ihnen mitteilt, dass er fertig ist
5. Lesen Sie das neue Feedback, verbessern Sie es erneut und wiederholen Sie den Vorgang

Machen Sie weiter, bis:

• Der Benutzer sagt, er sei zufrieden
• Das Feedback ist komplett leer (alles sieht gut aus)
• Sie machen keine nennenswerten Fortschritte

---

Fortgeschritten: Blindvergleich

Für Situationen, in denen Sie einen genaueren Vergleich zwischen zwei Versionen einer Fertigkeit wünschen (z. B. wenn der Benutzer fragt: „Ist die neue Version tatsächlich besser?“), gibt es ein Blindvergleichssystem. Weitere Informationen finden Sie unteragents/comparator.mdundagents/analyzer.md. Die Grundidee besteht darin, einem unabhängigen Agenten zwei Ausgaben zu geben, ohne ihm zu sagen, welche welche sind, und ihn die Qualität beurteilen zu lassen. Analysieren Sie dann, warum der Gewinner gewonnen hat.

Dies ist optional, erfordert Subagenten und wird von den meisten Benutzern nicht benötigt. Die menschliche Überprüfungsschleife reicht normalerweise aus.

---

Beschreibung Optimierung

Das Beschreibungsfeld in SKILL.md frontmatter ist der primäre Mechanismus, der bestimmt, ob Claude einen Skill aufruft. Bieten Sie nach dem Erstellen oder Verbessern einer Fertigkeit an, die Beschreibung zu optimieren, um eine bessere Auslösegenauigkeit zu erzielen.

Schritt 1: Trigger-Bewertungsabfragen generieren

Erstellen Sie 20 Auswertungsabfragen – eine Mischung aus „Sollte auslösen“ und „Sollte nicht auslösen“. Als JSON speichern:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

Die Abfragen müssen realistisch sein und etwas sein, was ein Claude Code- oder Claude.ai-Benutzer tatsächlich eingeben würde. Keine abstrakten Anfragen, sondern Anfragen, die konkret und konkret sind und viele Details enthalten. Zum Beispiel Dateipfade, persönlicher Kontext zum Job oder zur Situation des Benutzers, Spaltennamen und -werte, Firmennamen, URLs. Ein bisschen Hintergrundgeschichte. Einige sind möglicherweise in Kleinbuchstaben geschrieben oder enthalten Abkürzungen, Tippfehler oder beiläufige Sprache. Verwenden Sie eine Mischung aus unterschiedlichen Längen und konzentrieren Sie sich auf Randfälle, anstatt sie klar abzugrenzen (der Benutzer erhält die Möglichkeit, sie abzuzeichnen).

Schlecht:"Format this data","Extract text from PDF","Create a chart"

Gut:"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

Denken Sie bei den Abfragen, die auslösen sollten (8–10), an die Abdeckung. Sie möchten unterschiedliche Formulierungen für die gleiche Absicht – einige formell, andere locker. Schließen Sie Fälle ein, in denen der Benutzer die Fertigkeit oder den Dateityp nicht explizit benennt, diese aber eindeutig benötigt. Fügen Sie einige ungewöhnliche Anwendungsfälle und Fälle hinzu, in denen diese Fähigkeit mit einer anderen konkurriert, aber gewinnen sollte.

Bei den sollten nicht auslösenden Abfragen (8–10) sind die Beinahe-Fehler am wertvollsten – Abfragen, die Schlüsselwörter oder Konzepte mit dem Skill teilen, aber tatsächlich etwas anderes benötigen. Denken Sie an angrenzende Domänen, mehrdeutige Formulierungen, bei denen eine naive Schlüsselwortübereinstimmung ausgelöst werden würde, aber nicht sollte, und Fälle, in denen die Abfrage etwas berührt, was der Skill tut, aber in einem Kontext, in dem ein anderes Tool besser geeignet ist.

Das Wichtigste, was Sie vermeiden sollten: Machen Sie Abfragen, die nicht auslösen sollen, nicht offensichtlich irrelevant. „Eine Fibonacci-Funktion schreiben“ als negativer Test für eine PDF-Fähigkeit ist zu einfach – es testet nichts. Die negativen Fälle dürften wirklich knifflig sein.

Schritt 2: Besprechen Sie es mit dem Benutzer

Präsentieren Sie den Evaluierungssatz dem Benutzer zur Überprüfung mithilfe der HTML-Vorlage:

1. Lesen Sie die Vorlage vonassets/eval_review.html
2. Ersetzen Sie die Platzhalter:
   • __EVAL_DATA_PLACEHOLDER__-> das JSON-Array der Auswertungselemente (ohne Anführungszeichen – es handelt sich um eine JS-Variablenzuweisung)
   • __SKILL_NAME_PLACEHOLDER__-> der Name des Skills
   • __SKILL_DESCRIPTION_PLACEHOLDER__-> die aktuelle Beschreibung des Skills
3. Schreiben Sie in eine temporäre Datei (z. B./tmp/eval_review_<skill-name>.html) und öffnen Sie sie:open /tmp/eval_review_<skill-name>.html
4. Der Benutzer kann Abfragen bearbeiten, „Sollte auslösen“ umschalten, Einträge hinzufügen/entfernen und dann auf „Auswertungssatz exportieren“ klicken.
5. Die Datei wird auf~/Downloads/eval_set.jsonheruntergeladen. Überprüfen Sie den Download-Ordner auf die neueste Version, falls mehrere vorhanden sind (z. B.eval_set (1).json).

Dieser Schritt ist wichtig – schlechte Auswertungsabfragen führen zu schlechten Beschreibungen.

Schritt 3: Führen Sie die Optimierungsschleife aus

Sagen Sie dem Benutzer: „Das wird einige Zeit dauern – ich werde die Optimierungsschleife im Hintergrund ausführen und sie regelmäßig überprüfen.“

Speichern Sie den Evaluierungssatz im Arbeitsbereich und führen Sie ihn dann im Hintergrund aus:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

Verwenden Sie die Modell-ID aus Ihrer Systemeingabeaufforderung (diejenige, die die aktuelle Sitzung antreibt), damit der auslösende Test mit dem übereinstimmt, was der Benutzer tatsächlich erlebt.

Verfolgen Sie während der Ausführung regelmäßig die Ausgabe, um dem Benutzer Aktualisierungen darüber zu geben, in welcher Iteration er sich befindet und wie die Ergebnisse aussehen.

Dadurch wird die gesamte Optimierungsschleife automatisch abgewickelt. Es teilt den Evaluierungssatz in 60 % Zug und 40 % angehaltener Test auf, wertet die aktuelle Beschreibung aus (wobei jede Abfrage dreimal ausgeführt wird, um eine zuverlässige Auslöserrate zu erhalten) und ruft dann Claude auf, um basierend auf den Fehlern Verbesserungen vorzuschlagen. Jede neue Beschreibung wird sowohl im Zug als auch im Test neu bewertet und bis zu fünfmal wiederholt. Wenn es fertig ist, öffnet es einen HTML-Bericht im Browser, der die Ergebnisse pro Iteration anzeigt, und gibt JSON mitbest_descriptionzurück – ausgewählt nach Testergebnis und nicht nach Trainingsergebnis, um eine Überanpassung zu vermeiden.

So funktioniert das Auslösen von Fertigkeiten

Das Verständnis des Auslösemechanismus hilft beim Entwerfen besserer Auswertungsabfragen. Fertigkeiten erscheinen in Claudesavailable_skills-Liste mit ihrem Namen und ihrer Beschreibung, und Claude entscheidet anhand dieser Beschreibung, ob er eine Fertigkeit konsultieren möchte. Wichtig zu wissen ist, dass Claude Fertigkeiten nur für Aufgaben heranzieht, die er alleine nicht ohne weiteres bewältigen kann – einfache, einstufige Abfragen wie „Lesen Sie dieses PDF“ lösen möglicherweise keine Fertigkeit aus, selbst wenn die Beschreibung perfekt übereinstimmt, da Claude sie direkt mit einfachen Werkzeugen bearbeiten kann. Komplexe, mehrstufige oder spezialisierte Abfragen lösen bei passender Beschreibung zuverlässig Skills aus.

Das bedeutet, dass Ihre Bewertungsanfragen substanziell genug sein sollten, damit Claude tatsächlich von der Befragung einer Fertigkeit profitieren würde. Einfache Abfragen wie „Datei X lesen“ sind schlechte Testfälle – sie lösen unabhängig von der Beschreibungsqualität keine Fähigkeiten aus.

Schritt 4: Übernehmen Sie das Ergebnis

Nehmen Siebest_descriptionaus der JSON-Ausgabe und aktualisieren Sie die SKILL.md-Frontmatter des Skills. Zeigen Sie dem Benutzer Vorher/Nachher und melden Sie die Ergebnisse.

---

Verpacken und präsentieren (nur wenn daspresent_files-Tool verfügbar ist)

Prüfen Sie, ob Sie Zugriff auf das Toolpresent_fileshaben. Wenn nicht, überspringen Sie diesen Schritt. Wenn Sie dies tun, verpacken Sie den Skill und präsentieren Sie die.skill-Datei dem Benutzer:

python -m scripts.package_skill <path/to/skill-folder>

Leiten Sie den Benutzer nach dem Packen zum resultierenden.skill-Dateipfad, damit er ihn installieren kann.

---

Claude.ai-spezifische Anweisungen

In Claude.ai ist der Kernworkflow derselbe (Entwurf -> Test -> Überprüfung -> Verbessern -> Wiederholen), aber da Claude.ai keine Subagenten hat, ändern sich einige Mechanismen. Folgendes müssen Sie anpassen:

Testfälle ausführen: Keine Subagenten bedeuten keine parallele Ausführung. Lesen Sie für jeden Testfall die Datei SKILL.md des Skills und befolgen Sie dann die Anweisungen, um die Testaufforderung selbst durchzuführen. Machen Sie sie einzeln. Dies ist weniger streng als bei unabhängigen Subagenten (Sie haben den Skill geschrieben und führen ihn auch aus, sodass Sie über den vollständigen Kontext verfügen), aber es ist eine nützliche Plausibilitätsprüfung – und der Schritt der menschlichen Überprüfung entschädigt. Überspringen Sie die Grundlinienläufe – nutzen Sie einfach die Fertigkeit, um die Aufgabe wie gewünscht abzuschließen.

Überprüfung der Ergebnisse: Wenn Sie einen Browser nicht öffnen können (z. B. die VM von Claude.ai hat keine Anzeige oder Sie befinden sich auf einem Remote-Server), überspringen Sie den Browser-Überprüfer vollständig. Präsentieren Sie Ergebnisse stattdessen direkt im Gespräch. Zeigen Sie für jeden Testfall die Eingabeaufforderung und die Ausgabe an. Wenn es sich bei der Ausgabe um eine Datei handelt, die der Benutzer sehen muss (z. B. eine DOCX- oder XLSX-Datei), speichern Sie sie im Dateisystem und teilen Sie ihm mit, wo sie sich befindet, damit er sie herunterladen und überprüfen kann. Bitten Sie inline um Feedback: „Wie sieht das aus? Gibt es etwas, das Sie ändern würden?“

Benchmarking: Überspringen Sie das quantitative Benchmarking – es basiert auf Basisvergleichen, die ohne Subagenten nicht aussagekräftig sind. Konzentrieren Sie sich auf qualitatives Feedback des Benutzers.

Die Iterationsschleife: Das Gleiche wie zuvor – die Fähigkeit verbessern, die Testfälle erneut ausführen, um Feedback bitten – nur ohne den Browser-Prüfer in der Mitte. Sie können Ergebnisse weiterhin in Iterationsverzeichnissen im Dateisystem organisieren, sofern Sie eines haben.

Beschreibungsoptimierung: Für diesen Abschnitt ist das CLI-Toolclaude(insbesondereclaude -p) erforderlich, das nur in Claude Code verfügbar ist. Überspringen Sie es, wenn Sie auf Claude.ai sind.

Blindvergleich: Erfordert Subagenten. Überspringen Sie es.

Paketierung: Daspackage_skill.py-Skript funktioniert überall mit Python und einem Dateisystem. Auf Claude.ai können Sie es ausführen und der Benutzer kann die resultierende.skill-Datei herunterladen.

Aktualisieren eines vorhandenen Skills: Der Benutzer bittet Sie möglicherweise, einen vorhandenen Skill zu aktualisieren und keinen neuen zu erstellen. In diesem Fall:

• Behalten Sie den ursprünglichen Namen bei. Beachten Sie den Verzeichnisnamen des Skills und dasname-Frontmatter-Feld – verwenden Sie sie unverändert. Wenn der installierte Skill beispielsweiseresearch-helperist, geben Sieresearch-helper.skill(nichtresearch-helper-v2) aus.
• Vor der Bearbeitung an einen beschreibbaren Speicherort kopieren. Der installierte Skillpfad ist möglicherweise schreibgeschützt. Nach/tmp/skill-name/kopieren, dort bearbeiten und aus der Kopie verpacken.
• Beim manuellen Packen zuerst/tmp/bereitstellen, dann in das Ausgabeverzeichnis kopieren – direkte Schreibvorgänge können aufgrund von Berechtigungen fehlschlagen.

---

Cowork-spezifische Anweisungen

Wenn Sie in Cowork arbeiten, sollten Sie vor allem Folgendes wissen:

• Sie verfügen über Subagenten, sodass der Hauptarbeitsablauf (Testfälle parallel erzeugen, Baselines ausführen, Benotung usw.) vollständig funktioniert. (Wenn jedoch schwerwiegende Probleme mit Zeitüberschreitungen auftreten, ist es in Ordnung, die Testaufforderungen in Reihe statt parallel auszuführen.)
• Sie verfügen weder über einen Browser noch über eine Anzeige. Verwenden Sie daher beim Generieren des Evaluierungs-Viewers--static <output_path>, um eine eigenständige HTML-Datei zu schreiben, anstatt einen Server zu starten. Bieten Sie dann einen Link an, auf den der Benutzer klicken kann, um den HTML-Code in seinem Browser zu öffnen.
• Aus irgendeinem Grund scheint das Cowork-Setup Claude davon abzuhalten, den Evaluierungsviewer nach dem Ausführen der Tests zu generieren. Um es noch einmal zu wiederholen: Egal, ob Sie in Cowork oder in Claude Code sind, nach dem Ausführen von Tests sollten Sie immer den Evaluierungsviewer generieren, damit der Mensch sich Beispiele ansehen kann, bevor Sie den Skill selbst überarbeiten und versuchen, Korrekturen vorzunehmen, indem Siegenerate_review.pyverwenden (und nicht Ihren eigenen Boutique-HTML-Code schreiben). Tut mir leid im Voraus, aber ich werde hier alles in Großbuchstaben schreiben: ERSTELLEN SIE DEN EVAL VIEWER BEVOR Sie die Eingaben selbst auswerten. Sie möchten sie so schnell wie möglich vor den Menschen bringen!
• Feedback funktioniert anders: Da kein Server läuft, lädt der Betrachter über die Schaltfläche „Alle Bewertungen abschicken“feedback.jsonals Datei herunter. Sie können es dann von dort aus lesen (ggf. müssen Sie zuerst den Zugang anfordern).
• Das Packen funktioniert –package_skill.pybenötigt lediglich Python und ein Dateisystem.
• Die Beschreibungsoptimierung (run_loop.py/run_eval.py) sollte in Cowork problemlos funktionieren, daclaude -püber einen Unterprozess und nicht über einen Browser verwendet wird. Bitte speichern Sie sie jedoch, bis Sie den Skill vollständig erstellt haben und der Benutzer zustimmt, dass er in gutem Zustand ist.
• Aktualisieren eines vorhandenen Skills: Der Benutzer bittet Sie möglicherweise, einen vorhandenen Skill zu aktualisieren und keinen neuen zu erstellen. Befolgen Sie die Update-Anleitung im Abschnitt claude.ai oben.

---

Referenzdateien

Das Verzeichnis „agents/“ enthält Anweisungen für spezialisierte Subagenten. Lesen Sie sie, wenn Sie den entsprechenden Subagenten erzeugen müssen.

• agents/grader.md– So werten Sie Behauptungen gegenüber Ausgaben aus
• agents/comparator.md– So führen Sie einen blinden A/B-Vergleich zwischen zwei Ausgaben durch
• agents/analyzer.md– So analysieren Sie, warum eine Version eine andere übertrifft

Das Verzeichnis references/ enthält zusätzliche Dokumentation:

• references/schemas.md– JSON-Strukturen für evals.json, grading.json usw.

---

Zur Betonung wiederholen wir hier noch einmal die Kernschleife:

• Finden Sie heraus, worum es bei der Fertigkeit geht
• Entwerfen oder bearbeiten Sie den Skill
• Führen Sie „claude-with-access-to-the-skill“ bei Testaufforderungen aus
• Bewerten Sie mit dem Benutzer die Ergebnisse:
  • Erstellen Sie benchmark.json und führen Sieeval-viewer/generate_review.pyaus, um dem Benutzer bei der Überprüfung zu helfen
  • Führen Sie quantitative Auswertungen durch
• Wiederholen Sie dies, bis Sie und der Benutzer zufrieden sind
• Verpacken Sie den endgültigen Skill und geben Sie ihn an den Benutzer zurück.

Bitte fügen Sie Schritte zu Ihrer TodoList hinzu, falls Sie so etwas haben, um sicherzustellen, dass Sie es nicht vergessen. Wenn Sie in Cowork arbeiten, fügen Sie bitte ausdrücklich „Erstellen Sie Evals JSON und führen Sieeval-viewer/generate_review.pyaus, damit ein Mensch Testfälle überprüfen kann“ in Ihre TodoList ein, um sicherzustellen, dass dies geschieht.

Viel Glück!

Ressourcendateien

LIZENZ.txt

LICENSE.txt herunterladen

Binäre Ressource

agenten/analyzer.md

Agents/analyzer.md herunterladen

Binäre Ressource

agenten/comparator.md

Agents/comparator.md herunterladen

Binäre Ressource

agenten/grader.md

Agents/grader.md herunterladen

Binäre Ressource

asset/eval_review.html

Assets/eval_review.html herunterladen

Binäre Ressource

eval-viewer/generate_review.py

Eval-viewer/generate_review.py herunterladen

Binäre Ressource

eval-viewer/viewer.html

Eval-viewer/viewer.html herunterladen

Binäre Ressource

references/schemas.md

References/schemas.md herunterladen

Binäre Ressource

scripts/init.py

Scripts/init.py herunterladen

Binäre Ressource

scripts/aggregate_benchmark.py

Download scripts/aggregate_benchmark.py

Binäre Ressource

scripts/generate_report.py

Download scripts/generate_report.py

Binäre Ressource

scripts/improve_description.py

Download scripts/improve_description.py

Binäre Ressource

scripts/package_skill.py

Scripts/package_skill.py herunterladen

#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import fnmatch
import sys
import zipfile
from pathlib import Path
from scripts.quick_validate import validate_skill

# Patterns to exclude when packaging skills.
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
EXCLUDE_GLOBS = {"*.pyc"}
EXCLUDE_FILES = {".DS_Store"}
# Directories excluded only at the skill root (not when nested deeper).
ROOT_EXCLUDE_DIRS = {"evals"}


def should_exclude(rel_path: Path) -> bool:
    """Check if a path should be excluded from packaging."""
    parts = rel_path.parts
    if any(part in EXCLUDE_DIRS for part in parts):
        return True
    # rel_path is relative to skill_path.parent, so parts[0] is the skill
    # folder name and parts[1] (if present) is the first subdir.
    if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
        return True
    name = rel_path.name
    if name in EXCLUDE_FILES:
        return True
    return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)


def package_skill(skill_path, output_dir=None):
    """
    Package a skill folder into a .skill file.

    Args:
        skill_path: Path to the skill folder
        output_dir: Optional output directory for the .skill file (defaults to current directory)

    Returns:
        Path to the created .skill file, or None if error
    """
    skill_path = Path(skill_path).resolve()

    # Validate skill folder exists
    if not skill_path.exists():
        print(f"❌ Error: Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"❌ Error: Path is not a directory: {skill_path}")
        return None

    # Validate SKILL.md exists
    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"❌ Error: SKILL.md not found in {skill_path}")
        return None

    # Run validation before packaging
    print("🔍 Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"❌ Validation failed: {message}")
        print("   Please fix the validation errors before packaging.")
        return None
    print(f"✅ {message}\n")

    # Determine output location
    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    # Create the .skill file (zip format)
    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            # Walk through the skill directory, excluding build artifacts
            for file_path in skill_path.rglob('*'):
                if not file_path.is_file():
                    continue
                arcname = file_path.relative_to(skill_path.parent)
                if should_exclude(arcname):
                    print(f"  Skipped: {arcname}")
                    continue
                zipf.write(file_path, arcname)
                print(f"  Added: {arcname}")

        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"❌ Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        print("\nExample:")
        print("  python utils/package_skill.py skills/public/my-skill")
        print("  python utils/package_skill.py skills/public/my-skill ./dist")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"📦 Packaging skill: {skill_path}")
    if output_dir:
        print(f"   Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)

    if result:
        sys.exit(0)
    else:
        sys.exit(1)


if __name__ == "__main__":
    main()

scripts/quick_validate.py

Download scripts/quick_validate.py

#!/usr/bin/env python3
"""
Quick validation script for skills - minimal version
"""

import sys
import os
import re
import yaml
from pathlib import Path

def validate_skill(skill_path):
    """Basic validation of a skill"""
    skill_path = Path(skill_path)

    # Check SKILL.md exists
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "SKILL.md not found"

    # Read and validate frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    # Extract frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    # Parse YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    # Define allowed properties
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}

    # Check for unexpected properties (excluding nested keys under metadata)
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # Check required fields
    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    # Extract name for validation
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        # Check naming convention (kebab-case: lowercase with hyphens)
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
        # Check name length (max 64 characters per spec)
        if len(name) > 64:
            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."

    # Extract and validate description
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        # Check for angle brackets
        if '<' in description or '>' in description:
            return False, "Description cannot contain angle brackets (< or >)"
        # Check description length (max 1024 characters per spec)
        if len(description) > 1024:
            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."

    # Validate compatibility field if present (optional)
    compatibility = frontmatter.get('compatibility', '')
    if compatibility:
        if not isinstance(compatibility, str):
            return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
        if len(compatibility) > 500:
            return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."

    return True, "Skill is valid!"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)

scripts/run_eval.py

Download scripts/run_eval.py

Binäre Ressource

scripts/run_loop.py

Download scripts/run_loop.py

Binäre Ressource

scripts/utils.py

Scripts/utils.py herunterladen

"""Shared utilities for skill-creator scripts."""

from pathlib import Path



def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
    """Parse a SKILL.md file, returning (name, description, full_content)."""
    content = (skill_path / "SKILL.md").read_text()
    lines = content.split("\n")

    if lines[0].strip() != "---":
        raise ValueError("SKILL.md missing frontmatter (no opening ---)")

    end_idx = None
    for i, line in enumerate(lines[1:], start=1):
        if line.strip() == "---":
            end_idx = i
            break

    if end_idx is None:
        raise ValueError("SKILL.md missing frontmatter (no closing ---)")

    name = ""
    description = ""
    frontmatter_lines = lines[1:end_idx]
    i = 0
    while i < len(frontmatter_lines):
        line = frontmatter_lines[i]
        if line.startswith("name:"):
            name = line[len("name:"):].strip().strip('"').strip("'")
        elif line.startswith("description:"):
            value = line[len("description:"):].strip()
            # Handle YAML multiline indicators (>, |, >-, |-)
            if value in (">", "|", ">-", "|-"):
                continuation_lines: list[str] = []
                i += 1
                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
                    continuation_lines.append(frontmatter_lines[i].strip())
                    i += 1
                description = " ".join(continuation_lines)
                continue
            else:
                description = value.strip('"').strip("'")
        i += 1

    return name, description, content

Siehe in GitHub

Siehe in GitHub

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

kill $VIEWER_PID 2>/dev/null

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

python -m scripts.package_skill <path/to/skill-folder>