Советы по оптимизации описания навыков
Поле description — единственная основа для определения, срабатывает ли навык.
Хорошо написанное описание позволяет навыку срабатывать в нужный момент и не мешать Claude в нерелевантных сценариях.
Роль и ограничения описания
При принятии решения об использовании навыка Claude читает только поле description и не читает содержимое SKILL.md заранее.
Это означает, что описание должно одновременно выполнять две задачи: объяснять, что может делать навык, и указывать, когда его следует использовать.
Идеальная длина описания — 50-150 символов. Слишком короткое приводит к неточному срабатыванию; слишком длинное может превысить лимиты контекста, и Claude будет сложно быстро просматривать и сравнивать.
Структура описания из четырёх элементов
| Элемент | Назначение | Пример |
|---|---|---|
| Основная функция в одном предложении | Наиболее прямо указывает, что представляет собой навык | "Обрабатывает данные электронных таблиц в форматах Excel и CSV" |
| Список конкретных возможностей | Перечислите 3-5 типичных операций | "Включая очистку данных, статистический анализ, построение диаграмм" |
| Описание сценария срабатывания | Указывает Claude, когда его следует использовать | "Срабатывать, когда пользователь упоминает анализ данных, отчёты или статистику" |
| Рекламное утверждение (опционально) | Решает проблему "низкой частоты срабатывания" | "Даже если пользователь явно не упоминает формат, его следует использовать всякий раз, когда задействованы табличные данные" |
--- name: data-analyzer description: > 处理 Excel(.xlsx)和 CSV 格式的表格数据,包括数据读取、 清洗去重、统计分析(均值/中位数/分布)、生成可视化报告。 当用户需要分析数据文件、生成统计报告、处理表格、 查找数据规律时应优先使用此 Skill,即使用户只是上传了 一个数据文件并询问"帮我看看这个"。 ---
Распространённые проблемы при написании описаний
| Проблема | Пример (неправильно) | Направление исправления |
|---|---|---|
| Описываются только функции, без сценариев срабатывания | "Инструмент для анализа данных" | Добавьте "срабатывание, когда пользователь..." |
| Описание слишком общее | "Универсальный инструмент для обработки файлов" | Перечислите конкретные типы файлов и операции |
| Использование внутренней терминологии реализации Skill | "Вызов pandas для анализа" | Замените на бизнес-описание с точки зрения пользователя |
| Нечёткие границы с другими Skills | В обоих Skills сказано "обрабатывать документы" | Чётко разграничьте типы файлов или типы операций для каждого |
Оптимизация описания с помощью автоматизированных инструментов
skill-creator предоставляет скрипт автоматической оптимизации описания, который использует итеративное тестирование для поиска стиля написания с наивысшей частотой срабатывания.
Шаг 1: Подготовьте тестовые случаи
Пример
{
"id": "should_trigger_01",
"prompt": "Помогите мне проанализировать example_sales.csv и найти тенденцию месячных продаж",
"expected": true,
"note": Типичный запрос на анализ данных
},
{
"id": "should_trigger_02",
"prompt": "В каких столбцах этого файла Excel есть пустые значения? Помогите мне посчитать их.",
"expected": true,
"note": Включает проверку качества данных
},
{
"id": "should_not_trigger_01",
"prompt": "В чём разница между Excel и CSV?",
"expected": false,
"note": Вопросы и ответы по знаниям, Skill не требуется
},
{
"id": "should_not_trigger_02",
"prompt": "Помогите мне написать письмо",
"expected": false,
"note": Полностью несвязанная задача
}
]
Шаг 2: Запуск цикла оптимизации
Пример
# Скрипт будет автоматически: оценивать → изменять → переоценивать, повторяя цикл 5 раз
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)已保存。
Шаг 3: Примените оптимальный результат
Пример
# До оптимизации
grep "description:" data-analyzer/SKILL.md
# Вручную или с помощью скрипта замените его содержимым best_description
# Переупакуйте Skill после замены
python -m scripts.package_skill data-analyzer/
A/B-тестирование
Если вы не уверены, какой стиль написания лучше, можно провести слепое сравнительное тестирование двух версий описания.
Пример
# Версия B: новое описание-кандидат
# Запускать оценки отдельно
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
# Сгенерировать сравнительный отчёт
python eval-viewer/generate_review.py \
--results evals/results_v1.json evals/results_v2.json \
--compare \
--output evals/comparison.html
Другие расширенияОценка должна основываться на показателе на тестовой выборке, а не на обучающей. Если показатель на обучающей выборке высокий, а на тестовой — низкий, это значит, что описание переобучилось на тестовых примерах, и его эффективность в реальных сценариях может ухудшиться.