Agent Skill

Wenn Sie einen KI-Coding-Assistenten wie Claude Code, Codex oder Cursor nutzen, bringt ihm der SpicyAPI-Skill bei, richtig mit SpicyAPI zu arbeiten. Sie installieren ihn ein einziges Mal. Danach können Sie sagen „Füge meiner App Bildgenerierung mit SpicyAPI hinzu“, und der Assistent hält sich an die Regeln von SpicyAPI, statt zu raten.

Sie müssen kein Entwickler sein, um dieser Seite zu folgen. Wenn Sie einen Befehl in ein Terminal einfügen können, können Sie den Skill installieren.

Was ein Skill ist

Ein Skill ist ein Ordner mit Anweisungen, die für einen KI-Assistenten geschrieben sind statt für Menschen. Stellen Sie sich ein Betriebshandbuch vor, das Sie einem neuen Kollegen in die Hand geben: Es erledigt die Arbeit nicht selbst, sagt aber demjenigen, der sie erledigt, welche Schritte nötig sind, in welcher Reihenfolge und was er nie tun darf.

KI-Assistenten wissen viel über Programmierung im Allgemeinen, kennen aber die besonderen Regeln von SpicyAPI nicht verlässlich. Muss ein Assistent raten, kann es passieren, dass er

• eine Modell-ID oder ein Eingabefeld erfindet, das es nicht gibt;
• Ihren API-Schlüssel direkt in Ihren Code schreibt;
• nach einer kurzen Netzwerkstörung dieselbe kostenpflichtige Anfrage zweimal sendet und Sie doppelt zahlen;
• Ihnen einen Ergebnislink übergibt, der ein paar Tage später nicht mehr funktioniert.

Ist der Skill installiert, liest der Assistent die Regeln von SpicyAPI, bevor er loslegt. So funktioniert das in der Praxis:

1. Der Ordner des Skills liegt an einem Ort, den Ihr Assistent beim Start einer Sitzung durchsucht.
2. Der Assistent liest die Zusammenfassung des Skills, einen einzigen Absatz. Geht es in Ihrer Anfrage um SpicyAPI, öffnet er die vollständigen Anweisungen. Sie müssen den Skill dafür nicht beim Namen nennen.
3. Er befolgt diese Anweisungen, während er Code für Sie schreibt oder Befehle ausführt.

Drei Tatsachen, die Sie vorab kennen sollten:

• Er besteht nur aus Text. Markdown- und YAML-Dateien: keine Programme, keine Skripte, nichts, was bei der Installation ausgeführt wird. Sie können jede Datei in einem Texteditor öffnen; siehe Was drin ist.
• Er enthält keinen API-Schlüssel und ruft nichts auf. Von sich aus kann er weder auf Ihr Konto zugreifen noch Geld ausgeben.
• Er ist kostenlos und quelloffen. Unter MIT-Lizenz auf npm veröffentlicht als @spicyapi/skill und offen entwickelt unter github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK und CLI

SpicyAPI hat vier offizielle Werkzeuge. Sie lösen unterschiedliche Probleme und sind dafür gemacht, zusammen verwendet zu werden.

Der Skill ersetzt keines dieser Werkzeuge. Er sagt dem Assistenten, wie er sie einsetzt: die MCP-Tools, wenn sie verbunden sind, die CLI für einmalige Vorgänge und das SDK Ihrer Sprache für Code, der in Ihre Anwendung gehört.

• Nur Skill. Der Assistent schreibt korrekten Integrationscode für Ihr Projekt, kann aber nichts in Ihrem Konto nachsehen und keine Tasks für Sie ausführen.
• Nur MCP. Der Assistent kann in Ihrem Konto handeln, muss sich die richtige Reihenfolge der Schritte aber jedes Mal selbst erschließen.
• Beides. Der Assistent kann Dinge für Sie ausprobieren und tut sie auf die dokumentierte Weise. Soll Ihr Assistent echte Tasks ausführen, installieren Sie beides. Die beiden kommen sich nicht in die Quere.

Wobei er hilft

Die linke Spalte ist das, worum Sie bitten. Die rechte Spalte ist das, was der Skill den Assistenten dabei tun lässt.

Was er nicht tut

