ComposioHQ/skill-creator

Skill Creator

Dieses Skill bietet eine Anleitung zum Erstellen effektiver Fähigkeiten.

Über Skills

Skills sind modulare, in sich geschlossene Pakete, die die Fähigkeiten von Codex erweitern, indem sie spezialisiertes Wissen, Arbeitsabläufe und Tools bereitstellen. Betrachten Sie sie als „Onboarding-Anleitungen“ für bestimmte Domänen oder Aufgaben – sie verwandeln Codex von einem通用-Agenten in einen spezialisierten Agenten, der mit prozeduralem Wissen ausgestattet ist, das kein Modell vollständig besitzen kann.

Was Skills Bereitstellen

1. Spezialisierte Arbeitsabläufe – Mehrstufige Verfahren für bestimmte Domänen
2. Tool-Integrationen – Anleitungen für die Arbeit mit bestimmten Dateiformaten oder APIs
3. Domänenexpertise – Firmenspezifisches Wissen, Schemata, Geschäftslogik
4. Gebündelte Ressourcen – Skripte, Referenzen und Assets für komplexe und wiederkehrende Aufgaben

Kernprinzipien

Prägnanz ist entscheidend

Das Kontextfenster ist ein öffentliches Gut. Skills teilen sich das Kontextfenster mit allem anderen, was Codex benötigt: Systemaufforderung, Gesprächsverlauf, Metadaten anderer Skills und die eigentliche Benutzeranfrage.

Standardannahme: Codex ist bereits sehr intelligent. Fügen Sie nur Kontext hinzu, den Codex noch nicht hat. Hinterfragen Sie jede Information: „Braucht Codex diese Erklärung wirklich?“ und „Rechtfertigt dieser Absatz seine Token-Kosten?“

Bevorzugen Sie prägnante Beispiele gegenüber ausführlichen Erklärungen.

Angemessene Freiheitsgrade Festlegen

Passen Sie den Spezifitätsgrad an die Fragilität und Variabilität der Aufgabe an:

Hohe Freiheit (textbasierte Anleitungen): Verwenden Sie dies, wenn mehrere Ansätze gültig sind, Entscheidungen vom Kontext abhängen oder Heuristiken den Ansatz leiten.

Mittlere Freiheit (Pseudocode oder Skripte mit Parametern): Verwenden Sie dies, wenn ein bevorzugtes Muster existiert, ein gewisses Maß an Variation akzeptabel ist oder die Konfiguration das Verhalten beeinflusst.

Niedrige Freiheit (spezifische Skripte, wenige Parameter): Verwenden Sie dies, wenn Operationen zerbrechlich und fehleranfällig sind, Konsistenz entscheidend ist oder eine bestimmte Reihenfolge eingehalten werden muss.

Stellen Sie sich Codex vor, der einen Weg erkundet: Eine schmale Brücke mit Klippen benötigt spezifische Leitplanken (niedrige Freiheit), während ein offenes Feld viele Routen zulässt (hohe Freiheit).

Anatomie eines Skills

Jeder Skill besteht aus einer erforderlichen SKILL.md-Datei und optionalen gebündelten Ressourcen:

skill-name/
├── SKILL.md (erforderlich)
│   ├── YAML-Frontmatter-Metadaten (erforderlich)
│   │   ├── name: (erforderlich)
│   │   └── description: (erforderlich)
│   └── Markdown-Anleitungen (erforderlich)
└── Gebündelte Ressourcen (optional)
    ├── scripts/          - Ausführbarer Code (Python/Bash/etc.)
    ├── references/       - Dokumentation, die nach Bedarf in den Kontext geladen werden soll
    └── assets/           - Dateien, die in der Ausgabe verwendet werden (Vorlagen, Symbole, Schriftarten, etc.)

SKILL.md (erforderlich)

Jede SKILL.md besteht aus:

• Frontmatter (YAML): Enthält die Felder name und description. Dies sind die einzigen Felder, die Codex liest, um zu bestimmen, wann der Skill verwendet wird. Daher ist es sehr wichtig, klar und umfassend zu beschreiben, was der Skill ist und wann er verwendet werden soll.
• Body (Markdown): Anleitungen und Hinweise zur Verwendung des Skills. Wird erst geladen, NACHDEM der Skill ausgelöst wurde (falls überhaupt).

Gebündelte Ressourcen (optional)

Skripte (scripts/)

Ausführbarer Code (Python/Bash/etc.) für Aufgaben, die deterministische Zuverlässigkeit erfordern oder wiederholt neu geschrieben werden.

