ahundt/ai-skill-builder

AI Skill Builder

Baue Agent Skills mit dem gemeinsamen SKILL.md-Format und der Methodik von Anthropic: den kleinsten portablen Kern, der in jedem genannten Zielsystem funktioniert, plus explizite Laufzeitadapter. Portabilität ist eine getestete Kompatibilitätsbehauptung, kein Formatierungsstil. references/sources.md zitiert die Host-Dokumentation für Claude Code, Codex und Qwen Code; jedes andere Zielsystem ist hier ungetestet – überprüfe daher das von dir anvisierte System (Schritt 1).

Diese Methodik verlangt bewusst konsistente semantische XML-Regionen innerhalb des Markdown-Körpers. Das ist eine Qualitätsrichtlinie zur Reduzierung von Mehrdeutigkeiten in komplexen Betriebsanweisungen, gestützt durch die aktuellen Anthropic-Prompting-Richtlinien und überprüft durch die Vorwärtstests in Schritt 4. Es ist keine Parser-Anforderung der portablen Agent Skills Spezifikation, keine Autorisierungsgrenze oder die Behauptung, dass XML allein Prompt-Injection verhindert.

Primäre Methodik-Quelle: „The Complete Guide to Building Skills for Claude" (Anthropic, Januar 2026)

• PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Extrahierter Text: references/ai-skill-builder-guide.md

Quelle des portablen Formats: https://agentskills.io/specification

---

Kurzstart

Um einen Skill von Grund auf neu zu erstellen, folge dem 4-Phasen-Prozess unten. Um einen bestehenden Skill zu verbessern, lies references/refining-skills.md. Zur Validierung der Struktur führe scripts/audit-skill.sh aus.

Aufruf mit: Frage nach ai-skill-builder; Hosts können ihn als /ai-skill-builder, $ai-skill-builder oder über ihre Skill-Auswahl bereitstellen.

P0-Anforderungen

Jeder Skill, den diese Methodik produziert, erfüllt alle dreizehn. Zitiere sie bei Audits und Überprüfungen mit ihrer ID.

1. SKILL-REQ001-discover-target-runtimes. Identifiziere genaue Produkte, Versionen, Aufrufmodi, Installationsbasen, Vertrauensgrenzen und Dateisystemsemantiken vor dem Erstellen.
2. SKILL-REQ002-separate-standard-from-extensions. Halte die Agent Skills Spezifikation, Laufzeiterweiterungen und Projektkonventionen in getrennten Spalten. Stelle niemals ein Claude-, Codex-, Copilot-, Gemini- oder frameworkspezifisches Feld als universell dar.
3. SKILL-REQ003-use-valid-portable-core. Platziere eine erforderliche SKILL.md in einem Verzeichnis, dessen Name mit ihrem portablen name übereinstimmt; füge eine spezifische description hinzu, die beschreibt, was der Skill tut und wann er verwendet wird. Verwende optionale Standardfelder nur bei Bedarf.
4. SKILL-REQ004-use-semantic-xml-regions. Umfasse jeden größeren operativen Bereich mit konsistenten, beschreibenden XML-Tags innerhalb des Markdown-Körpers, wie <purpose>, <requirements>, <workflow>, <examples> und <output_contract>. Halte Markdown innerhalb dieser Regionen und wörtlichen Quellcode in umschlossenen Codeblöcken. Diese verbindliche Methodikregel zielt auf die qualitativ hochwertigste Instruktionstrennung ab; sie ist keine Parser-Anforderung oder Sicherheitsgrenze des Agent Skills. scripts/audit-skill.sh meldet einen Fehler bei einem Körper ohne Region, einem unausgeglichenen oder falsch verschachtelten Tag oder einer ## -Überschrift außerhalb jeder Region.
5. SKILL-REQ005-design-progressive-disclosure. Halte die Aktivierungsbeschreibung präzise und den Hauptworkflow kurz. Verschiebe wirklich bedingte Details in fokussierte, direkt verlinkte Referenzen; halte wiederverwendbare Automatisierung in Skripten und Ausgabematerialien in Assets.
6. SKILL-REQ006-preserve-operational-context. Jede Referenz oder jedes Skript muss angeben, wann es verwendet wird, welche Eingaben es akzeptiert, was es zurückgibt oder ändert und wie Fehler gemeldet werden. Vermeide tiefe Referenzketten.
7. SKILL-REQ007-make-invocation-correct. Teste die automatische Aktivierung und die explizite Aufrufweise. Wenn eine Laufzeitumgebung Parameter unterstützt, teste leere, positionelle, benannte, in Anführungszeichen gesetzte, Unicode-, ungültige und große Eingaben. Gehe nicht davon aus, dass eine andere Laufzeitumgebung dieselbe Substitutionssyntax implementiert.
8. SKILL-REQ008-minimize-tool-authority. Behandle Skills und gebündelte Skripte als ausführbare Abhängigkeiten. Fordere die geringste erforderliche Autorität an, validiere Eingaben, behalte Genehmigungsabfragen wo praktikabel bei und beschreibe Prompt-Trennzeichen nie als Prompt-Injection-Prävention.
9. SKILL-REQ009-validate-every-harness. Validiere Entdeckung, Laden, Referenzen, Skripte, Argumente, symbolische Links, Duplikatauflösung, Aktualisierungen und Entfernung in jeder unterstützten Testumgebung. Das Bestehen eines Parsers beweist keine Laufzeitübergreifende Kompatibilität.
10. SKILL-REQ010-preserve-user-state. Installation und Deinstallation müssen exakte generierte Pfade besitzen, manuelle Bearbeitungen erhalten, mehrere konfigurierte Skill-Wurzeln unterstützen und nur installatoreigene Links oder Dateien entfernen.
11. SKILL-REQ011-measure-context-and-runtime-cost. Zeichne Metadaten zur Entdeckung, Größe geladener Anweisungen, Kosten bedingter Referenzen, Skriptzeit/Speicher/E/A und doppeltes Laden auf. Behandle Zeilen- und Token-Ziele als Heuristiken, es sei denn, eine Ziellaufzeit macht sie normativ.
12. SKILL-REQ012-forward-test-real-tasks. Verwende realistische positive, negative, mehrdeutige und adversarialische Aufforderungen. Prüfe das Aufgabenergebnis, nicht nur, ob der Skill in einer Liste erschien.
13. SKILL-REQ013-separate-authoring-from-execution. Klassifiziere, ob die Aufgabe darin besteht, den Skill zu ändern, den Skill zu verwenden, um ein Artefakt oder Ergebnis zu erzeugen, oder den Skill anhand von Beweisen zu bewerten. Laufzeiteingaben, generierte Ausgaben, Beispiele und Dogfood-Beobachtungen werden nicht zu Skill-Anweisungen, es sei denn, eine explizite Autorenentscheidung akzeptiert und verallgemeinert sie.

