Skip to main content
Mit der Skills-API kannst du Skills in deinem nuwacom Workspace programmatisch erstellen und verwalten, zum Beispiel um Skill-Instruktionen mit einer externen Quelle synchron zu halten, Skills aus eigenen Tools heraus anzulegen oder die Skill-IDs zu ermitteln, die du brauchst, um Skills an Agents anzuhängen. Ein Skill ist ein wiederverwendbares Instruktionspaket für die KI: ein Name, eine kurze Beschreibung und Markdown-Instruktionen, die die KI bei Bedarf lädt, wenn sie für die aktuelle Aufgabe relevant sind.

​
Bevor du startest

  • API-Key: Alle Endpunkte erfordern einen Bearer-Token. Admins können API-Keys in den Workspace-Einstellungen im Bereich API Keys erstellen.
  • Space-Bezug: Skills gehören immer zu einem Space, daher sind alle Endpunkte unter dem Space-Pfad verschachtelt (/api/v1/spaces/{spaceId}/skills). Die Rolle des Aufrufers in diesem Space muss Leserechte für das Skills-Feature haben, um Skills aufzulisten oder abzurufen, und Schreibrechte, um sie zu erstellen, zu ändern oder zu löschen.
  • Nur eigene Skills: Eingebaute nuwacom Skills und Skill-Vorlagen sind über diese API nicht zugänglich. Die API liefert und verwaltet ausschließlich selbst erstellte Skills (manuell, per Upload, GitHub-Import oder KI-generiert).
  • Kein Entwurfsstand: Anders als bei Agents gibt es bei Skills keine Unterscheidung zwischen Entwurf und veröffentlichter Version — Änderungen sind sofort live.

​
Base URL

Ersetze {customer-tenant} durch den Tenant-Namen deines Workspace.

​
Verfügbare Endpunkte

​
Instruktionen und SKILL.md

Intern wird ein Skill als SKILL.md-Datei gespeichert: ein YAML-Frontmatter-Block mit name und description des Skills, gefolgt von den Markdown-Instruktionen. Die API abstrahiert das:
  • Das Feld instructions bei Erstellen und Aktualisieren ist der Body der SKILL.md — schreibe reines Markdown, ohne Frontmatter.
  • Das Frontmatter wird automatisch aus name und description generiert und bei Änderungen synchron gehalten.
  • Skill-Details abrufen liefert den aktuellen Body als instructions. Der Listen-Endpunkt lässt das Feld aus Performance-Gründen weg; rufe einen einzelnen Skill ab, um es zu lesen.
Beim Aktualisieren ersetzt instructions den aktuellen Body vollständig. Lies den aktuellen Wert zuerst über Skill-Details abrufen, wenn du anhängen statt ersetzen willst. Wird instructions weggelassen, bleibt der aktuelle Body erhalten (eine reine Umbenennung aktualisiert nur das Frontmatter).

​
Aktivierung

Jeder Skill trägt in den API-Antworten ein enabled-Flag: den space-weiten Aktivierungszustand. Aktivierte Skills lädt die KI, sobald ihre Beschreibung zur Aufgabe passt; deaktivierte Skills werden ignoriert. Neue Skills sind zunächst aktiviert.
  • Skill deaktivieren schaltet einen Skill für den ganzen Space aus, ohne ihn zu löschen — der Skill und seine Dateien bleiben unangetastet.
  • Skill aktivieren schaltet ihn wieder ein.
Ein Space kann höchstens 40 aktive Skills haben; ein Aktivieren darüber hinaus liefert 409 — deaktiviere zuerst einen anderen Skill.
Die API verwaltet den space-weiten Zustand (Admin-Semantik — API-Keys haben keinen persönlichen Benutzerkontext). Einzelne Benutzer können ihn in der nuwacom App weiterhin für sich selbst überschreiben; diese persönlichen Präferenzen sind über diese API nicht sichtbar.

​
Skill-Dateien

Neben seiner SKILL.md kann ein Skill weitere Dateien enthalten — Referenzdokumente, Skripte oder Templates, die die KI bei Bedarf liest, wenn die Instruktionen darauf verweisen. Die Datei-Endpunkte verwalten diese Dateien:
  • Skill-Dateien auflisten liefert jede Datei mit path, size (Bytes) und mimeType.
  • Skill-Datei abrufen liefert den Textinhalt einer Datei. Referenziere Dateien über ihren relativen path im Skill-Ordner — verschachtelte Pfade wie reference/format.md gehören direkt in die URL.
  • Skill-Datei erstellen oder ersetzen schreibt eine Textdatei. Übergeordnete Ordner entstehen implizit durch den Pfad; der übergebene content ersetzt eine bestehende Datei vollständig.
  • Skill-Datei löschen entfernt eine Datei. SKILL.md kann nicht gelöscht werden — jeder Skill braucht eine.
Nur Textdateien: Die Datei-Endpunkte verarbeiten Textformate (Markdown, Skripte, JSON/YAML, CSV, SVG und ähnliche). Binäre Assets wie Bilder und Fonts können derzeit nur in der nuwacom App hochgeladen werden.
Du kannst die SKILL.md über die Datei-Endpunkte schreiben; dabei wird die gesamte Datei inklusive Frontmatter ersetzt (eine gültige description im Frontmatter wird zurück in die Skill-Metadaten synchronisiert). Bevorzuge stattdessen Skill aktualisieren mit instructions — das hält das Frontmatter automatisch konsistent.

​
Pagination

Skills auflisten ist paginiert. Steuere die Seite über zwei optionale Query-Parameter: Die Antwort ist eine Envelope: Die Skills stehen in data, zusammen mit den Pagination-Metadaten (total, limit, offset, hasMore). Blättere durch die vollständige Liste, indem du offset um limit erhöhst, bis hasMore false ist.

​
Beispiel: Skill erstellen

Die Antwort enthält die id des neuen Skills. Der Skill ist sofort aktiv und die KI kann ihn laden, sobald seine Beschreibung zur Aufgabe passt.

​
Feldgrenzen

​
Skills mit Agents nutzen

Agents können bestimmte Skills angehängt bekommen: Übergib die von dieser API zurückgegebenen Skill-ids im skillIds-Array beim Erstellen oder Aktualisieren eines Agents. Die vollständige Semantik (exklusives Laden, Full Replace, Entwurf/Veröffentlichung) beschreibt die Agents-API-Übersicht.