• Wann einbinden: Wenn derselbe Code wiederholt neu geschrieben wird oder deterministische Zuverlässigkeit erforderlich ist
• Beispiel: scripts/rotate_pdf.py für PDF-Drehaufgaben
• Vorteile: Tokeneffizient, deterministisch, kann ausgeführt werden, ohne in den Kontext geladen zu werden
• Hinweis: Skripte müssen möglicherweise dennoch von Codex gelesen werden, um Patches oder umgebungsspezifische Anpassungen vorzunehmen

Referenzen (references/)

Dokumentation und Referenzmaterial, das nach Bedarf in den Kontext geladen werden soll, um den Prozess und das Denken von Codex zu informieren.

• Wann einbinden: Für Dokumentation, auf die Codex während der Arbeit verweisen soll
• Beispiele: references/finanz.md für Finanzschemata, references/mnda.md für die firmeneigene NDA-Vorlage, references/richtlinien.md für Unternehmensrichtlinien, references/api_docs.md für API-Spezifikationen
• Anwendungsfälle: Datenbankschemata, API-Dokumentation, Domänenwissen, Unternehmensrichtlinien, detaillierte Arbeitsablaufanleitungen
• Vorteile: Hält SKILL.md schlank, wird nur geladen, wenn Codex es für nötig hält
• Best Practice: Bei großen Dateien (>10k Wörter) grep-Suchmuster in SKILL.md einfügen
• Doppelungen vermeiden: Informationen sollten entweder in SKILL.md oder in Referenzdateien enthalten sein, nicht in beiden. Bevorzugen Sie Referenzdateien für detaillierte Informationen, es sei denn, sie sind wirklich zentral für den Skill – dies hält SKILL.md schlank, während Informationen auffindbar bleiben, ohne das Kontextfenster zu überlasten. Halten Sie in SKILL.md nur wesentliche prozedurale Anleitungen und Arbeitsablaufhinweise; verschieben Sie detailliertes Referenzmaterial, Schemata und Beispiele in Referenzdateien.

Assets (assets/)

Dateien, die nicht in den Kontext geladen werden sollen, sondern in der von Codex erstellten Ausgabe verwendet werden.

• Wann einbinden: Wenn der Skill Dateien benötigt, die in der endgültigen Ausgabe verwendet werden
• Beispiele: assets/logo.png für Marken-Assets, assets/folien.pptx für PowerPoint-Vorlagen, assets/frontend-template/ für HTML/React-Boilerplate, assets/schriftart.ttf für Typografie
• Anwendungsfälle: Vorlagen, Bilder, Symbole, Boilerplate-Code, Schriftarten, Beispieldokumente, die kopiert oder geändert werden
• Vorteile: Trennt Ausgaberessourcen von der Dokumentation, ermöglicht Codex die Verwendung von Dateien, ohne sie in den Kontext zu laden

Was Nicht in einen Skill Aufgenommen Werden Soll

Ein Skill sollte nur wesentliche Dateien enthalten, die seine Funktionalität direkt unterstützen. Erstellen Sie KEINE zusätzlichen Dokumentations- oder Hilfsdateien, einschließlich:

• README.md
• INSTALLATIONSANLEITUNG.md
• KURZREFERENZ.md
• CHANGELOG.md
• usw.

Der Skill sollte nur die Informationen enthalten, die ein KI-Agent benötigt, um die anstehende Aufgabe zu erledigen. Er sollte keine zusätzlichen Informationen über den Erstellungsprozess, Setup- und Testverfahren, benutzerseitige Dokumentation usw. enthalten. Das Erstellen zusätzlicher Dokumentationsdateien trägt nur zur Unübersichtlichkeit und Verwirrung bei.

Prinzip der Progressiven Offenlegung

Skills verwenden ein dreistufiges Ladesystem, um den Kontext effizient zu verwalten:

1. Metadaten (Name + Beschreibung) – Immer im Kontext (~100 Wörter)
2. SKILL.md-Body – Wenn der Skill ausgelöst wird (<5000 Wörter)
3. Gebündelte Ressourcen – Nach Bedarf von Codex (unbegrenzt, da Skripte ausgeführt werden können, ohne in das Kontextfenster gelesen zu werden)

Muster der Progressiven Offenlegung

Halten Sie den SKILL.md-Body auf das Wesentliche beschränkt und unter 500 Zeilen, um die Kontextüberlastung zu minimieren. Teilen Sie Inhalte in separate Dateien auf, wenn Sie sich dieser Grenze nähern. Wenn Sie Inhalte in andere Dateien auslagern, ist es sehr wichtig, von SKILL.md darauf zu verweisen und klar zu beschreiben, wann sie gelesen werden sollen, um sicherzustellen, dass der Leser des Skills von ihrer Existenz weiß und weiß, wann er sie verwenden soll.

