YouTip

The description field is the sole criterion for Skill triggering. A well-written description enables a Skill to be triggered at the right moment and prevents it from interfering with Claude in irrelevant scenarios. * * * ## The Role and Limitations of Description When deciding whether to use a Skill, Claude only reads the description field and does not read the SKILL.md body in advance. This means the description needs to fulfill two tasks simultaneously: explaining what the Skill can do, and indicating when it should be used. > The ideal length for a description is 50-150 characters. Too short leads to inaccurate triggering, while too long may exceed context limits and make it difficult for Claude to quickly scan and compare. * * * ## The Four-Element Structure of Description | Element | Purpose | Example | | --- | --- | --- | | One-sentence core function | Most directly states what the Skill is | "Process tabular data in Excel and CSV formats" | | Specific capability listing | Lists 3-5 typical operations | "Including data cleaning, statistical analysis, chart generation" | | Trigger scenario description | Tells Claude when to use it | "Trigger when user mentions data analysis, reports, or statistics" | | Push statement (optional) | Solves the "low trigger rate" problem | "Even if user doesn't explicitly mention format, use whenever tabular data is involved" | --- name: data-analyzer description: > Process Excel (.xlsx) and CSV format tabular data, including data reading, cleaning and deduplication, statistical analysis (mean/median/distribution), and generating visual reports. Prioritize using this Skill when the user needs to analyze data files, generate statistical reports, process tables, or discover data patterns, even if the user simply uploads a data file and asks "take a look at this for me".--- * * * ## Common Description Writing Problems | Problem | Example (Incorrect) | Correction Direction | | --- | --- | --- | | Only writes function, not trigger scenario | "A tool for analyzing data" | Add "trigger when user..." | | Description too broad | "A general tool for handling files" | List specific file types and operations | | Uses internal implementation terminology | "Call pandas for analysis" | Change to user-perspective business description | | Unclear boundary with other Skills | Both Skills write "process documents" | Clearly distinguish respective file types or operation types | * * * ## Using Automated Tools to Optimize Description skill-creator provides an automatic description optimization script that finds the highest trigger rate through iterative testing. ### Step 1: Prepare Test Cases ## Example [ { "id":"should_trigger_01", "prompt":"Help me analyze tutorial_sales.csv and find the monthly sales trend", "expected":true, "note":"Typical data analysis request" }, { "id":"should_trigger_02", "prompt":"Which columns in this Excel file have null values? Help me count them", "expected":true, "note":"Involves data quality check" }, { "id":"should_not_trigger_01", "prompt":"What's the difference between Excel and CSV?", "expected":false, "note":"Knowledge Q&A, no Skill needed" }, { "id":"should_not_trigger_02", "prompt":"Help me write an email", "expected":false, "note":"Completely unrelated task" } ] ### Step 2: Run Optimization Loop ## Example # Run automatic description optimization # Script will automatically: evaluate → modify → re-evaluate, loop 5 times python -m scripts.run_loop \ --eval-set evals/