Skills API - DeerFlow

Overview

The Skills API provides endpoints to list, retrieve, enable/disable, and install skills. Skills are extensions that provide specialized instructions and workflows to AI agents.

List All Skills

GET /api/skills

Retrieve a list of all available skills from both public and custom directories

Response

skills

array

List of all skills regardless of enabled status

Show Skill Object

name

string

required

Name of the skill (hyphen-case format)

description

string

required

Description of what the skill does

license

string

License information (e.g., MIT, Apache-2.0)

Example Request

curl http://localhost:8001/api/skills

Example Response

{
  "skills": [
    {
      "name": "mintlify",
      "description": "Comprehensive reference for building Mintlify documentation sites",
      "license": "MIT",
      "category": "public",
      "enabled": true
    },
    {
      "name": "pdf-processing",
      "description": "Extract and analyze PDF content",
      "license": null,
      "category": "custom",
      "enabled": false
    }
  ]
}

Get Skill Details

GET /api/skills/{skill_name}

Retrieve detailed information about a specific skill by its name

Path Parameters

skill_name

string

required

The name of the skill to retrieve

Response

name

string

required

Name of the skill

description

string

required

Description of what the skill does

license

string

License information

Example Request

curl http://localhost:8001/api/skills/mintlify

Example Response

{
  "name": "mintlify",
  "description": "Comprehensive reference for building Mintlify documentation sites",
  "license": "MIT",
  "category": "public",
  "enabled": true
}

Error Responses

404

Not Found

Skill not found

{
  "detail": "Skill 'invalid-skill' not found"
}

Update Skill

PUT /api/skills/{skill_name}

Update a skill’s enabled status by modifying the extensions_config.json file

Path Parameters

skill_name

string

required

The name of the skill to update

Request Body

enabled

boolean

required

Whether to enable or disable the skill

Response

Returns the updated skill object (same as GET /api/skills/).

Example Request

curl -X PUT http://localhost:8001/api/skills/mintlify \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Example Response

{
  "name": "mintlify",
  "description": "Comprehensive reference for building Mintlify documentation sites",
  "license": "MIT",
  "category": "public",
  "enabled": false
}

Error Responses

404

Not Found

Skill not found

500

Internal Server Error

Failed to update skill configuration

Notes

This endpoint modifies the extensions_config.json file
The SKILL.md file itself is not modified
Changes take effect immediately for new conversations

Install Skill

POST /api/skills/install

Install a skill from a .skill file (ZIP archive) located in the thread’s user-data directory

Request Body

thread_id

string

required

The thread ID where the .skill file is located

path

string

required

Virtual path to the .skill file (e.g., /mnt/user-data/outputs/my-skill.skill)

Response

success

boolean

required

Whether the installation was successful

skill_name

string

required

Name of the installed skill

message

string

required

Installation result message

Example Request

curl -X POST http://localhost:8001/api/skills/install \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "abc123-def456",
    "path": "/mnt/user-data/outputs/my-skill.skill"
  }'

Example Response

{
  "success": true,
  "skill_name": "my-skill",
  "message": "Skill 'my-skill' installed successfully"
}

Error Responses

400

Bad Request

Invalid .skill file or validation error

{
  "detail": "Invalid skill: Missing 'name' in frontmatter"
}

403

Forbidden

Access denied (path traversal detected)

404

Not Found

Skill file not found

{
  "detail": "Skill file not found: /mnt/user-data/outputs/my-skill.skill"
}

409

Conflict

Skill already exists

{
  "detail": "Skill 'my-skill' already exists. Please remove it first or use a different name."
}

.skill File Format

A .skill file is a ZIP archive containing:

SKILL.md (required): Markdown file with YAML frontmatter
scripts/: Optional directory with executable scripts
references/: Optional directory with reference documentation
assets/: Optional directory with images, templates, etc.

SKILL.md Frontmatter

---
name: my-skill
description: Description of what this skill does
license: MIT
allowed-tools:
  - read
  - write
  - bash
metadata:
  author: Your Name
  version: 1.0.0
---

# Skill Instructions

Your skill content here...

Naming Requirements

Must be hyphen-case (lowercase letters, digits, and hyphens only)
Cannot start or end with hyphen
Cannot contain consecutive hyphens
Maximum 64 characters
Must be unique (no duplicates)

Validation Rules

The API validates:

File extension: Must be .skill
ZIP format: Must be a valid ZIP archive
SKILL.md exists: Required file with frontmatter
Required fields: name and description in frontmatter
Name format: Must follow hyphen-case convention
Description: No angle brackets, max 1024 characters
No duplicates: Skill name must not already exist

Skill Categories

Public Skills

Public skills are bundled with DeerFlow and located in the skills/public/ directory. These are maintained by the DeerFlow team.

Custom Skills

Custom skills are user-created and installed in the skills/custom/ directory. These can be installed via the API or manually placed in the directory.

Use Cases

List Available Skills

const response = await fetch('http://localhost:8001/api/skills');
const { skills } = await response.json();

// Filter by category
const publicSkills = skills.filter(s => s.category === 'public');
const customSkills = skills.filter(s => s.category === 'custom');

// Filter enabled skills
const enabledSkills = skills.filter(s => s.enabled);

Toggle Skill Status

async function toggleSkill(skillName: string, enabled: boolean) {
  const response = await fetch(`http://localhost:8001/api/skills/${skillName}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ enabled })
  });
  return response.json();
}

Install Custom Skill

async function installSkill(threadId: string, skillPath: string) {
  const response = await fetch('http://localhost:8001/api/skills/install', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      thread_id: threadId,
      path: skillPath
    })
  });
  return response.json();
}

Creating Skills

Learn how to create custom skills

Gateway Overview

Learn about the Gateway API

Python Client

Gateway API

LangGraph API

Agent Tools

​Overview

​List All Skills

GET /api/skills

​Response

​Example Request

​Example Response

​Get Skill Details

GET /api/skills/{skill_name}

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Update Skill

PUT /api/skills/{skill_name}

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Notes

​Install Skill

POST /api/skills/install

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​.skill File Format

​SKILL.md Frontmatter

​Naming Requirements

​Validation Rules

​Skill Categories

​Public Skills

​Custom Skills

​Use Cases

​List Available Skills

​Toggle Skill Status

​Install Custom Skill

​Related

Creating Skills

Gateway Overview

Build docs developers (and LLMs) love

Overview

List All Skills

Response

Example Request

Example Response

Get Skill Details

Path Parameters

Response

Example Request

Example Response

Error Responses

Update Skill

Path Parameters

Request Body

Response

Example Request

Example Response

Error Responses

Notes

Install Skill

Request Body

Response

Example Request

Example Response

Error Responses

.skill File Format

SKILL.md Frontmatter

Naming Requirements

Validation Rules

Skill Categories

Public Skills

Custom Skills

Use Cases

List Available Skills

Toggle Skill Status

Install Custom Skill

Related