Consejos de optimización de descripción de Skills
El campo description es el único criterio para activar un Skill.
Una description bien escrita permite que el Skill se active en el momento correcto y evita que Claude interfiera en escenarios irrelevantes.
Función y limitaciones de Description
Cuando Claude decide si usar un Skill, solo lee el campo description y no lee el contenido de SKILL.md de antemano.
Esto significa que description debe cumplir dos funciones a la vez: explicar qué puede hacer el Skill e indicar cuándo debe usarse.
La longitud ideal de description es de 50 a 150 caracteres. Si es demasiado corta, la activación será imprecisa; si es demasiado larga, puede exceder el límite de contexto y a Claude le resultará difícil escanearla y compararla rápidamente.
Estructura de cuatro elementos de Description
| Elemento | Función | Ejemplo |
|---|---|---|
| Función principal en una frase | Explica de la manera más directa qué es el Skill | "Procesar datos tabulares en formatos Excel y CSV" |
| Lista de capacidades específicas | Enumera de 3 a 5 operaciones típicas | "Incluye limpieza de datos, análisis estadístico y generación de gráficos" |
| Descripción de escenarios de activación | Indica a Claude cuándo debe usarlo | "Activar cuando el usuario mencione análisis de datos, informes o estadísticas" |
| Frase de impulso (opcional) | Resuelve el problema de la "baja tasa de activación" | "Incluso si el usuario no menciona explícitamente el formato, debe usarse siempre que se trate de datos tabulares" |
--- name: data-analyzer description: > 处理 Excel(.xlsx)和 CSV 格式的表格数据,包括数据读取、 清洗去重、统计分析(均值/中位数/分布)、生成可视化报告。 当用户需要分析数据文件、生成统计报告、处理表格、 查找数据规律时应优先使用此 Skill,即使用户只是上传了 一个数据文件并询问"帮我看看这个"。 ---
Problemas comunes al escribir Description
| Problema | Ejemplo (incorrecto) | Enfoque de corrección |
|---|---|---|
| Solo escribe la función, sin el escenario de activación | "Herramienta para analizar datos" | Añade "Activar cuando el usuario..." |
| Descripción demasiado amplia | "Herramienta general para procesar archivos" | Enumera tipos de archivo y operaciones específicos |
| Usa terminología interna de implementación del Skill | "Llamar a pandas para realizar el análisis" | Cambiar a una descripción de negocio desde la perspectiva del usuario |
| Límites poco claros con otros Skills | Dos Skills escriben ambos "procesar documentos" | Distinguir claramente los tipos de archivo o tipos de operación de cada uno |
Optimizar Description con herramientas automatizadas
skill-creator ofrece un script de optimización automática de description que, mediante pruebas iterativas, encuentra la redacción con la tasa de activación más alta.
Paso 1: Preparar casos de prueba
Ejemplo
{
"id": "should_trigger_01",
"prompt": "Ayúdame a analizar ejemplo_sales.csv y encontrar la tendencia de ventas mensual",
"expected": true,
"note": "Solicitud típica de análisis de datos"
},
{
"id": "should_trigger_02",
"prompt": "¿Qué columnas de este archivo de Excel tienen valores vacíos? Ayúdame a contarlas",
"expected": true,
"note": "Implica verificación de calidad de datos"
},
{
"id": "should_not_trigger_01",
"prompt": "¿Cuál es la diferencia entre Excel y CSV?",
"expected": false,
"note": "Pregunta de conocimiento, no necesita Skill"
},
{
"id": "should_not_trigger_02",
"prompt": "Ayúdame a escribir un correo electrónico",
"expected": false,
"note": "Tarea completamente no relacionada"
}
]
Paso 2: Ejecutar el bucle de optimización
Ejemplo
# El script automáticamente: evalúa → modifica → vuelve a evaluar, repitiendo 5 veces
python -m scripts.run_loop \
--eval-set evals/trigger-eval.json \
--skill-path data-analyzer/ \
--model claude-sonnet-4-20250514 \
--max-iterations 5 \
--verbose
迭代 1:训练集得分 0.62,测试集得分 0.60 迭代 2:训练集得分 0.75,测试集得分 0.72 迭代 3:训练集得分 0.87,测试集得分 0.85 迭代 4:训练集得分 0.90,测试集得分 0.88 迭代 5:训练集得分 0.91,测试集得分 0.89 最优 description(测试集得分 0.89)已保存。
Paso 3: Aplicar el mejor resultado
Ejemplo
# Antes de la optimización
grep "description:" data-analyzer/SKILL.md
# Reemplaza manualmente o con un script el contenido de best_description
# Después de reemplazarlo, vuelve a empaquetar el Skill
python -m scripts.package_skill data-analyzer/
Prueba comparativa A/B
Cuando no estés seguro de qué redacción es mejor, puedes realizar una prueba ciega comparativa de las dos versiones de description.
Ejemplo
# Versión B: la nueva description candidata
# Ejecutar evaluaciones por separado
python -m scripts.run_eval \
--eval-set evals/trigger-eval.json \
--skill-path data-analyzer-v1/ \
--output evals/results_v1.json
python -m scripts.run_eval \
--eval-set evals/trigger-eval.json \
--skill-path data-analyzer-v2/ \
--output evals/results_v2.json
# Generar informe comparativo
python eval-viewer/generate_review.py \
--results evals/results_v1.json evals/results_v2.json \
--compare \
--output evals/comparison.html
Otras extensionesLa evaluación debe basarse en la puntuación del conjunto de prueba, no en la del conjunto de entrenamiento. Si la puntuación del conjunto de entrenamiento es alta pero la del conjunto de prueba es baja, significa que description está sobreajustada a los casos de prueba y su rendimiento en escenarios reales puede empeorar.