Schlüsselprinzip: Wenn ein Skill mehrere Variationen, Frameworks oder Optionen unterstützt, behalten Sie nur den Kernarbeitsablauf und die Auswahlhinweise in SKILL.md. Verschieben Sie variantspezifische Details (Muster, Beispiele, Konfiguration) in separate Referenzdateien.

Muster 1: Übersichtsleitfaden mit Referenzen

# PDF-Verarbeitung

## Kurzanleitung

Text mit pdfplumber extrahieren:
[Codebeispiel]

## Erweiterte Funktionen

- **Formularausfüllen**: Vollständige Anleitung in [FORMS.md](FORMS.md)
- **API-Referenz**: Alle Methoden in [REFERENCE.md](REFERENCE.md)
- **Beispiele**: Häufige Muster in [EXAMPLES.md](EXAMPLES.md)

Codex lädt FORMS.md, REFERENCE.md oder EXAMPLES.md nur bei Bedarf.

Muster 2: Domänenspezifische Organisation

Organisieren Sie für Skills mit mehreren Domänen die Inhalte nach Domäne, um das Laden von irrelevantem Kontext zu vermeiden:

bigquery-skill/
├── SKILL.md (Übersicht und Navigation)
└── reference/
    ├── finanz.md (Umsatz, Abrechnungskennzahlen)
    ├── vertrieb.md (Chancen, Pipeline)
    ├── produkt.md (API-Nutzung, Funktionen)
    └── marketing.md (Kampagnen, Attribution)

Wenn ein Benutzer nach Vertriebskennzahlen fragt, liest Codex nur vertrieb.md.

Organisieren Sie ähnlich für Skills, die mehrere Frameworks oder Varianten unterstützen, nach Variante:

cloud-deploy/
├── SKILL.md (Arbeitsablauf + Anbieterauswahl)
└── references/
    ├── aws.md (AWS-Bereitstellungsmuster)
    ├── gcp.md (GCP-Bereitstellungsmuster)
    └── azure.md (Azure-Bereitstellungsmuster)

Wenn der Benutzer AWS wählt, liest Codex nur aws.md.

Muster 3: Bedingte Details

Zeigen Sie grundlegende Inhalte, verlinken Sie zu erweiterten Inhalten:

# DOCX-Verarbeitung

## Dokumente erstellen

Verwenden Sie docx-js für neue Dokumente. Siehe [DOCX-JS.md](DOCX-JS.md).

## Dokumente bearbeiten

Für einfache Bearbeitungen ändern Sie das XML direkt.

**Für Nachverfolgung von Änderungen**: Siehe [REDLINING.md](REDLINING.md)
**Für OOXML-Details**: Siehe [OOXML.md](OOXML.md)

Codex liest REDLINING.md oder OOXML.md nur, wenn der Benutzer diese Funktionen benötigt.

Wichtige Richtlinien:

• Vermeiden Sie tief verschachtelte Referenzen – Halten Sie Referenzen eine Ebene tief von SKILL.md entfernt. Alle Referenzdateien sollten direkt von SKILL.md aus verlinkt sein.
• Strukturieren Sie längere Referenzdateien – Fügen Sie bei Dateien mit mehr als 100 Zeilen ein Inhaltsverzeichnis am Anfang hinzu, damit Codex bei der Vorschau den gesamten Umfang sehen kann.

Skill-Erstellungsprozess

Die Erstellung eines Skills umfasst die folgenden Schritte:

1. Skill mit konkreten Beispielen verstehen
2. Wiederverwendbare Skill-Inhalte planen (Skripte, Referenzen, Assets)
3. Skill initialisieren (init_skill.py ausführen)
4. Skill bearbeiten (Ressourcen implementieren und SKILL.md schreiben)
5. Skill paketieren (package_skill.py ausführen)
6. Basierend auf tatsächlicher Nutzung iterieren

Befolgen Sie diese Schritte in der angegebenen Reihenfolge und überspringen Sie sie nur, wenn es einen klaren Grund gibt, dass sie nicht anwendbar sind.

Skill-Benennung

• Verwenden Sie nur Kleinbuchstaben, Ziffern und Bindestriche; normalisieren Sie benutzerdefinierte Titel zu Bindestrich-Schreibweise (z. B. „Plan-Modus“ -> plan-modus).
• Generieren Sie beim Erstellen von Namen einen Namen unter 64 Zeichen (Buchstaben, Ziffern, Bindestriche).
• Bevorzugen Sie kurze, verbbetonte Phrasen, die die Aktion beschreiben.
• Versehen Sie den Namespace mit dem Tool, wenn dies die Klarheit oder Auslösung verbessert (z. B. gh-adressen-kommentare, linear-adresse-issue).
• Benennen Sie den Skill-Ordner genau nach dem Skill-Namen.

