Import Skill

Imports a Skill from a SKILL.md file or a zip archive. Use this endpoint to sync repository-managed Skills into Langdock.

Base URL

https://api.langdock.com/skills/v1/import

Dedicated deploymentsReplace api.langdock.com with <your-deployment-url>/api/public in all requests.

Required Scopes

This endpoint requires the SKILL_API scope.

Creating a new Skill requires the createSkills workspace permission. Updating an existing Skill with mode: "upsert" requires editor access to the matching Skill.

Request Format

Send the request as multipart/form-data.

Field	Type	Required	Description
`file`	file	Yes	`SKILL.md`, `.zip`, or `.skill` file content.
`fileType`	string	Yes	File parser to use: `md` or `zip`. Use `zip` for `.zip` and `.skill` archives.
`mode`	string	No	Import mode: `create` or `upsert`. Default: `create`.
`integrationIds`	string	No	JSON-encoded array of integration UUIDs to attach, for example `["550e8400-e29b-41d4-a716-446655440000"]`.

SKILL.md Format

The imported Skill must include YAML frontmatter followed by instructions:

SKILL.md

---
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 Field	Required	Description
`name`	Yes	Skill name. Maximum: 64 characters.
`slug`	No	Stable Skill slug. If omitted, Langdock generates one from the name.
`description`	No	Description used to explain when the Skill should apply. Maximum: 1024 characters.
`license`	No	Optional license metadata.

Zip archive rules

Zip archives must contain a SKILL.md file at the root or inside one top-level directory. Langdock stores allowed supporting files with the Skill and skips unsupported file types.

Limit	Value
Upload size	25 MB
Total uncompressed size	20 MB
Individual file size	5 MB
Files per archive	200

Supported supporting file types include Markdown, text, Python, shell, JavaScript, TypeScript, JSON, YAML, TOML, CSV, SQL, XML, HTML, CSS, SVG, PDF, Office files, fonts, and common image formats.

Import Modes

Mode	Behavior
`create`	Creates a new Skill from the import. The request fails if the slug already exists.
`upsert`	Updates one editable Skill with the same slug, or creates a new Skill if none exists. The request fails if multiple editable Skills use the same slug.

When an upsert updates an existing Skill, imported files replace the Skill’s existing stored files.

Example

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();

Response Format

Success Response (200 OK or 201 Created)

{
  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 means an existing Skill was updated through upsert. 201 Created means a new Skill was created.

Error Handling

Status Code	Description
400	Invalid form data, invalid `SKILL.md`, invalid zip archive, or inaccessible `integrationIds`
401	Invalid or missing API key
403	Missing `SKILL_API` scope, Skills product access, create permission, or editor access
409	Existing slug conflict or ambiguous upsert slug
413	Uploaded file is too large
429	Rate limit exceeded
500	Internal server error

Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

Overview

Completion API

Embedding API

Agents API

Integrations API

Skills API

Knowledge Folder API

Prompt Library API

Usage Export API

Workflow API

Scheduled Tasks API

User Management API

Billing API

Audit Logs API

Governance API

Compliance API

Import Skill

Base URL

Required Scopes

Request Format

SKILL.md Format

Zip archive rules

Import Modes

Example

Response Format

Success Response (200 OK or 201 Created)

Error Handling

​Base URL

​Required Scopes

​Request Format

​SKILL.md Format

​Zip archive rules

​Import Modes

​Example

​Response Format

​Success Response (200 OK or 201 Created)

​Error Handling

Base URL

Required Scopes

Request Format

SKILL.md Format

Zip archive rules

Import Modes

Example

Response Format

Success Response (200 OK or 201 Created)

Error Handling