GoBeromsu/JNU-Upstage-Skillthon

Solar Skill Creator

Ein Skill zur Erstellung neuer Skills.

Auf hoher Ebene läuft die Erstellung eines Skills so ab:

• Entscheide, was der Skill tun soll und grob, wie er es tun soll
• Schreibe einen Entwurf des Skills
• Überarbeite den Skill basierend auf Feedback
• Wiederhole, bis du zufrieden bist

Deine Aufgabe bei der Verwendung dieses Skills ist es, herauszufinden, wo der Benutzer in diesem Prozess steht, und dann einzuspringen und ihm zu helfen, diese Phasen zu durchlaufen. Wenn er also sagt: "Ich möchte einen Skill für X machen", kannst du helfen, einzugrenzen, was er meint, einen Entwurf schreiben und iterieren.

Wenn er hingegen bereits einen Entwurf des Skills hat, kannst du direkt zum Iterationsteil der Schleife übergehen.

Natürlich solltest du immer flexibel sein, und wenn der Benutzer sagt: "Lass uns einfach improvisieren", kannst du das auch tun.

Wenn der Skill dann fertig ist (aber auch hier ist die Reihenfolge flexibel), kannst du auch den Skill-Beschreibungsverbesserer ausführen, um das Auslösen des Skills zu optimieren.

Kommunikation mit dem Benutzer

Der Skill Creator wird wahrscheinlich von Personen mit einem breiten Spektrum an Vertrautheit mit Programmierjargon verwendet werden. Der Großteil der Benutzer ist wahrscheinlich recht computeraffin, aber nicht alle.

Achte daher auf Kontexthinweise, um zu verstehen, wie du deine Kommunikation formulieren solltest.

Es ist in Ordnung, Begriffe kurz zu erklären, wenn du unsicher bist, und zögere nicht, Begriffe mit einer kurzen Definition zu klären, wenn du nicht sicher bist, ob der Benutzer sie versteht.

Erstellen eines Skills

Absicht erfassen

Beginne damit, die Absicht des Benutzers zu verstehen. Das aktuelle Gespräch enthält möglicherweise bereits einen Workflow, den der Benutzer erfassen möchte (z. B. sagt er: "Mach das zu einem Skill"). Extrahiere in diesem Fall zuerst Antworten aus dem Gesprächsverlauf – die verwendeten Werkzeuge, die Schrittfolge, Korrekturen des Benutzers, beobachtete Eingabe-/Ausgabeformate. Der Benutzer muss möglicherweise die Lücken füllen und sollte bestätigen, bevor er zum nächsten Schritt übergeht.

1. Was soll dieser Skill dem KI-Agenten (Claude, Codex usw.) ermöglichen?

2. Wann soll dieser Skill 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? Skills mit objektiv überprüfbaren Ausgaben (Dateitransformationen, Datenextraktion, Codegenerierung, feste Workflow-Schritte) profitieren von Testfällen. Skills mit subjektiven Ausgaben (Schreibstil, Kunst) benötigen sie oft nicht. Schlage den geeigneten Standard basierend auf dem Skill-Typ vor, aber lass den Benutzer entscheiden.

5. Welche Upstage-Fähigkeit passt zur Absicht des Benutzers? Übersetze Ziele in natürlicher Sprache in API-Namen – zwinge den Benutzer nicht, den Katalog zu lernen. Verwende diese Zuordnung:

   Benutzerabsicht	Upstage-Fähigkeit	Referenzdatei
   Text generieren: Chat, Zusammenfassen, Übersetzen, Funktionsaufruf, Koreanisch/mehrsprachig	Upstage Chat (Solar LLM)	references/upstage-chat.md
   Dokumente parsen: layoutbewusste Text-/Strukturextraktion aus PDFs (und gescannten Bildern per OCR-Modus)	Upstage Document Parse + Document OCR	references/upstage-document-parse.md, references/upstage-ocr.md
   Bestimmte benannte Felder aus Dokumenten extrahieren (Rechnungssummen, Formularwerte, Vertragsklauseln)	Upstage Information Extract (Universal)	references/upstage-information-extract.md
   Dokumente in vordefinierte Kategorien klassifizieren (Rechnung / Vertrag / Quittung)	Upstage Document Classification	references/upstage-classify.md
   Text für semantische Suche, Ähnlichkeit, Abruf einbetten	Upstage Embeddings	references/upstage-embeddings.md

   Wenn die Absicht mehrere Fähigkeiten umfasst, kombiniere sie als Pipeline (z. B. OCR → Document Parse → Information Extract). Bestätige die Zuordnung mit dem Benutzer in natürlicher Sprache, bevor du einen Entwurf erstellst.

