> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuwacom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills-API Übersicht

> Skills in deinem nuwacom Workspace programmatisch erstellen und verwalten

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](/api-reference/skills/list-skills) |
| `POST` | `/api/v1/spaces/{spaceId}/skills` | [Neuen Skill erstellen](/api-reference/skills/create-a-skill) |
| `GET` | `/api/v1/spaces/{spaceId}/skills/{skillId}` | [Skill-Details abrufen](/api-reference/skills/get-a-skill) |
| `PATCH` | `/api/v1/spaces/{spaceId}/skills/{skillId}` | [Skill aktualisieren](/api-reference/skills/update-a-skill) |
| `DELETE` | `/api/v1/spaces/{spaceId}/skills/{skillId}` | [Skill löschen](/api-reference/skills/delete-a-skill) |
| `POST` | `/api/v1/spaces/{spaceId}/skills/{skillId}/enable` | [Skill aktivieren](/api-reference/skills/enable-a-skill) |
| `POST` | `/api/v1/spaces/{spaceId}/skills/{skillId}/disable` | [Skill deaktivieren](/api-reference/skills/disable-a-skill) |
| `GET` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files` | [Skill-Dateien auflisten](/api-reference/skills/list-skill-files) |
| `GET` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files/{path}` | [Skill-Datei abrufen](/api-reference/skills/get-a-skill-file) |
| `PUT` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files/{path}` | [Skill-Datei erstellen oder ersetzen](/api-reference/skills/create-or-replace-a-skill-file) |
| `DELETE` | `/api/v1/spaces/{spaceId}/skills/{skillId}/files/{path}` | [Skill-Datei löschen](/api-reference/skills/delete-a-skill-file) |

## 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](/api-reference/skills/create-a-skill) und [Aktualisieren](/api-reference/skills/update-a-skill) 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](/api-reference/skills/get-a-skill) 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.

<Note>
  Beim Aktualisieren **ersetzt** `instructions` den aktuellen Body vollständig. Lies den aktuellen Wert zuerst über [Skill-Details abrufen](/api-reference/skills/get-a-skill), wenn du anhängen statt ersetzen willst. Wird `instructions` weggelassen, bleibt der aktuelle Body erhalten (eine reine Umbenennung aktualisiert nur das Frontmatter).
</Note>

## 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](/api-reference/skills/disable-a-skill) schaltet einen Skill für den ganzen Space aus, ohne ihn zu löschen — der Skill und seine Dateien bleiben unangetastet.
* [Skill aktivieren](/api-reference/skills/enable-a-skill) 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.

<Note>
  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.
</Note>

## 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](/api-reference/skills/list-skill-files) liefert jede Datei mit `path`, `size` (Bytes) und `mimeType`.
* [Skill-Datei abrufen](/api-reference/skills/get-a-skill-file) 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](/api-reference/skills/create-or-replace-a-skill-file) schreibt eine Textdatei. Übergeordnete Ordner entstehen implizit durch den Pfad; der übergebene `content` ersetzt eine bestehende Datei vollständig.
* [Skill-Datei löschen](/api-reference/skills/delete-a-skill-file) 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.

<Note>
  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](/api-reference/skills/update-a-skill) mit `instructions` — das hält das Frontmatter automatisch konsistent.
</Note>

## Pagination

[Skills auflisten](/api-reference/skills/list-skills) 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

```bash theme={null}
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: Übergib die von dieser API zurückgegebenen Skill-`id`s im `skillIds`-Array beim [Erstellen](/api-reference/agents/create-an-agent) oder [Aktualisieren](/api-reference/agents/update-an-agent) eines Agents. Die vollständige Semantik (exklusives Laden, Full Replace, Entwurf/Veröffentlichung) beschreibt die [Agents-API-Übersicht](/de/admin/agents-api-uebersicht#skills).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.