Skills-API Übersicht

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

https://{customer-tenant}.nuwacom.ai

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

Verfügbare Endpunkte

Methode	Endpunkt	Beschreibung
`GET`	`/api/v1/spaces/{spaceId}/skills`	Skills auflisten
`POST`	`/api/v1/spaces/{spaceId}/skills`	Neuen Skill erstellen
`GET`	`/api/v1/spaces/{spaceId}/skills/{skillId}`	Skill-Details abrufen
`PATCH`	`/api/v1/spaces/{spaceId}/skills/{skillId}`	Skill aktualisieren
`DELETE`	`/api/v1/spaces/{spaceId}/skills/{skillId}`	Skill löschen

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).

Pagination

Skills auflisten ist paginiert. Steuere die Seite über zwei optionale Query-Parameter:

Parameter	Typ	Beschreibung
`limit`	integer	Maximale Anzahl zurückgegebener Skills (1–100). Standard: `50`.
`offset`	integer	Anzahl der zu überspringenden Skills am Anfang der Liste. Standard: `0`.

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

curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/YOUR_SPACE_ID/skills \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meeting-Notizen",
    "description": "Formatiert Meeting-Notizen im Firmen-Template",
    "instructions": "Wenn du Meeting-Notizen schreiben sollst:\n\n1. Beginne mit Datum, Teilnehmern und Agenda.\n2. Fasse Entscheidungen als Bullet Points zusammen.\n3. Schließe mit einer Aufgaben-Tabelle ab (Verantwortlicher, Aufgabe, Fällig am)."
  }'

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

Feld	Limit
`name`	1–64 Zeichen; Buchstaben, Ziffern, Leerzeichen und Bindestriche; muss mit einem Buchstaben oder einer Ziffer beginnen und enden.
`description`	1–1.024 Zeichen.
`instructions`	Bis zu 50.000 Zeichen Markdown.

Skills mit Agents nutzen

Agents können bestimmte Skills angehängt bekommen. Verwende die von dieser API zurückgegebene Skill-id, wenn du Agents konfigurierst — über die Agents-API oder in der nuwacom App.

Übersicht

AI

Assets

Completion API

Agents

Skills

Bevor du startest

Base URL

Verfügbare Endpunkte

Instruktionen und SKILL.md

Beispiel: Skill erstellen

Feldgrenzen

Skills mit Agents nutzen

​Bevor du startest

​Base URL

​Verfügbare Endpunkte

​Instruktionen und SKILL.md

​Pagination

​Beispiel: Skill erstellen

​Feldgrenzen

​Skills mit Agents nutzen

Bevor du startest

Base URL

Verfügbare Endpunkte

Instruktionen und SKILL.md

Pagination

Beispiel: Skill erstellen

Feldgrenzen

Skills mit Agents nutzen