Советы по оптимизации описания навыков

Поле 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: Примените оптимальный результат

Пример

# Скрипт выводит поле best_description; замените им description в SKILL.md
# До оптимизации
grep "description:" data-analyzer/SKILL.md

# Вручную или с помощью скрипта замените его содержимым best_description
# Переупакуйте Skill после замены
python -m scripts.package_skill data-analyzer/

A/B-тестирование

Если вы не уверены, какой стиль написания лучше, можно провести слепое сравнительное тестирование двух версий описания.

Пример

# Версия A: текущее описание
# Версия 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

Оценка должна основываться на показателе на тестовой выборке, а не на обучающей. Если показатель на обучающей выборке высокий, а на тестовой — низкий, это значит, что описание переобучилось на тестовых примерах, и его эффективность в реальных сценариях может ухудшиться.

Другие расширения