> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating Custom Skills
> Package your team's expertise into reusable skills—author them in Duvo with the built-in editor or upload a multi-file zip.
Custom skills let you package your team's unique expertise into reusable capabilities that your agents can use. Think of a skill as a reference document—it contains the knowledge, processes, and best practices needed to handle a specific type of task.
You can create a skill directly in Duvo using the built-in editor—optionally with AI to generate a first draft from a short description—or upload a zip file for more complex skills that include multiple reference documents. This page explains how to structure your skill so agents can use it effectively.
## What is a Skill?
A skill is a folder (uploaded as a zip file) containing:
1. **A main instruction file** (`SKILL.md`) - Required. Contains the core knowledge and guidance.
2. **Supporting files** - Optional. Additional documents, templates, examples, or reference materials.
When you attach a skill to an agent, it gains access to all the expertise contained in that skill folder.
## The SKILL.md File
Every skill must have a file named `SKILL.md` at the root of the folder. This file has two parts:
### Part 1: Frontmatter (Metadata)
At the very top of the file, include metadata between triple dashes:
```yaml theme={"dark"}
---
name: your-skill-name
description: A clear description of what this skill does and when to use it.
---
```
**name** (required)
* Use lowercase letters, numbers, and hyphens only
* Maximum 64 characters
* Examples: `expense-policy`, `brand-voice`, `invoice-processing`
**description** (required)
* Explain what the skill does AND when to use it
* Maximum 1024 characters
* This description helps the agent understand when to apply this expertise
**Good description example:**
```
description: Guidelines for processing customer refund requests. Use when handling refund emails, evaluating refund eligibility, or drafting refund approval/denial responses.
```
### Part 2: Content (Instructions)
After the frontmatter, write your skill content using Markdown formatting:
```markdown theme={"dark"}
---
name: refund-processing
description: Guidelines for processing customer refund requests. Use when handling refund emails, evaluating refund eligibility, or drafting refund responses.
---
# Refund Processing Guidelines
## Overview
This skill provides guidance for handling customer refund requests according to company policy.
## Eligibility Criteria
- Request must be within 30 days of purchase
- Product must be unused or defective
- Original receipt or order number required
## Processing Steps
1. Verify the purchase in the order system
2. Check if the request meets eligibility criteria
3. If eligible, process the refund
4. If not eligible, draft a polite explanation
## Response Templates
### Approved Refund
"Thank you for contacting us. We've processed your refund of [amount]..."
### Denied Refund
"Thank you for your request. Unfortunately..."
```
## Skill Folder Structure
For simple skills, you only need the `SKILL.md` file:
```
my-skill/
└── SKILL.md
```
For more complex skills, include additional files:
```
refund-processing/
├── SKILL.md (main instructions - required)
├── ELIGIBILITY.md (detailed eligibility rules)
├── TEMPLATES.md (response templates)
├── examples/
│ ├── approved-example.md
│ └── denied-example.md
└── reference/
└── policy-document.pdf
```
### Why Use Multiple Files?
Breaking your skill into multiple files has benefits:
* **Focused content**: Each file covers one specific topic
* **Efficient loading**: The agent only loads files it needs for the current task
* **Easier maintenance**: Update individual sections without rewriting everything
* **Reference materials**: Include policies, schemas, or examples the agent can look up
### How to Reference Additional Files
In your main `SKILL.md`, reference other files when relevant:
```markdown theme={"dark"}
## Eligibility Rules
For detailed eligibility criteria, see `ELIGIBILITY.md`.
## Response Templates
Standard response templates are available in `TEMPLATES.md`.
```
## Writing Effective Skill Content
### Use Clear Structure
Organize your content with headings and sections:
```markdown theme={"dark"}
# Skill Name
## Overview
Brief explanation of what this skill covers.
## Key Concepts
Important terms or ideas to understand.
## Step-by-Step Process
1. First step
2. Second step
3. Third step
## Examples
Concrete examples of good outputs.
## Common Mistakes to Avoid
What not to do.
## Edge Cases
How to handle unusual situations.
```
### Write for Action
Skills should provide **actionable guidance**. Instead of vague statements, give specific instructions:
```text Less effective theme={"dark"}
Handle customer complaints professionally.
```
```text More effective theme={"dark"}
When handling customer complaints:
1. Acknowledge their frustration
2. Apologize for the inconvenience
3. Ask clarifying questions to understand the issue
4. Propose a specific solution
5. Follow up within 24 hours
```
### Include Examples
Examples are incredibly valuable. Show what good looks like:
```markdown theme={"dark"}
## Example: Responding to a Late Delivery Complaint
**Customer message:**
"My order was supposed to arrive yesterday and it still hasn't come!"
**Good response:**
"I'm sorry to hear your order hasn't arrived yet. That's frustrating,
and I want to help resolve this. Let me look up your order status right now.
Could you please provide your order number? I'll track it down and
get you an update within the hour."
```
### Define Terminology
If your skill uses specific terms or jargon, define them:
```markdown theme={"dark"}
## Key Terms
- **SKU**: Stock Keeping Unit - the unique product identifier
- **PO**: Purchase Order - the document requesting goods from a supplier
- **Net 30**: Payment terms requiring payment within 30 days
```
## Complete Example: Brand Voice Skill
Here's a complete example of a well-structured skill:
**Folder structure:**
```
brand-voice/
├── SKILL.md
├── TONE-GUIDE.md
└── examples/
├── email-examples.md
└── social-examples.md
```
**SKILL.md:**
```markdown theme={"dark"}
---
name: brand-voice
description: Company brand voice and communication guidelines. Use when writing any customer-facing content, emails, social media posts, or marketing materials.
---
# Brand Voice Guidelines
## Overview
This skill ensures all communications reflect our brand personality: friendly, professional, and helpful.
## Our Voice Principles
### 1. Friendly but Professional
- Use conversational language, not corporate jargon
- Write like you're helping a friend, but maintain professionalism
- Contractions are fine ("we're" instead of "we are")
### 2. Clear and Direct
- Get to the point quickly
- Use simple words over complex ones
- Break up long paragraphs
### 3. Empathetic
- Acknowledge the customer's situation
- Show you understand their perspective
- Focus on solutions, not problems
## Words to Use
- "Happy to help"
- "Let me take care of that"
- "Great question"
- "Here's what we can do"
## Words to Avoid
- "Unfortunately" (too negative)
- "Policy" (sounds bureaucratic)
- "Actually" (can sound condescending)
- "Per my last email" (passive aggressive)
## Detailed Guidelines
For comprehensive tone guidance, see `TONE-GUIDE.md`.
For examples of on-brand communications, see the [examples/](examples/) folder.
```
## How to Create a Skill
You can create a custom skill two ways: directly in the Duvo interface, or by uploading a zip file for more complex skills with multiple reference files.
Recommended for simple skills that fit in a single `SKILL.md` file.
Go to **Resources** in the left sidebar.
Click on **Skills and Files**.
Click **Create Skill**.
Write or edit the skill content in the editor — the editor starts with a template showing the required frontmatter and structure.
To generate skill content with AI, type a description of what your skill should do in the **Generate with AI** field and press Enter or click **Generate**. Review and edit the generated content before saving.
Once you have content in the editor, the AI field switches to **Edit with AI** mode. Describe what you want to change (for example, "add a section on escalation steps") and press Enter or click **Edit** to refine the existing content.
When the content looks right, click **Create Skill**.
Use this approach for multi-file skills, when your skill includes reference documents, templates, examples, or other supporting files alongside the main `SKILL.md`.
Create a folder on your computer with your `SKILL.md` file and any additional files.
Compress the folder into a zip file:
* **Windows**: Right-click the folder → Send to → Compressed (zipped) folder
* **Mac**: Right-click the folder → Compress
1. Go to **Resources** in the left sidebar
2. Click on **Skills and Files**
3. Click **Upload Skill**
4. Select your zip file
### Attach to Agents
Once created or uploaded, attach the skill to any agent:
Open the agent.
Find the Skills section in settings.
Select your custom skill.
Save changes.
### Editing Shared Skills
If you edit a skill that is used by more than one agent, Duvo will ask you to confirm before saving. A dialog shows how many agents will be affected and lets you expand the list to see which ones. This gives you a chance to review the impact before your changes apply everywhere. Click **Save changes** to proceed or **Cancel** to go back and edit.
## Best Practices
### Keep Skills Focused
One skill should cover one area of expertise. Instead of creating a massive "Customer Service" skill, create focused skills:
* `complaint-handling`
* `refund-processing`
* `escalation-procedures`
### Write Clear, Step-by-Step Instructions
Imagine explaining this to a capable person who knows nothing about your specific processes. What would they need to know?
### Include What to Do AND What Not to Do
Don't just explain the happy path. Include:
* Common mistakes to avoid
* Red flags to watch for
* When to escalate or ask for help
### Test Before Deploying
Before relying on a skill for important agents:
1. Attach it to a test agent
2. Run several scenarios
3. Check that the outputs match your expectations
4. Refine the skill content if needed
### Keep Skills Updated
Review your skills periodically:
* Do they reflect current processes?
* Have policies or guidelines changed?
* Are there new edge cases to address?
## Troubleshooting
* **Check your description**: Is it clear about when to use the skill?
* **Review your instructions**: Are they specific enough?
* **Add more examples**: Sometimes the agent needs to see what good looks like
* Break long sections into separate files
* Use clear headings so relevant sections are easy to find
* Make sure important instructions aren't buried in walls of text
If your skill is very large:
* Split it into multiple files with clear references
* Move detailed reference material to separate documents
* Keep the main `SKILL.md` focused on core guidance
## Things to Know
* Skills must have a `SKILL.md` file with proper frontmatter
* Use lowercase letters, numbers, and hyphens for the skill name
* Custom skills are private to your team
* You can attach multiple skills to one agent
* Simple skills can be created directly in Duvo using the **Create Skill** button; complex multi-file skills should be uploaded as a zip file using **Upload Skill**
* AI generation produces a draft based on your description—always review and edit before creating
* Once content is in the editor, use **Edit with AI** to refine it by describing the changes you want
* Delete and re-upload (or recreate) to update a skill's content