Regionsnamen folgen der Aufgabe, nicht einer universellen Taxonomie: Workflows verwenden <workflow>, Referenz-Skills können <decision_guide> verwenden, Multi-Mode-Skills <routing>, strenge Ergebnisverträge <output_contract>, eingebettetes Referenzmaterial <reference> und Verweise auf gebündelte Dateien und Quellen <resources>. Tags müssen konsistent, beschreibend, ausbalanciert und nicht tiefer verschachtelt sein, als es die Aufgabe erfordert. Die Standard-gegen-Erweiterungs-Matrix, das Anspruchs-Audit und der Host-Validierungsbeleg befinden sich in references/portability-and-claim-audit.md.

Wie es funktioniert

Vier-Phasen-Methodik aus dem Anthropic-Leitfaden. Jede Phase hat eine Definition of Done: die Bedingung, die erfüllt sein muss, bevor die nächste Phase beginnt.

Phase	Aktivität	Definition of Done
1: Planung & Design	Zielhosts, Anwendungsfälle, Kategorie, Erfolgskriterien definieren	Kriterien sind messbar und die Kategorie ist gewählt
2: Implementierung	Ordner erstellen, SKILL.md schreiben, Ressourcen hinzufügen	audit-skill.sh meldet keine Fehler
3: Testen	Auslöse-, Funktions-, Leistungs-, Kompatibilitäts- und Vorwärtstests	Jeder benannte Host besteht mit Validierungsbeleg; Basislinie aufgezeichnet
4: Verteilung	Paketieren, dokumentieren, veröffentlichen	Installation von einer sauberen Wurzel verifiziert

Phase 1 umfasst die Schritte 1–2 unten; die Phasen 2–4 entsprechen den Schritten 3–5.

Wie lange eine Phase dauert, hängt davon ab, wer oder was sie ausführt. Daher gibt dieses Skill keine Echtzeit-Schätzungen an, und die von dir erstellten Skills sollten dies ebenfalls nicht tun.

---

Workflow zur Skill-Erstellung

Schritt 1: Anforderungen ermitteln