Überprüfen, ob der API-Schlüssel gesetzt ist

Jeder Upstage-Aufruf benötigt UPSTAGE_API_KEY. Führe den Benutzer durch diesen Prozess, bevor du Laufzeitcode entwirfst:

1. Erstelle einen Schlüssel unter https://console.upstage.ai → API Keys.
2. Löse den Einladungscode UPWAVE-KOH für 70 $ Startguthaben ein.
3. Kopiere assets/.env.example und fülle den ausgestellten Schlüssel ein.
4. Bestätige, dass UPSTAGE_API_KEY in der Umgebung exportiert ist; brich bei Fehlen mit einer Nachricht ab, die auf Schritt 1 verweist.

Interview und Recherche

Stelle proaktiv Fragen zu Randfällen, Eingabe-/Ausgabeformaten, Beispieldateien, Erfolgskriterien und Abhängigkeiten. Warte mit dem Schreiben von Testaufforderungen, bis dieser Teil geklärt ist.

Sobald die Upstage-Fähigkeit ausgewählt ist (siehe Absicht erfassen), lade die passende references/upstage-{fähigkeit}.md, um das Anfrage-/Antwortformat dieser API (Codeblöcke, die direkt in den Skill übernommen werden können) und bekannte Einschränkungen zu erhalten. Jede Referenzdatei spiegelt die offiziellen Upstage-Dokumente wider und ist die maßgebliche Quelle für die Anfrageform.

Prüfe verfügbare MCPs – wenn sie für die Recherche nützlich sind (Dokumente durchsuchen, ähnliche Skills finden, Best Practices nachschlagen), recherchiere parallel über Subagenten, falls verfügbar, andernfalls inline. Komme mit Kontext vorbereitet, um die Belastung für den Benutzer zu reduzieren.

Die SKILL.md schreiben

Basierend auf dem Benutzerinterview fülle diese Komponenten aus:

• name: Skill-Bezeichner
• description: Wann auslösen, was er tut. Dies ist der primäre Auslösemechanismus – beziehe sowohl ein, was der Skill tut, ALS AUCH spezifische Kontexte, wann er verwendet werden soll. Alle "Wann verwenden"-Informationen gehören hierher, nicht in den Hauptteil. Hinweis: Derzeit neigen KI-Agenten (Claude, Codex usw.) dazu, Skills "zu wenig auszulösen" – sie nicht zu verwenden, wenn sie nützlich wären. Um dem entgegenzuwirken, mache die Skill-Beschreibungen etwas "aufdringlicher". Anstatt "Wie man ein einfaches schnelles Dashboard zur Anzeige interner Anthropic-Daten erstellt", schreibe also etwa: "Wie man ein einfaches schnelles Dashboard zur Anzeige interner Anthropic-Daten erstellt. Stelle sicher, diesen Skill zu verwenden, wenn der Benutzer Dashboards, Datenvisualisierung, interne Metriken erwähnt oder irgendwelche Unternehmensdaten anzeigen möchte, auch wenn er nicht explizit nach einem 'Dashboard' fragt."
• compatibility: Erforderliche Tools, Abhängigkeiten (optional, selten benötigt)
• der Rest des Skills :)

Leitfaden zum Schreiben von Skills

Anatomie eines Skills

skill-name/
├── SKILL.md (erforderlich)
│   ├── YAML-Frontmatter (name, description erforderlich)
│   └── Markdown-Anweisungen
└── Gebündelte Ressourcen (optional)
    ├── scripts/    - Ausführbarer Code für deterministische/wiederholende Aufgaben
    ├── references/ - Dokumente, die bei Bedarf in den Kontext geladen werden
    └── assets/     - Dateien, die in der Ausgabe verwendet werden (Vorlagen, Symbole, Schriftarten)