• Eigenmächtig Geld ausgeben. Der Skill ist Text und kann nichts aufrufen. Hat Ihr Assistent zusätzlich den MCP-Server oder die CLI und einen API-Schlüssel, kann er kostenpflichtige Tasks erstellen. Der Skill weist ihn an, Ihnen zuerst den Preis zu zeigen und Ihre ausdrückliche Bestätigung einzuholen, es sei denn, Ihre Anfrage hat genau diesen kostenpflichtigen Lauf bereits eindeutig freigegeben. Mit dem MCP-Server hält außerdem jede kostenpflichtige Aktion für eine Bestätigung an, die der Assistent nicht überspringen kann.
• Funktionen erfinden. Er schreibt keine Aufrufe für Dinge, die die öffentliche API nicht anbietet, etwa einen Task abbrechen, einen Task-Datensatz löschen oder einen Webhook erneut senden.
• Ihre Kontoeinstellungen anfassen. Registrierung, Anmeldung, Zahlungen, Aufladungen, Teammitglieder, Datenschutzanfragen und Kontoschließung bleiben in der SpicyAPI-Konsole. Der Assistent versucht nicht, sie zu automatisieren.
• Einen Test vortäuschen. Bitten Sie um einen echten Test, sendet er eine echte (und nach Ihrer Bestätigung möglicherweise kostenpflichtige) Anfrage und berichtet, was tatsächlich passiert ist. Ein bestandener Mock wird nie als „verifiziert“ gemeldet.
• Eine Inhaltseinstellung hinzufügen. SpicyAPI hat keinen Schalter für einen Inhaltsmodus und keine Inhaltsprüfung pro Anfrage, und der Skill erfindet keine. Was möglich ist, entscheidet das Modell, das Sie wählen.

Bevor Sie beginnen

Sie brauchen vier Dinge. Für die Installation sind nur die ersten drei nötig.

1. Einen KI-Coding-Assistenten, der Agent Skills unterstützt. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf und viele andere tun das. Der Skill nutzt das portable Ordnerformat für Agent Skills und funktioniert daher mit jedem Assistenten, der dieses Format liest. Sind Sie bei Ihrem unsicher, durchsuchen Sie seine Dokumentation nach „skills“.

2. Node.js 22 oder neuer, das den Befehl npx mitbringt. Prüfen Sie das mit:

   node --version

   Der Installer skills verlangt derzeit Node.js 22.20 oder neuer, der Installer des Pakets selbst 22.13 oder neuer. Wird der Befehl nicht gefunden oder ist die Version niedriger, installieren Sie die LTS-Version von nodejs.org und öffnen ein neues Terminal.

3. Ein Terminal. Unter macOS die App Terminal, unter Windows PowerShell. Führen Sie die Befehle in Ihrem Projektordner aus, wenn Sie pro Projekt installieren möchten.

4. Einen SpicyAPI-API-Schlüssel, sobald Sie die API aufrufen. Für die Installation des Skills brauchen Sie keinen. Legen Sie einen Schlüssel in der Konsole an; er beginnt mit sk-spicy- und wird nur ein einziges Mal angezeigt. Legen Sie ihn in einer Umgebungsvariable namens SPICY_API_KEY ab und fügen Sie den Schlüssel selbst nie in einen Chat mit Ihrem Assistenten ein. Siehe Authentifizierung.

Installieren

Es gibt zwei Wege zur Installation. Beide legen dieselben Dateien ab. Nehmen Sie den ersten, sofern Sie keinen Grund dagegen haben.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, nur dieses Projekt
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, alle Projekte
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code und Codex, alle Projekte, ohne Rückfragen
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Prüfen, ob es funktioniert

npx skills list      # Im aktuellen Projekt installierte Skills
npx skills list -g   # Für alle Projekte installierte Skills

Beispielanfragen

Fügen Sie eine dieser Anfragen in Ihren Assistenten ein und passen Sie die Details an. Erwähnen Sie SpicyAPI in der Anfrage, damit der Assistent weiß, dass der Skill gilt.

Wissen Sie bereits, welches Modell Sie wollen, kopieren Sie seine exakte ID aus dem Tab API der Modellseite oder aus dem authentifizierten Live-Katalog (GET /api/v1/models) und setzen Sie sie in die Anfrage ein. Die Beispiele schreiben MODEL_ID_FROM_CATALOG an die Stelle, an die diese ID gehört; das ist ein Platzhalter, keine echte ID. Haben Sie keine, bitten Sie den Assistenten, aus dem Live-Katalog zu wählen. Siehe Modellkatalog.

