# 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 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 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: ```yaml --- 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: ```markdown --- 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: ```markdown ## 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: ```markdown # 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: ```markdown ## 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 ## 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 --- 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 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. *** ### Option 1: Create in Duvo (Recommended for Simple Skills) 1. Go to **Resources** in the left sidebar 2. Click on **Skills and Files** 3. Click **Create Skill** 4. Write or edit the skill content in the editor — the editor starts with a template showing the required frontmatter and structure 5. 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. 6. 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. 7. When the content looks right, click **Create Skill** This approach works well for skills that fit in a single `SKILL.md` file. *** ### Option 2: Upload a Zip File (For Multi-File Skills) Use this approach when your skill includes reference documents, templates, examples, or other supporting files alongside the main `SKILL.md`. **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 **Skills and Files** 3. Click **Upload Skill** 4. Select your zip file *** ### Attach to Assignments Once created or uploaded, 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 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 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 * 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