YouTip

Skill Description is the most important part of a skill, as it determines whether the agent can correctly recognize when to activate the skill. This section will teach you how to write effective skill descriptions. * * * ## Why Description is Important Skill descriptions play a key role during the agent's skill loading process: * In the discovery phase, the agent only loads each skill's name and description * The description is the main basis for the agent to determine whether to activate the skill * A good description can improve the skill activation accuracy If the description is poorly written, the agent may: * Activate the skill when it's not needed (false positive) * Fail to activate the skill when it's needed (false negative) * Activate the wrong skill > Tip: The quality of skill description directly affects the skill's usability. Investing time in optimizing the description is worth it. * * * ## Basic Structure of Description A good skill description should contain two parts: 1. **Function Description**: Describes what the skill can do 2. **Trigger Conditions**: Explains under what circumstances to use it description: Extract text and tables from PDF files, fill PDF forms, merge multiple PDFs. Used when processing PDF documents or when users mention PDF, forms, or document extraction.# ↑ Function Description ↑ Trigger Conditions * * * ## Tips for Writing Effective Descriptions ### 1. Include Specific Trigger Keywords Include specific words and phrases that users might use in the description. These keywords help the agent recognize related tasks. Good description: description: Extract PDF text and tables, fill forms, merge PDFs. Use cases: processing PDF files, extracting document content, filling PDF forms, merging multiple PDFs, when users mention keywords like "PDF", "extract", "form", "merge". ### 2. Be Specific Rather Than General Avoid using overly broad descriptions, as this will prevent the agent from making accurate judgments. # Bad Description - Too General description: Help process various files.# Good Description - Specific and Clear description: Process image files, including resizing, applying filters, converting formats. Use cases: processing images, resizing images, converting image formats. ### 3. Describe Multiple Use Cases List different scenarios where the skill might be applicable to help the agent match more accurately. description: Perform code reviews, check for security vulnerabilities, code quality, and performance issues. Use cases: code review, PR review, code inspection, security scanning, quality assessment, when users mention "review", "check code", "security". ### 4. Differentiate Similar Skills If you have multiple related skills, ensure their descriptions are clearly different. # Skill 1: PDF Text Extraction name: pdf-extract description: Extract text content and table data from PDF files. Use cases: extracting PDF text, reading PDF content, PDF to text, when users mention "PDF extraction", "read PDF".# Skill 2: PDF Form Processing name: pdf-form description: Fill PDF form fields, extract form data. Use cases: filling PDF forms, filling form fields, PDF form data processing, when users mention "PDF form", "fill form". * * * ## Description Length Control The maximum length of the description field is 1024 characters. However, this is not the target - the description should be concise and accurate. | Situation | Recommended Length | | --- | --- | | Simple Skill | 50-100 characters | | Medium Complexity Skill | 100-200 characters | | Complex Skill | 200-400 characters | > Note: Longer is not better. An overly long description may contain too much irrelevant information, which caninstead interfere with the agent's judgment. * * * ## Testing and Optimizing Descriptions After creating a skill, you should test whether the description can correctly trigger the skill. Here are the testing steps: ### 1. Basic Function Testing Test using the keywords included in the description to confirm the skill can be activated. ### 2. Edge Case Testing Test some scenarios that might trigger but shouldn't. ### 3. Iterative Optimization Adjust the description based on test results: * If false positives increase: Add more limiting conditions to the description * If false negatives increase: Add more possible trigger words to the description * If wrong skill is activated: Ensure the description is sufficiently differentiated from similar skills Optimization example: # Initial Version - May Have False Negatives description: Extract PDF text.# Optimized Version - Reduce False Negatives description: Extract text content and table data from PDF files. Use cases: extracting PDF text, reading PDF content, PDF to text.# Final Version - Further Optimized description: Extract text content and table data from PDF files. Use cases: extracting PDF text, reading PDF content, PDF to text, when users mention keywords like "PDF extraction", "read PDF", "PDF text", "PDF content". * * * ## Common Problems and Solutions ### Problem 1: Skill Always Gets Activated This indicates the description is too broad. The solution is to add more limiting conditions and use cases. Solution: # Before Modification - Too Broad description: Process text.# After Modification - More Specific description: Use regular expressions to process and transform text strings. Use cases: text matching, string replacement, pattern extraction, data cleaning. ### Problem 2: Skill Never Gets Activated This indicates the description is missing keywords that users might use. The solution is to add more trigger words. Solution: # Before Modification - Too Few Keywords description: Optimize database queries.# After Modification - Add More Trigger Words description: Optimize SQL query performance, analyze execution plans, add indexes. Use cases: SQL optimization, slow queries, database performance, tuning indexes, execution plan analysis. ### Problem 3: Wrong Skill Gets Activated This indicates multiple skills' descriptions are too similar. The solution is to make the descriptions more differentiated. > Tip: Regularly testing and optimizing your skill descriptions is a good habit. As use cases increase, you may find that descriptions need adjustment.