Skip to main content

​
What are Skills?

Skills are modular, self-contained packages that extend DeerFlow’s capabilities by providing specialized knowledge, workflows, and tools. Think of them as “onboarding guides” for specific domains or tasks.

​
What Skills Provide

Specialized Workflows

Multi-step procedures for specific domains

Tool Integrations

Instructions for working with specific file formats or APIs

Domain Expertise

Company-specific knowledge, schemas, business logic

Bundled Resources

Scripts, references, and assets for complex tasks

​
Skill Structure

Every skill consists of a required SKILL.md file and optional bundled resources: 
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/          - Executable code
    ├── references/       - Documentation
    └── assets/           - Output resources

​
SKILL.md Format

Every SKILL.md consists of:
1

Frontmatter (YAML)

Contains name and description fields - the only fields DeerFlow reads to determine when to use the skill.
---
name: pdf-processing
description: Handle PDF documents efficiently. Use when working with PDF files for extraction, rotation, merging, or analysis.
---
The description is critical - it’s the primary triggering mechanism. Include both what the skill does and when to use it.
2

Body (Markdown)

Instructions and guidance loaded AFTER the skill triggers.
# PDF Processing Skill

## Quick Start

Extract text from PDF:
[code example]

## Advanced Features
...

​
Creating a Skill

1

Initialize the Skill

Use the initialization script to create a template:
# From the DeerFlow root directory
python backend/scripts/init_skill.py my-skill --path skills/custom/
This creates:
skills/custom/my-skill/
├── SKILL.md
├── scripts/
│   └── example.py
├── references/
│   └── example.md
└── assets/
    └── example.txt
2

Edit the Frontmatter

Update SKILL.md with your skill’s metadata:
---
name: data-analysis
description: Analyze datasets using pandas and create visualizations. Use when user asks to analyze CSV/Excel files, create charts, or perform statistical analysis.
---
Include all “when to use” information in the description - not in the body. The body is only loaded after triggering.
3

Write Instructions

Add your skill instructions in the Markdown body:
# Data Analysis Skill

## Overview
This skill provides tools and workflows for analyzing datasets.

## Prerequisites
- pandas library available in sandbox
- matplotlib for visualizations

## Quick Start

Load and analyze a CSV:
```python
import pandas as pd
df = pd.read_csv('/mnt/user-data/uploads/data.csv')
print(df.describe())

​
Creating Visualizations

…
</Step>

<Step title="Add Bundled Resources (Optional)">
Add scripts, references, or assets as needed in the skill directory.

**Scripts**: Executable code for deterministic tasks (e.g., `scripts/analyze.py`)

**References**: Documentation loaded on-demand (e.g., `references/sql_schema.md`)

**Assets**: Templates and files used in output (e.g., `assets/report-template.html`)

<Info>
  Bundled resources are loaded on-demand when explicitly referenced in SKILL.md.
</Info>
</Step>

<Step title="Test the Skill">
Test your skill by placing it in the skills directory and using it:

```bash
# Skills are automatically discovered from:
# - skills/public/ (built-in skills)
# - skills/custom/ (user-created skills)
Ask DeerFlow a question that should trigger your skill:
  • “Analyze this dataset for me”
  • “Can you help with data analysis?”

​
Best Practices

​
Keep Skills Concise

Skills share the context window with everything else. Only include information the agent doesn’t already know.✅ Good: Concise examples and specific procedures ❌ Bad: Verbose explanations of basic concepts

​
Progressive Disclosure

Keep SKILL.md under 500 lines. Split content into separate files: Keep your main SKILL.md file concise and reference detailed documentation: 
# BigQuery Skill

## Quick Start
Basic query example...

## Advanced Features
- Finance queries: See references/finance.md
- Sales queries: See references/sales.md  
- Product queries: See references/product.md
The agent loads specific reference files only when they’re needed. The agent loads specific reference files only when needed.

​
Write Effective Descriptions

The description determines when your skill is used: 
---
name: docx-editor
description: Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when working with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks.
---
✅ Includes what it does ✅ Lists specific triggers ✅ Covers multiple use cases

​
Avoid Unnecessary Files

Do NOT create:
  • README.md
  • INSTALLATION_GUIDE.md
  • CHANGELOG.md
  • CONTRIBUTING.md
Skills should only contain information needed for the AI agent to do the job. No auxiliary documentation or setup procedures.

​
Real-World Examples

Learn from existing skills in the DeerFlow repository:

Deep Research

skills/public/deep-research/SKILL.mdSystematic web research methodology

Skill Creator

skills/public/skill-creator/SKILL.mdMeta-skill for creating new skills

PPT Generation

skills/public/ppt-generation/SKILL.mdCreate PowerPoint presentations

Frontend Design

skills/public/frontend-design/SKILL.mdBuild web applications and UIs

​
Packaging Skills

Once your skill is complete, package it for distribution: 
# Package skill into .skill file
python backend/scripts/package_skill.py skills/custom/my-skill

# Specify output directory
python backend/scripts/package_skill.py skills/custom/my-skill ./dist
This:
  1. Validates the skill structure
  2. Checks frontmatter and naming conventions
  3. Creates a .skill file (zip with .skill extension)
The packaging script automatically validates your skill. Fix any errors before the package is created.

​
Installing Custom Skills

Place custom skills in the skills/custom/ directory: 
# Extract .skill file
unzip my-skill.skill -d skills/custom/my-skill

# Or copy skill directory directly
cp -r /path/to/my-skill skills/custom/
Skills are automatically discovered on startup.

​
Managing Skills via API

Enable/disable skills dynamically: 
curl http://localhost:2026/api/skills
Skill state is stored in extensions_config.json.

​
Troubleshooting

Check the description in frontmatter:
  • Is it specific enough?
  • Does it include trigger keywords?
  • Does it match the user’s query?
Test by explicitly asking for the skill:
  • “Use the [skill-name] skill to…”
Verify:
  • Script has correct shebang (#!/usr/bin/env python3)
  • File has execute permissions: chmod +x scripts/script.py
  • Script path is correct in SKILL.md
  • Script is using sandbox virtual paths (/mnt/skills/...)
Ensure:
  • Reference files exist in references/ directory
  • Links in SKILL.md use relative paths
  • File names match exactly (case-sensitive)
Check packaging script output:
python backend/scripts/package_skill.py skills/custom/my-skill
Common issues:
  • Missing required frontmatter fields
  • Invalid YAML syntax
  • Incorrect directory structure

​
Next Steps

Custom Tools

Add custom tools to complement your skills

MCP Servers

Integrate external tools via MCP protocol

Configuration

Learn about skill configuration options

Examples

Browse built-in skills for inspiration

Build docs developers (and LLMs) love

Get started for freeTalk to us