Creating Custom Skills

Introduction

Custom skills let you package your team's unique expertise into reusable capabilities that your assignments can use. Think of a skill as an onboarding guide you'd give to a new team member—it contains the knowledge, processes, and best practices they need to handle a specific type of task.

Skills are created outside of Duvo and uploaded as files. This guide explains how to structure your skill so assignments 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 assignment, 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:

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

---
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 assignment 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 assignment can look up

How to Reference Additional Files

In your main SKILL.md, reference other files when relevant:

## Eligibility Rules
For detailed eligibility criteria, see [ELIGIBILITY.md](ELIGIBILITY.md).

## Response Templates
Standard response templates are available in [TEMPLATES.md](TEMPLATES.md).

---

Writing Effective Skill Content

Use Clear Structure

Organize your content with headings and sections:

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

Less effective:

Handle customer complaints professionally.

More effective:

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:

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

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

---
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](TONE-GUIDE.md).

For examples of on-brand communications, see the [examples/](examples/) folder.

---

How to Upload Your Skill

Step 1: Create Your Skill Folder

Create a folder on your computer with your SKILL.md file and any additional files.

Step 2: Zip the Folder

Compress the folder into a zip file:

• Windows: Right-click the folder → Send to → Compressed (zipped) folder

• Mac: Right-click the folder → Compress

Step 3: Upload to Duvo

1. Go to Resources in the left sidebar

2. Click on Files

3. Select the Skills tab

4. Click Upload Skill

5. Select your zip file

Step 4: Attach to Assignments

Once uploaded, you can attach the skill to any assignment:

1. Open the assignment

2. Find the Skills section in settings

3. Select your custom skill

4. Save changes

---

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 Like You're Training Someone

Imagine explaining this to a capable new hire 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 assignments:

1. Attach it to a test assignment

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

Skill Not Working as Expected

• Check your description: Is it clear about when to use the skill?

• Review your instructions: Are they specific enough?

• Add more examples: Sometimes the assignment needs to see what good looks like

Assignment Ignoring Parts of the Skill

• 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

Content Too Long

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 assignment

• Upload skills as zip files containing the skill folder

• Delete and re-upload to update a skill's content