Правильный способ использования функции Skill: пять размышлений после публикации Anthropic внутренней методологии

Автор: Ай-продукт Айнь

Прочитал блог-статью команды Anthropic «Уроки создания Claude Code: как мы используем навыки». На сегодняшний день это, пожалуй, самое глубокое практическое резюме по теме «навыки», которое мне попадалось.

Сама концепция «навыка» не так уж сложна, однако добиться действительно качественной реализации навыка — задача отнюдь не тривиальная.

Помню, как в период всплеска популярности навыков все с энтузиазмом создавали самые разные «навыки стиля письма» и «навыки написания текстов». Казалось, что стоит лишь заложить в модель собственный стиль письма — и она будет стабильно генерировать тексты в этом стиле.

Однако, когда я сам попробовал реализовать подобные навыки, выяснилось, что на практике это зачастую просто неработоспособно.

Дело в том, что один «навык стиля письма» может содержать несколько тысяч или даже десятки тысяч знаков. При загрузке такого навыка значительная часть контекста сразу же заполняется. Чем больше объём контекста, тем сильнее снижается способность модели к рассуждению.

В результате часто возникает парадоксальная ситуация: стиль действительно усвоен, но содержание становится поверхностным, а аналитические способности ослабевают.

Существует и ещё одна распространённая проблема.

Многие при написании навыков стремятся включить в них подробные инструкции по шагам: «Сначала сделайте то, потом это, затем вот это». Однако на практике оказывается, что выполнение таких инструкций моделью происходит нестабильно.

Со временем я понял: такие повторяющиеся операции гораздо лучше оформлять в виде скриптов (Scripts), а не прописывать в виде длинных инструкций.

Прочитав статью Anthropic, я сделал для себя главное вывод: многие действительно используют навыки, но далеко не все по-настоящему их понимают.

По своей сути навык — это инженерия контекста (Context Engineering). Важно знать, когда следует включать знания в навык, когда — разбивать их на ссылки (References), когда — оформлять в виде скриптов, а когда — использовать ограничения (Gotchas) для управления поведением модели. Здесь накоплено множество практических наработок.

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

Если вы хотите глубоко изучить тему навыков, настоятельно рекомендую прочитать две статьи:

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity

#01 Не пишите «воду»

Навык по своей сути предназначен для фиксации «неявных знаний» организации. Поэтому в навыке не следует дублировать общепринятые, очевидные вещи — модель и так их знает. По-настоящему ценной является именно та информация, которую модель изначально не знает.

Внутри Anthropic постоянно подчёркивают: в навыке нужно писать именно Gotchas — типичные ошибки и ловушки.

Например:

1. Эту таблицу нельзя сортировать по полю created_at;

2. Код ответа 200 в staging-среде не означает успешное завершение операции;

3. request_id и trace_id — это одно и то же.

Такая информация обычно существует только в опыте сотрудников. Поэтому важно чётко осознавать, что такое навык.

Навык = записанный опыт мастера.

С помощью навыков опыт, ранее распылённый по головам разных людей, систематизируется и сохраняется.

#02 Навык — это Context Engineering

Это, возможно, одна из самых глубоких идей, высказанных Anthropic.

Навык — это не просто Markdown-файл, а целая папка. Для тех, кто уже работал с навыками, это звучит как банальность.

Однако, размышляя над этим в последние дни, я постепенно осознал: именно формат папки выбран для выражения идеи Context Engineering.

Рассмотрим типичную структуру навыка:

skill/
 ├── SKILL.md
 ├── references/ — подробные описания, справочники API, граничные условия
 ├── scripts/ — исполняемые скрипты
 ├── examples/ — примеры использования
 ├── assets/ — шаблоны, изображения, фиксированные материалы

При вызове навыка модель в первую очередь считывает файл SKILL.md. Если поместить всю информацию в этот единственный файл, контекст очень быстро переполнится.

Представим, что это навык диагностики платежей: он содержит и описание кодов ошибок Stripe, и историю аварийных ситуаций, и скрипты диагностики, и шаблон итогового отчёта.

Если всё это «упаковать» в SKILL.md, каждый раз при вызове навыка Claude будет вынужден заново читать весь объём информации.

Даже если пользователь хочет лишь уточнить значение одного кода ошибки или проверить причину задержки обновления статуса платежа, в контекст будут загружены огромные объёмы совершенно ненужных данных.

Подход Anthropic кардинально отличается.

SKILL.md скорее напоминает страницу навигации. Его задача — сообщить модели: «Если возникла ошибка Stripe, ищи соответствующее описание в папке references».

Когда требуется проанализировать исторический случай — обращайся к examples; когда нужно выполнить конкретные диагностические действия — запускай скрипты из папки scripts; а при формировании итогового отчёта — используй шаблоны из assets.

Весь процесс происходит поэтапно, с постепенным раскрытием необходимой информации.

