Skills API

Manage skills and their enabled status

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)

category · string · required

Category of the skill: public or custom

enabled · boolean · default: "true"

Whether this skill is enabled

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

category · string · required

Category: public or custom

enabled · boolean · required

Whether this skill is enabled

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:

1. File extension: Must be .skill
2. ZIP format: Must be a valid ZIP archive
3. SKILL.md exists: Required file with frontmatter
4. Required fields: name and description in frontmatter
5. Name format: Must follow hyphen-case convention
6. Description: No angle brackets, max 1024 characters
7. 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();
}

---

Related

Creating Skills

Learn how to create custom skills

Gateway Overview

Learn about the Gateway API