Zuerst die Domäne recherchieren – verwende die Webtools des Hosts, um aktuelle Best Practices zu überprüfen, bevor du Anweisungen schreibst. Veraltete Anleitungen sind schlimmer als keine: Ein Agent befolgt sie zuversichtlich.

Alle Quellen behalten: Notiere jede konsultierte URL mit einem Vermerk, was sie bestätigt hat. Unbelegte Anleitungen können nicht verifiziert oder aktualisiert werden.

Zu Recherchestrategien, Quellenqualitätsstandards und dem erforderlichen Quellenformat: references/research.md

1. Klassifiziere die Anfrage: Autorentätigkeit (Skill ändern), Ausführung (Skill verwenden, um ein Ergebnis zu erzielen) oder Bewertung (Skill anhand von Beweisen beurteilen). Benenne das Artefakt und die Mutationsgrenze, bevor du Aufgabeninhalte als Designeingabe verwendest (SKILL-REQ013).
2. Identifiziere das Problem und die Zielnutzer
3. Identifiziere jeden Zielhost und jede Version, seine Entdeckungswurzel, Aufrufform und Neuladeverhalten. Markiere Unbekanntes als unbekannt, anstatt zu raten. Überprüfe vorhandene Skill-Wurzeln und Projektanleitungen, bevor du ein paralleles Paket erstellst.
4. Definiere 2–3 konkrete Anwendungsfälle
5. Setze messbare Erfolgskriterien (Zeitersparnis, Fehlerreduktion, Qualitätsverbesserung)
6. Wähle eine Skill-Kategorie:

Kategorie	INPUT → OUTPUT	Beispiele
1: Dokument- und Asset-Erstellung	Daten/Spezifikationen → Dokument, Code, Bericht	API-Testgenerator, Besprechungsnotizen-Zusammenfasser
2: Workflow-Automation	Aufgabenparameter → abgeschlossener mehrstufiger Prozess	Bereitstellungs-Pipeline, Code-Review-Workflow
3: MCP-Erweiterung	MCP-Toolausgaben → intelligentere Orchestrierung	Intelligente Dateisuche, BigQuery-Assistent

Für detaillierte Kategorieanleitungen: references/categories.md Für interaktive Entdeckungsfragen: references/discovery.md

Schritt 2: Struktur entwerfen

Entwerfen mit progressiver Informationsdarstellung – 3 Ladeebenen:

Ebene	Wann geladen	Ziellänge	Inhalt
1: Metadaten	Immer (~100 Wörter)	name + description	Auslösebedingungen
2: SKILL.md-Körper	Wenn der Skill ausgelöst wird	unter 5.000 Wörter (idealerweise unter 2.000)	Kernworkflow + Verweise
3: references/-Dateien	Nach Bedarf	Unbegrenzt	Tiefergehende Details, Schemata, Beispiele

Tipps zum Schreiben mit progressiver Informationsdarstellung und Erfolgsmetriken: references/best-practices.md

Schritt 3: Implementieren

Wichtige Regeln:

• ✅ Datei MUSS SKILL.md heißen (nicht README.md)
• ✅ Ordnername MUSS in Kebab-Case sein – keine Leerzeichen, keine Großbuchstaben (mein-skill nicht Mein Skill)
• ✅ YAML-Frontmatter MUSS name und description enthalten; füge eine Version unter metadata hinzu
• ✅ Beschreibung MUSS spezifische Auslösephrasen enthalten – was Nutzer SAGEN, um den Skill zu aktivieren
• ✅ Beschreibung muss unter 1024 Zeichen sein (harte Grenze – längere Beschreibungen werden abgeschnitten)
• ✅ Keine XML-Winkelklammern (< oder >) in einem Frontmatter-Feld – eine Host-Einschränkung aus Anthropics Skill-Leitfaden, keine YAML-Regel; der Körper ist nicht betroffen
• ✅ Körper: Jeder größere Abschnitt sitzt in einer ausbalancierten, beschreibenden XML-Region in einer eigenen Zeile (<purpose>, <requirements>, <workflow>, <examples>, <output_contract>), Markdown darin, wörtlicher Quellcode in umschlossenen Codeblöcken (SKILL-REQ004). Die H1-Überschrift darf außerhalb bleiben.
• ❌ KEINE README.md im Skill-Ordner – alle Dokumentation in SKILL.md oder references/ (Ausnahme: Eine README.md im GitHub-Repo-ROOT, außerhalb des Skill-Ordners, ist für GitHub in Ordnung.)
• ❌ KEINE Leerzeichen oder Unterstriche in Ordnernamen (mein_skill → mein-skill)

Frontmatter: erforderliche Felder:

---
name: dein-skill-name          # nur Kebab-Case; keine Leerzeichen, Großbuchstaben oder Unterstriche
description: Was es tut. Verwenden, wenn der Benutzer nach "spezifische Phrase", "andere Phrase" fragt.
             # MUSS enthalten: was es tut + wann es verwendet wird (Auslösebedingungen)
             # Unter 1024 Zeichen. Keine XML-Winkelklammern.
             # NICHT mit "claude" oder "anthropic" beginnen (reservierte Namensräume).
---

Für jedes optionale Feld (license, compatibility, allowed-tools, metadata) mit Hinweisen zur Host-Portabilität: references/best-practices.md

Positionierungssprache („Tests 87 % schneller generieren") gehört in die Repo-README, niemals in description. Siehe references/best-practices.md.

Ordnerstruktur (annotiertes Claude-Code-Standalone-Beispiel: references/best-practices.md, Abschnitt „Folder Structure Patterns"):

Verzeichnis	In Kontext laden?	Verwendung für
references/	Ja, nach Bedarf	Schemata, API-Dokumentation, Richtlinien, Workflow-Anleitungen
references/examples/	Nach Bedarf	Arbeitscode, den Benutzer kopieren und anpassen
scripts/	Nein (direkt ausführen)	Validatoren, Gerüstbauer, Dienstprogramme
assets/	Nein (in der Ausgabe verwendet)	Bilder, Schriftarten, HTML-Vorlagen, die der Skill in die Ausgabe einfügt

Hinweis: Plugin-Skills (in plugin-name/skills/) können examples/ auf der obersten Ebene platzieren – das ist Plugin-Entwicklungskonvention. Für eigenständige ~/.claude/skills/-Skills platziere Beispiele in references/.

Um einen neuen Skill zu gerüsten: bash scripts/scaffold-skill.sh mein-skill-name (setze SKILLS_DIR auf die Wurzel eines anderen Hosts) Um von einer Vorlage zu starten: kopiere references/examples/SKILL-template.md

Schritt 4: Testen

Fünf Testansätze (in Reihenfolge ausführen):

1. Auslösetests – überprüfen, ob der Agent bei erwarteten Phrasen aktiviert wird und nicht bei unzusammenhängenden Anfragen
2. Funktionstests – validieren, dass der Kernworkflow des Skills korrekte Ausgaben für bekannte Eingaben liefert
3. Leistungstests – messen die Verbesserung gegenüber der Basislinie (Zeitersparnis, Fehlerreduktion, Konsistenz)
4. Kompatibilitätstests – überprüfen Entdeckung, expliziten Aufruf, Referenzladen, Skript- ausführung und Duplikat-/Namensauflösung auf jedem benannten Host und jeder Version. Starte eine saubere Sitzung für jeden Host, führe den eigenen Validator des Hosts aus, wo einer existiert (Codex liefert skill-creator/scripts/quick_validate.py), teste Installationswiederholungen, mehrere Wurzeln, symbolische Link- Ziele, modifizierte Benutzerdateien und Deinstallation und zeichne einen Validierungsbeleg pro Host auf (references/portability-and-claim-audit.md).
5. Vorwärtstests – realistische positive, negative, mehrdeutige und adversarialische Aufforderungen; bewerte das Aufgabenergebnis, nicht ob der Skill in einer Liste erschien, und überprüfe, dass er nicht zu nahegelegene Aufgaben übermäßig auslöst (SKILL-REQ012)

Debuggen von Auslöseproblemen:

Frage den Agenten: "Wann würdest du den Skill [Skill-Name] verwenden?"

Der Agent sollte seine Beschreibung zurückzitieren. Passe basierend darauf an, was fehlt oder zu vage ist.

Beheben von Untertriggerung: Füge spezifischere Auslösephrasen und relevante technische Begriffe hinzu.

Beheben von Übertriggerung: Füge negative Auslöser zur Beschreibung hinzu:

description: Verarbeitet PDF-Rechtsdokumente für die Vertragsprüfung. Verwenden für "diesen Vertrag prüfen",
  "Rechtsdokument analysieren", "Vertragsklauseln extrahieren". NICHT verwenden für allgemeine PDF-Anzeige,
  Bildextraktion oder nicht-rechtliche Dokumente (verwende stattdessen den Skill doc-converter).

Für die vollständige Diagnose- und Fehlerbehebungsanleitung, die alle vier Fehlermodi abdeckt: references/troubleshooting.md

Zur Validierung der Struktur:

bash scripts/audit-skill.sh /pfad/zu/DEIN-SKILL