> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Skill importieren
> Erstelle oder aktualisiere einen Skill aus einer SKILL.md-Datei oder einem Zip-Archiv
**Nutzt du unsere API über ein Dedicated Deployment?** Ersetze einfach `api.langdock.com` mit der Basis-URL deines Deployments: **`/api/public`**
Importiert einen Skill aus einer `SKILL.md`-Datei oder einem Zip-Archiv. Nutze diesen Endpoint, um repository-verwaltete Skills in Langdock zu synchronisieren.
## Erforderliche Scopes
Dieser Endpoint erfordert den `SKILL_API` Scope.
Das Erstellen eines neuen Skills erfordert die Workspace-Berechtigung `createSkills`. Das Aktualisieren eines bestehenden Skills mit `mode: "upsert"` erfordert Editor-Zugriff auf den passenden Skill.
## Request-Format
Sende die Anfrage als `multipart/form-data`.
| Feld | Typ | Erforderlich | Beschreibung |
| ---------------- | ------ | ------------ | ---------------------------------------------------------------------------------------------------------- |
| `file` | file | Ja | `SKILL.md`, `.zip` oder `.skill` Dateiinhalt. |
| `fileType` | string | Ja | Zu verwendender Datei-Parser: `md` oder `zip`. Nutze `zip` für `.zip`- und `.skill`-Archive. |
| `mode` | string | Nein | Import-Modus: `create` oder `upsert`. Standard: `create`. |
| `integrationIds` | string | Nein | JSON-kodiertes Array von Integration-UUIDs zum Anhängen, z. B. `["550e8400-e29b-41d4-a716-446655440000"]`. |
## SKILL.md-Format
Der importierte Skill muss YAML-Frontmatter gefolgt von Anweisungen enthalten:
```mdx SKILL.md theme={null}
---
name: Support Reply Style
slug: support-reply-style
description: Applies the support team's tone and escalation rules.
---
Write concise replies, include the next best action, and escalate billing issues to the account owner.
```
| Frontmatter-Feld | Erforderlich | Beschreibung |
| ---------------- | ------------ | ------------------------------------------------------------------------------ |
| `name` | Ja | Skill-Name. Maximum: 64 Zeichen. |
| `slug` | Nein | Stabiler Skill-Slug. Wenn ausgelassen, generiert Langdock einen aus dem Namen. |
| `description` | Nein | Beschreibung, wann der Skill angewendet werden soll. Maximum: 1024 Zeichen. |
| `license` | Nein | Optionale Lizenz-Metadaten. |
## Zip-Archiv-Regeln
Zip-Archive müssen eine `SKILL.md`-Datei im Root oder in einem Top-Level-Verzeichnis enthalten. Langdock speichert erlaubte unterstützende Dateien mit dem Skill und überspringt nicht unterstützte Dateitypen.
| Limit | Wert |
| ------------------------- | ----- |
| Upload-Größe | 25 MB |
| Gesamtgröße unkomprimiert | 20 MB |
| Einzeldateigröße | 5 MB |
| Dateien pro Archiv | 200 |
Unterstützte Dateitypen umfassen Markdown, Text, Python, Shell, JavaScript, TypeScript, JSON, YAML, TOML, CSV, XML, HTML, CSS, SVG, PDF, Office-Dateien, Fonts und gängige Bildformate.
## Import-Modi
| Modus | Verhalten |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create` | Erstellt einen neuen Skill aus dem Import. Die Anfrage schlägt fehl, wenn der Slug bereits existiert. |
| `upsert` | Aktualisiert einen bearbeitbaren Skill mit demselben Slug oder erstellt einen neuen Skill, wenn keiner existiert. Die Anfrage schlägt fehl, wenn mehrere bearbeitbare Skills denselben Slug verwenden. |
Wenn ein Upsert einen bestehenden Skill aktualisiert, ersetzen importierte Dateien die bisher gespeicherten Skill-Dateien.
## Beispiel
```javascript theme={null}
const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");
async function importSkill() {
const form = new FormData();
form.append("file", fs.createReadStream("./support-reply-style.zip"));
form.append("fileType", "zip");
form.append("mode", "upsert");
form.append("integrationIds", JSON.stringify([]));
const response = await axios.post(
"https://api.langdock.com/skills/v1/import",
form,
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
...form.getHeaders()
}
}
);
console.log("Imported Skill:", response.data.skill.id);
}
importSkill();
```
## Antwortformat
### Erfolgsantwort (200 OK oder 201 Created)
```typescript theme={null}
{
skill: {
id: string;
name: string;
slug: string;
description: string;
instructions: string;
integrationIds: string[];
createdAt: string;
updatedAt: string;
};
files: Array<{
path: string;
sizeBytes: number;
extension: string;
hasScript: boolean;
}>;
}
```
`200 OK` bedeutet, dass ein bestehender Skill per `upsert` aktualisiert wurde. `201 Created` bedeutet, dass ein neuer Skill erstellt wurde.
## Fehlerbehandlung
| Statuscode | Beschreibung |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| 400 | Ungültige Form-Daten, ungültige `SKILL.md`, ungültiges Zip-Archiv oder nicht zugängliche `integrationIds` |
| 401 | Ungültiger oder fehlender API Key |
| 403 | Fehlender `SKILL_API` Scope, kein Skills-Produktzugriff, keine Erstellberechtigung oder kein Editor-Zugriff |
| 409 | Bestehender Slug-Konflikt oder mehrdeutiger Upsert-Slug |
| 413 | Hochgeladene Datei ist zu groß |
| 429 | Rate Limit überschritten |
| 500 | Interner Serverfehler |
Langdock blockiert bewusst Browser-basierte Anfragen, um deinen API-Schlüssel zu schützen und die Sicherheit deiner Anwendungen zu gewährleisten. Weitere Informationen findest du in unserem Guide zu [Best Practices für API-Schlüssel](/de/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml POST /skills/v1/import
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/skills/v1/import:
post:
tags:
- Skills
summary: Import a Skill
description: Creates or updates a Skill from a SKILL.md file or zip archive.
operationId: importSkill
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ImportSkillRequest'
responses:
'200':
description: Existing Skill updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImportSkillResponse'
'201':
description: Skill created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ImportSkillResponse'
'400':
description: Invalid form data or zip archive
'401':
description: Invalid or missing API key
'403':
description: Missing required scope or Skill permission
'409':
description: Existing slug conflict or ambiguous upsert slug
'413':
description: Uploaded file is too large
'429':
description: Rate limit exceeded
'500':
description: Internal server error
components:
schemas:
ImportSkillRequest:
type: object
required:
- file
- fileType
properties:
file:
type: string
format: binary
description: SKILL.md, .zip, or .skill file content.
fileType:
type: string
enum:
- md
- zip
description: File parser to use.
mode:
type: string
enum:
- create
- upsert
default: create
description: >-
Whether to create a Skill or update an editable Skill with the same
slug.
integrationIds:
type: string
description: JSON-encoded array of integration UUIDs.
ImportSkillResponse:
type: object
required:
- skill
- files
properties:
skill:
$ref: '#/components/schemas/Skill'
files:
type: array
items:
$ref: '#/components/schemas/ImportedSkillFile'
Skill:
type: object
required:
- id
- name
- slug
- description
- instructions
- integrationIds
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Unique identifier for the Skill.
name:
type: string
maxLength: 64
description: Skill name.
slug:
type: string
maxLength: 100
pattern: ^[a-z0-9-]+$
description: Stable Skill slug.
description:
type: string
maxLength: 1024
description: Description used to explain when the Skill should apply.
instructions:
type: string
maxLength: 50000
description: Skill instructions.
integrationIds:
type: array
items:
type: string
format: uuid
description: >-
Integration IDs attached to the Skill. Each integration must be
enabled in your workspace.
createdAt:
type: string
format: date-time
description: ISO 8601 timestamp for Skill creation.
updatedAt:
type: string
format: date-time
description: ISO 8601 timestamp for the latest Skill update.
ImportedSkillFile:
type: object
required:
- path
- sizeBytes
- extension
- hasScript
properties:
path:
type: string
description: File path inside the imported Skill.
sizeBytes:
type: integer
description: File size in bytes.
extension:
type: string
description: File extension.
hasScript:
type: boolean
description: Whether the file is a script file.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````