Einer Next.js-App einen Bild-Endpunkt hinzufügen

Füge meiner Next.js-App eine serverseitige API-Route hinzu, die einen Text-Prompt entgegennimmt, mit SpicyAPI und dem Modell MODEL_ID_FROM_CATALOG ein Bild generiert, auf das Ergebnis wartet und den Bildlink zurückgibt. Lies den API-Schlüssel aus SPICY_API_KEY.

Worauf der Skill den Assistenten achten lässt:

• Der Schlüssel bleibt auf Ihrem Server in SPICY_API_KEY. Ihre Webseite ruft Ihre Route auf; sie ruft SpicyAPI nie mit dem Schlüssel auf.
• Er liest die aktuellen Eingabefelder dieses Modells aus dem Live-Katalog, bevor er die Anfrage baut.
• Er holt zuerst eine genaue Kostenschätzung ein und zeigt Ihnen die geschätzten Kosten und den Höchstbetrag. Die kostenpflichtige Anfrage enthält diese bestätigte Kostenschätzung.
• Er legt für die Generierung einen einzigen Idempotenzschlüssel an und verwendet ihn wieder, wenn die Anfrage in eine Zeitüberschreitung läuft.
• Er wartet mit einer Frist und prüft danach den state des Tasks: Ein beendetes Warten ist nicht dasselbe wie eine erfolgreiche Generierung.

Ergebnisse mit einem Webhook in Express empfangen

Füge meinem Express-Server einen Webhook-Endpunkt hinzu, der Task-Ergebnisse von SpicyAPI empfängt, die Signatur mit SPICY_WEBHOOK_SECRET prüft und den Ergebnislink in meiner Datenbank speichert.

• Er prüft die Signatur am exakten rohen Anfragerumpf, bevor er ihn als JSON parst.
• Er ignoriert Duplikate anhand der request_id der Zustellung, denn dasselbe Ereignis kann mehr als einmal ankommen.
• Er liest das Ergebnis direkt aus einem vollständigen, geprüften Webhook, ohne es zusätzlich nachzuschlagen.

Fertige Videos in Ihren eigenen Speicher kopieren

Wenn ein SpicyAPI-Video-Task erfolgreich ist, lade das Video herunter, lade es in meinen S3-Bucket hoch und speichere dann meinen eigenen Link statt des Links von SpicyAPI.

• Ergebnislinks sind temporär, und erzeugte Dateien werden etwa 14 Tage aufbewahrt; deshalb legt er eine dauerhafte Kopie unter Ihrer Kontrolle an.
• Beim Herunterladen über einen Ergebnislink sendet er Ihren API-Schlüssel nicht mit.
• Ist ein Link abgelaufen, fragt er denselben Task erneut bei SpicyAPI ab, um einen frischen Link zu erhalten. Er erstellt nie einen neuen Task, nur um an einen Link zu kommen.

Das Foto eines Nutzers in ein Video verwandeln

Lass Nutzer in meiner App ein Foto hochladen und mit SpicyAPI ein kurzes Video daraus machen.

• Er lädt die Datei zuerst zu SpicyAPI hoch und setzt die zurückgegebene spicy://-Adresse in die Anfrage, statt die Datei als Base64 einzufügen.
• Er hält die Upload-Grenzen ein: 10 MiB für Bilder, 90 MiB für Video im Format MP4 oder WebM und für Audio im Format MP3 oder WAV.
• Ein Foto, das bereits unter einem öffentlichen HTTPS-Link liegt, kann direkt übergeben werden, ohne Upload.

Wiederholungen und niedriges Guthaben behandeln

Sorge dafür, dass meine SpicyAPI-Integration mit Fehlern umgehen kann: Zeitüberschreitungen im Netzwerk wiederholen, ohne doppelt zu zahlen, eine klare Meldung zeigen, wenn das Guthaben meines Kontos zu niedrig ist, und bei einem Rate Limit zurückfahren.

