claudeskills DocsSkill-Ersteller
Lebenszyklusleitfaden für Agentenfähigkeiten zur Festlegung, Strukturierung und Verpackung wiederverwendbarer Fähigkeiten, komplett mit Skripten, Referenzen und Assets.
Quelle: Inhalt angepasst von Anthropics/Skills (MIT).
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 das
eval-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.
- Wozu soll diese Fähigkeit Claude befähigen?
- Wann sollte diese Fähigkeit ausgelöst werden? (welche Benutzerphrasen/Kontexte)
- Was ist das erwartete Ausgabeformat?
- 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:
- Metadaten (Name + Beschreibung) – Immer im Kontext (~100 Wörter)
- SKILL.md-Körper – Im Kontext, wann immer der Skill ausgelöst wird (<500 Zeilen ideal)
- 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.mdClaude 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
## RecommendationsBeispielmuster – 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 authenticationSchreibstil
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 unter
without_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:
-
Bewerten Sie jeden Lauf – Erzeugen Sie einen Grader-Subagenten (oder eine Inline-Bewertung), der
agents/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. -
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 erzeugt
benchmark.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. -
Machen Sie einen Analystentest – lesen Sie die Benchmark-Daten und entdecken Sie Muster, die die aggregierten Statistiken möglicherweise verbergen. Sehen Sie sich
agents/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. -
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: Wenn
webbrowser.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.
- 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/nullVerbesserung 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
-
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.
-
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.
-
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.
-
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 ein
create_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:
- Wenden Sie Ihre Verbesserungen auf die Fertigkeit an
- Führen Sie alle Testfälle erneut in einem neuen
iteration-<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. - Starten Sie den Prüfer, wobei
--previous-workspaceauf die vorherige Iteration zeigt - Warten Sie, bis der Benutzer überprüft und Ihnen mitteilt, dass er fertig ist
- 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:
- Lesen Sie die Vorlage von
assets/eval_review.html - 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
- 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 - Der Benutzer kann Abfragen bearbeiten, „Sollte auslösen“ umschalten, Einträge hinzufügen/entfernen und dann auf „Auswertungssatz exportieren“ klicken.
- 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 \
--verboseVerwenden 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 das
name-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 Sie
generate_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 ausagents/comparator.md– So führen Sie einen blinden A/B-Vergleich zwischen zwei Ausgaben durchagents/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 Sie
eval-viewer/generate_review.pyaus, um dem Benutzer bei der Überprüfung zu helfen - Führen Sie quantitative Auswertungen durch
- Erstellen Sie benchmark.json und führen Sie
- 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
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
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
Binäre Ressource
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, contentSiehe in GitHub
Themenfabrik
Anweisungen für Agentenfähigkeiten zum Erstellen von Claude-Markenthemen mit Paletten, Typografie und Layout-Kits, die zur Wiederverwendung bereit sind.
Vorlagenfähigkeit
Minimales Agenten-Fähigkeitsgerüst mit Darstellung der erforderlichen Dateien, Metadaten und Hinweise zum schnellen Einstieg in neue Claude-Fähigkeiten.