Навык бесполезен, если Claude не понимает, когда его доставать. А решает он это по одному полю — description. Описание работает как триггер: агент сопоставляет твою задачу с описаниями всех навыков и подгружает тот, что подходит. Поэтому хорошее описание говорит не «что делает навык», а когда его применять.
Плохой триггер
description: Отчёты.
Слишком обще. Claude не поймёт, отчёт о чём, в какой момент и по какому поводу. Навык либо не сработает, либо вылезет невпопад.
Хороший триггер
description: Оформляет отчёт о проделанной работе по нашему внутреннему шаблону. Применяй, когда просят подвести итоги спринта, собрать changelog или отчитаться о сделанном за период.
Здесь есть и предмет, и сигналы-поводы: «итоги спринта», «changelog», «отчитаться за период». Когда в разговоре всплывёт что-то из этого, Claude узнает повод и подтянет навык.
Правила хорошего description
- Назови задачу и условия, при которых навык нужен («когда…», «если просят…»).
- Вставь слова-маяки, которыми люди реально описывают эту работу.
- Не делай описание слишком широким — иначе навык будет срабатывать на всё подряд и мешать.
- Не делай слишком узким — иначе он не включится, когда реально нужен.
Проверь себя так: прочитай только description (без тела) и спроси — «по этой фразе понятно, в какой момент доставать навык?». Если да — триггер настроен.
Остальное — тело SKILL.md — Claude прочитает уже после того, как триггер сработал. Поэтому львиная доля пользы навыка зависит от одной точной строки описания.