Schritt 1: Den Skill mit Konkreten Beispielen Verstehen

Überspringen Sie diesen Schritt nur, wenn die Nutzungsmuster des Skills bereits klar verstanden sind. Er bleibt wertvoll, auch wenn Sie mit einem vorhandenen Skill arbeiten.

Um einen effektiven Skill zu erstellen, müssen Sie klar verstehen, wie der Skill anhand konkreter Beispiele verwendet wird. Dieses Verständnis kann entweder aus direkten Benutzerbeispielen oder aus generierten Beispielen stammen, die mit Benutzerfeedback validiert werden.

Beispielsweise sind beim Erstellen eines Bildbearbeitungs-Skills relevante Fragen:

• „Welche Funktionalität soll das Bildbearbeitungs-Skill unterstützen? Bearbeiten, Drehen, etwas anderes?“
• „Können Sie einige Beispiele nennen, wie dieses Skill verwendet würde?“
• „Ich kann mir vorstellen, dass Benutzer Dinge wie ‚Entferne den Rotaugen-Effekt aus diesem Bild‘ oder ‚Drehe dieses Bild‘ fragen. Gibt es andere Arten, wie Sie sich vorstellen, dass dieses Skill verwendet wird?“
• „Was würde ein Benutzer sagen, das dieses Skill auslösen sollte?“

Um Benutzer nicht zu überfordern, vermeiden Sie es, zu viele Fragen in einer einzigen Nachricht zu stellen. Beginnen Sie mit den wichtigsten Fragen und fragen Sie bei Bedarf nach, um die Effektivität zu verbessern.

Schließen Sie diesen Schritt ab, wenn ein klares Verständnis der Funktionalität besteht, die das Skill unterstützen soll.

Schritt 2: Planen der Wiederverwendbaren Skill-Inhalte

Um konkrete Beispiele in einen effektiven Skill umzuwandeln, analysieren Sie jedes Beispiel, indem Sie:

1. Überlegen, wie das Beispiel von Grund auf ausgeführt werden kann
2. Identifizieren, welche Skripte, Referenzen und Assets hilfreich wären, wenn diese Arbeitsabläufe wiederholt ausgeführt werden

Beispiel: Beim Erstellen eines pdf-editor-Skills zur Bearbeitung von Abfragen wie „Hilf mir, dieses PDF zu drehen“, zeigt die Analyse:

1. Das Drehen eines PDFs erfordert jedes Mal das Neuschreiben des gleichen Codes
2. Ein Skript scripts/rotate_pdf.py wäre hilfreich, um es im Skill zu speichern

Beispiel: Beim Entwerfen eines frontend-webapp-builder-Skills für Abfragen wie „Erstelle mir eine Todo-App“ oder „Erstelle mir ein Dashboard, um meine Schritte zu verfolgen“, zeigt die Analyse:

1. Das Schreiben einer Frontend-Web-App erfordert jedes Mal dieselbe Boilerplate HTML/React
2. Eine Vorlage assets/hello-world/, die die Boilerplate-HTML/React-Projektdateien enthält, wäre hilfreich, um sie im Skill zu speichern

Beispiel: Beim Erstellen eines big-query-Skills zur Bearbeitung von Abfragen wie „Wie viele Benutzer haben sich heute angemeldet?“ zeigt die Analyse:

1. Das Abfragen von BigQuery erfordert jedes Mal das Neuentdecken der Tabellenschemata und -beziehungen
2. Eine Referenzdatei references/schema.md, die die Tabellenschemata dokumentiert, wäre hilfreich, um sie im Skill zu speichern

Um den Inhalt des Skills festzulegen, analysieren Sie jedes konkrete Beispiel, um eine Liste der wiederzuverwendenden Ressourcen zu erstellen: Skripte, Referenzen und Assets.

Schritt 3: Initialisieren des Skills

An diesem Punkt ist es an der Zeit, den Skill tatsächlich zu erstellen.

Überspringen Sie diesen Schritt nur, wenn der zu entwickelnde Skill bereits existiert und eine Iteration oder Paketierung erforderlich ist. Fahren Sie in diesem Fall mit dem nächsten Schritt fort.

Führen Sie beim Erstellen eines neuen Skills von Grund auf immer das Skript init_skill.py aus. Das Skript generiert bequem ein neues Skill-Verzeichnis mit einer Vorlage, die automatisch alles enthält, was ein Skill benötigt, was den Erstellungsprozess viel effizienter und zuverlässiger macht.

