Creating Skills

Extend DeerFlow with custom skills for specialized workflows

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

Why conciseness matters

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:

Good Descriptions

---
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

Bad Descriptions

---
name: docx-editor
description: Handle Word documents
---

❌ Too vague ❌ Missing triggers ❌ Doesn’t explain capabilities

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.md

Systematic web research methodology

Skill Creator

skills/public/skill-creator/SKILL.md

Meta-skill for creating new skills

PPT Generation

skills/public/ppt-generation/SKILL.md

Create PowerPoint presentations

Frontend Design

skills/public/frontend-design/SKILL.md

Build 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:

List Skills

curl http://localhost:2026/api/skills

curl -X PUT http://localhost:2026/api/skills/my-skill \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

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

Skill state is stored in extensions_config.json.

Troubleshooting

Skill not triggering

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…”

Scripts not executing

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/...)

References not loading

Ensure:

• Reference files exist in references/ directory
• Links in SKILL.md use relative paths
• File names match exactly (case-sensitive)

Validation fails

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