Рекомендую обязательно сохранить приведённую ниже иллюстрацию.

#03 Предпочтительно использовать скрипты

Не тратите ограниченный контекст и вычислительные ресурсы модели на рутинные, повторяющиеся операции — поручите их скриптам.

Например, при создании навыка многие пишут так:

1. Запросить данные регистрации;
2. Запросить данные оплаты;
3. Рассчитать коэффициент конверсии;
4. Проанализировать причины аномалий.

Такой подход, безусловно, рабочий, и модель справится с задачей. Но при каждом выполнении ей придётся заново проходить весь анализ с самого начала.

Запрос данных, их подготовка и обработка различных граничных случаев — всё это рутинные, многократно повторяющиеся действия.

Если эти возможности уже многократно протестированы и проверены на практике, зачем заставлять модель «изобретать велосипед»? Гораздо эффективнее предоставить готовые, конкретные скрипты.

Более того, использование скриптов обеспечивает более точное и экономичное (с точки зрения расхода токенов) выполнение навыков.

С этой точки зрения скрипты внутри навыка — это способ закрепления организационных компетенций. За каждым таким скриптом обычно стоит лучшая практика, выработанная командой после многочисленных неудач и ошибок.

Закрепив эти компетенции, Claude сможет каждый раз опираться на накопленный опыт, а не начинать с нуля.

Поэтому я всё больше убеждаюсь: Instructions и Scripts в навыке решают принципиально разные задачи.

Instructions предоставляют опыт и суждения, Scripts — компетенции и исполнительные возможности.

Например, в навыке диагностики платежей может быть такая формулировка:

«Если Stripe возвращает код 200, не делайте вывод о успешности платежа — необходимо дополнительно проверить таблицу payment_events».

Это — Instructions, поскольку здесь передаётся опыт. А функция check_payment_events() — это Script, поскольку она реализует конкретное действие.

Если есть только Script, модель знает, как проверить, но не знает, почему это нужно делать.

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

#04 Description выполняет роль правила маршрутизации

Многие изначально неправильно подходят к написанию описания навыка (Description).

Обычно его оформляют как функциональное описание: например, «PR Management Skill помогает отслеживать статус PR, решать проблемы CI и автоматически выполнять слияние».

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

Следовательно, самая важная информация в Description — это не то, что умеет делать навык, а в каких случаях его следует загружать.

Description фактически выполняет функцию маршрутизации всего навыка.

В реальной жизни почти никто не говорит: «Запусти для меня инструмент управления PR». Чаще звучит: «Проследи за этим PR», «CI снова упал» и т.п.

Поэтому хорошее Description должно максимально точно описывать намерение пользователя, а не просто перечислять функции.

Я даже предлагаю простой способ проверки.

Напишите Description, затем удалите весь навык, оставив только эту одну строку. И спросите себя: «Сможет ли модель, увидев запрос пользователя, понять, когда следует загрузить именно этот навык?»

Если ответ — «нет», значит, Description требует доработки.

#05 Управление и распространение навыков

Есть ещё один аспект — управление навыками.

Когда навыками пользуется один человек, задача управления крайне проста: пишите, поддерживайте и обновляйте их самостоятельно. Однако большинство команд со временем сталкиваются с одной и той же проблемой.

Когда количество навыков растёт с нескольких до десятков или даже сотен — как их управлять? Как обновлять? Как распространять среди членов команды?

Опыт Anthropic в этой области, на мой взгляд, весьма показателен.

На раннем этапе, при небольшом размере команды, навыки просто размещаются в репозитории кода — например, в каталоге .claude/skills проекта. Все участники команды используют одну и ту же совокупность навыков и следуют единой методологии работы.

Однако по мере роста количества навыков возникает новая проблема.

При старте Claude Code сканирует названия и описания всех навыков, чтобы определить, какой из них следует вызвать для текущей задачи. Чем больше навыков — тем выше затраты на маршрутизацию.

Именно поэтому Anthropic впоследствии создала Marketplace. Более интересным, однако, является их подход к управлению Marketplace.

Многие компании при решении подобных задач первым делом вводят строгий процесс согласования: автор навыка подаёт заявку, после её одобрения навык попадает в официальный каталог. Мы сами ранее использовали такой подход, но он оказался чрезмерно бюрократичным — управление ради управления.

Anthropic же действует гораздо легче и гибче.

Новый навык сначала распространяется в узком кругу: коллеги самостоятельно устанавливают и тестируют его.

Если число пользователей постепенно растёт — это сигнал: навык действительно решает реальную проблему. На этом этапе автор может официально представить его в Marketplace.

Таким образом, вместо предварительной оценки «стоит ли навык чего-то» Anthropic сначала даёт ему пройти проверку в реальных условиях эксплуатации. Популярность сама становится критерием включения в официальную систему. В результате остаются только те навыки, которые действительно нужны команде.