• Nach einer Zeitüberschreitung wiederholt er mit demselben Idempotenzschlüssel, sodass eine Wiederholung keinen zweiten kostenpflichtigen Task anlegen kann.
• „Guthaben nicht ausreichend“ (Code 40201) wiederholt er nicht; Ihr Nutzer sieht eine klare Meldung, und Sie laden in der Konsole auf.
• Er wartet so lange, wie Retry-After angibt, bevor er es erneut versucht.
• Ist die Kostenschätzung abgelaufen oder hat sich der Preis geändert (Code 40901), holt er eine neue Kostenschätzung ein und fragt Sie erneut, statt die Preisprüfung wegzulassen.
• Er weiß, dass die Wiederholung eines fehlgeschlagenen Tasks einen neuen Task anlegt, der erneut berechnet werden kann; er tut das deshalb nur, wenn Sie einen neuen Versuch wollen.

Einen Stapel generieren

Generiere mit SpicyAPI Produktfotos für die 20 Artikel in products.csv, höchstens 3 gleichzeitig, und protokolliere jede Task-ID.

• SpicyAPI hat keinen Batch-Endpunkt; deshalb lässt er nur eine begrenzte Zahl von Anfragen gleichzeitig laufen.
• Jeder Eintrag erhält seinen eigenen Idempotenzschlüssel und seinen eigenen Preis.
• Er hält jede Task-ID fest, sobald der Task angenommen ist.
• Läuft ein Eintrag in eine Zeitüberschreitung, holt er nur diesen einen nach und reicht nie den ganzen Stapel neu ein.

Was drin ist

Der installierte Ordner sieht so aus:

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

Der Assistent öffnet die beiden Referenzdateien nur, wenn eine Aufgabe sie erfordert; so bleibt sein Arbeitsgedächtnis frei für Ihr Projekt. Um die Dateien vor der Installation zu lesen, führen Sie npx @spicyapi/skill path aus: Der Befehl gibt den Ordner aus, in dem das Paket sie aufbewahrt.

Der Skill weist den Assistenten an, Ihren Code und Ihre Werkzeuge mit diesen Umgebungsvariablen zu konfigurieren. Der Skill selbst liest keine davon.

Aktualisieren und entfernen

Aktualisieren

Der Skill ändert sich, wenn sich der von SpicyAPI empfohlene Arbeitsablauf ändert, und installierte Kopien aktualisieren sich nicht von selbst. Der installierte Ordner trägt keine Versionsnummer; eine Neuinstallation ist daher der einfachste Weg, sicher auf dem aktuellen Stand zu sein.

• Mit npx skills add installiert: Führen Sie denselben Befehl erneut aus, mit demselben Geltungsbereich und denselben Assistenten. Er ersetzt die installierten Dateien durch den aktuellen Stand des Repositorys. Eine Änderung steht damit sofort zur Verfügung; warten müssen Sie auf nichts.

• Mit dem Paket-Installer installiert: Führen Sie ihn erneut mit --force und demselben --target aus. Mit @latest holt npx das neueste Paket, statt eine zwischengespeicherte Version wiederzuverwenden:

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

Entfernen

Das Entfernen des Skills wirkt sich nicht auf Ihr SpicyAPI-Konto, Ihre API-Schlüssel oder Code aus, den der Assistent bereits geschrieben hat.

• Mit npx skills add installiert: Führen Sie Folgendes im selben Projektordner aus, mit -g, falls Sie global installiert haben. Prüfen Sie danach, ob der Ordner spicyapi verschwunden ist.

  npx skills remove spicyapi

• Mit dem Paket-Installer installiert: Löschen Sie den Ordner spicyapi, im Finder bzw. Datei-Explorer oder in einem Terminal:

  # macOS und Linux: den Ordner verwenden, in den Sie installiert haben
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Prüfen Sie den Pfad zweimal, bevor Sie die Eingabetaste drücken: Er muss auf spicyapi enden.

Starten Sie anschließend eine neue Sitzung, damit der Assistent den Skill nicht mehr verwendet.

Fehlerbehebung

Quellcode

Das Paket steht unter MIT-Lizenz und wird offen unter github.com/spicyapi-ai/spicy-skill entwickelt. Dort lesen Sie die Anweisungen, die der Skill tatsächlich ablegt, melden Verhalten, das von der Beschreibung abweicht, oder schlagen eine Änderung vor.

Nächste Schritte