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

## 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>

## 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. Verwende die von dieser API zurückgegebene Skill-`id`, wenn du Agents konfigurierst — über die [Agents-API](/api-reference/agents/list-agents) oder in der nuwacom App.