Verwendung:

scripts/init_skill.py <skill-name> --path <ausgabe-verzeichnis> [--resources scripts,references,assets] [--examples]

Beispiele:

scripts/init_skill.py mein-skill --path skills/public
scripts/init_skill.py mein-skill --path skills/public --resources scripts,references
scripts/init_skill.py mein-skill --path skills/public --resources scripts --examples

Das Skript:

• Erstellt das Skill-Verzeichnis am angegebenen Pfad
• Generiert eine SKILL.md-Vorlage mit korrektem Frontmatter und TODO-Platzhaltern
• Erstellt optional Ressourcenverzeichnisse basierend auf --resources
• Fügt optional Beispieldateien hinzu, wenn --examples gesetzt ist

Passen Sie nach der Initialisierung die SKILL.md an und fügen Sie Ressourcen nach Bedarf hinzu. Wenn Sie --examples verwendet haben, ersetzen oder löschen Sie die Platzhalterdateien.

Schritt 4: Bearbeiten des Skills

Beim Bearbeiten des (neu generierten oder vorhandenen) Skills denken Sie daran, dass der Skill für eine andere Instanz von Codex erstellt wird – nicht für sich selbst. Sie machen ihn nicht besser, indem Sie erklären, warum Sie etwas getan haben. Der Skill muss nur das "Was" enthalten, mit minimalem "Warum".

Stellen Sie beim Einfügen von Beispielen oder Anleitungen sicher, dass alles in einen Kontext gestellt wird, den Codex nutzen kann, und vermeiden Sie das Wiederholen von Erklärungen für Konzepte, die Codex bereits kennt.

Beispiel: Schlechter Skill:

# PDF-Bearbeitung

## Drehen einer PDF-Datei

Verwenden Sie PyMuPDF (fitz), um eine PDF-Datei zu drehen. PyMuPDF ist eine leistungsstarke PDF-Bibliothek, die verschiedene Bearbeitungen ermöglicht.

So drehen Sie eine PDF:

```python
import fitz

doc = fitz.open("eingabe.pdf")
for seite in doc:
    seite.set_rotation(90)
doc.save("ausgabe.pdf")

**Beispiel: Guter Skill**:

```markdown
# PDF-Bearbeitung

## Drehen einer PDF-Datei

```python
import fitz

doc = fitz.open("eingabe.pdf")
for seite in doc:
    seite.set_rotation(90)
doc.save("ausgabe.pdf")

### Schritt 5: Paketieren des Skills

Nach der Erstellung oder Bearbeitung des Skills muss dieser paketiert werden.

Das Skript `package_skill.py` komprimiert das Skill-Verzeichnis in eine einzelne `.skill`-Datei, die installiert und verteilt werden kann, und validiert die Inhalte.

Verwendung:

```bash
scripts/package_skill.py <skill-verzeichnis>

Beispiel:

scripts/package_skill.py skills/public/mein-skill

Das Skript:

• Validiert das Skill-Verzeichnis (stellt sicher, dass SKILL.md und Frontmatter korrekt sind)
• Erstellt eine .skill-Datei (ein ZIP-Archiv) im selben Verzeichnis wie der Skill
• Zeigt das resultierende Paket an

Schritt 6: Iterieren basierend auf Tatsächlicher Nutzung

Nachdem der Skill erstellt und paketiert wurde, sollte er basierend auf der tatsächlichen Nutzung iteriert werden.

Nichts lehrt Sie, was fehlt, wie echte Anfragen. Wenn Sie bemerken, dass Codex nicht den richtigen Skill auslöst, liegt das wahrscheinlich daran, dass die Beschreibung nicht klar genug ist. Wenn Codex den richtigen Skill auslöst, aber die falschen Aktionen ausführt, sind möglicherweise detailliertere Anleitungen erforderlich.

Beobachten Sie die Nutzung des Skills und iterieren Sie basierend auf der tatsächlichen Leistung. Wenn Sie Bereiche identifizieren, in denen der Skill versagt, kehren Sie zu Schritt 4 zurück, nehmen Sie Änderungen vor und fahren Sie mit Schritt 5 zur Paketierung fort.

Ressourcen

Sie können die folgenden Skripte aus diesem Skill in anderen Kontexten verwenden:

• scripts/init_skill.py – Starter für neue Skills
• scripts/package_skill.py – Paketierer für Skills

Verwenden Sie diese, wann immer Sie einen neuen Skill initialisieren oder einen bestehenden paketieren müssen.