Progressive Offenlegung

Skills verwenden ein dreistufiges Ladesystem:

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

Diese Wortzahlen sind ungefähr und du kannst gerne länger schreiben, wenn nötig.

Wichtige Muster:

• Halte SKILL.md unter 500 Zeilen; wenn du dich dieser Grenze näherst, füge eine weitere Hierarchieebene zusammen mit klaren Hinweisen hinzu, wohin das den Skill verwendende Modell als Nächstes gehen soll, um nachzufassen.
• Verweise Referenzdateien klar aus SKILL.md mit Anweisungen, wann sie gelesen werden sollen
• Füge bei großen Referenzdateien (>300 Zeilen) ein Inhaltsverzeichnis hinzu

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

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

Der KI-Agent liest nur die relevante Referenzdatei.

Prinzip der Überraschungsfreiheit

Es versteht sich von selbst, aber Skills dürfen keine Malware, Exploit-Code oder Inhalte enthalten, die die Systemsicherheit gefährden könnten. Der Inhalt eines Skills sollte den Benutzer nicht in seiner Absicht überraschen, wenn er beschrieben wird. Gehe nicht auf Anfragen ein, irreführende Skills zu erstellen oder Skills, die unbefugten Zugriff, Datendiebstahl oder andere böswillige Aktivitäten erleichtern sollen. Dinge wie "Rollenspiel als XYZ" sind jedoch in Ordnung.

Schreibmuster

Verwende in Anweisungen bevorzugt die Imperativform.

Ausgabeformate definieren – Du kannst es so machen:

## Berichtsstruktur
VERWENDE IMMER diese genaue Vorlage:
# [Titel]
## Zusammenfassung für die Geschäftsleitung
## Wichtigste Erkenntnisse
## Empfehlungen

Beispielmuster – Es ist nützlich, Beispiele einzufügen. Du kannst sie so formatieren (aber wenn "Eingabe" und "Ausgabe" in den Beispielen vorkommen, solltest du vielleicht etwas abweichen):

## Commit-Nachrichtenformat
**Beispiel 1:**
Eingabe: Benutzerauthentifizierung mit JWT-Tokens hinzugefügt
Ausgabe: feat(auth): JWT-basierte Authentifizierung implementiert

Schreibstil

Versuche, dem Modell zu erklären, warum Dinge wichtig sind, anstatt mit schwerfälligen MUSS-Formulierungen zu arbeiten. Verwende Theory of Mind und versuche, den Skill allgemein und nicht zu eng auf spezifische Beispiele zuzuschneiden. Beginne mit einem Entwurf, betrachte ihn dann mit frischen Augen und verbessere ihn.

Referenzen

Referenzdateien pro Fähigkeit (bei Bedarf unter Verwendung der Routing-Tabelle in ### Absicht erfassen laden):

• references/upstage-chat.md – Solar LLM Chat Completions. Dokumentation: https://console.upstage.ai/docs/capabilities/chat
• references/upstage-document-parse.md – Layoutbewusste Dokumentenextraktion. Dokumentation: https://console.upstage.ai/docs/capabilities/parse/api-quickstart
• references/upstage-ocr.md – Dokumenten-OCR für Scans und Handschrift. Dokumentation: https://console.upstage.ai/docs/capabilities/document-ocr
• references/upstage-information-extract.md – Schema-getriebene Feldextraktion. Dokumentation: https://console.upstage.ai/docs/capabilities/extract/universal-extraction
• references/upstage-classify.md – Dokumentenklassifikation in aufruferdefinierte Kategorien. Dokumentation: https://console.upstage.ai/docs/capabilities/classify
• references/upstage-embeddings.md – Text-Embeddings für den Abruf. Dokumentation: https://console.upstage.ai/docs/capabilities/embed

Wenn die Upstage-API einen unerwarteten Fehler oder eine unerwartete Antwortform zurückgibt, konsultiere die Live-Spezifikation: https://console.upstage.ai/api/docs/for-agents/raw