Большинство написанных навыков неправильны: 5 размышлений после публикации внутренней методологии Anthropic

Автор: AI продукт Айньинг

Прочитал блог Anthropic под названием «Lessons from building Claude Code: How we use skills». Это, пожалуй, самое глубокое практическое резюме по навыкам, которое я видел на данный момент.

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

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

Но потом я попробовал сам и понял, что во многих случаях это просто невозможно.

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

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

Есть и другой распространённый случай.

Многие пишут навыки, вставляя туда разные инструкции по операциям. Что делать на первом шаге, что на втором, что на третьем. В итоге при запуске обнаруживается, что выполнение модели нестабильно.

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

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

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

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

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

#01 Не пишите пустых слов

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

Внутри Anthropic часто подчеркивают, что в навыке важно писать именно «Gotchas», то есть типичные ловушки.

Например:

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

2. Возврат 200 в staging не означает успех

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

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

Skill = записать опыт мастера.

Через навык можно накопить опыт, разбросанный по разным людям.

#02 Навык — это по сути инженерия контекста

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

Навык — это не markdown-файл, а папка. Для тех, кто использует навыки, это звучит как очевидное.

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

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

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

Когда вызывается навык, модель сначала читает SKILL.md. Если все сведения засовывать в один файл, то очень быстро контекст станет слишком большим.

Например, это навык устранения ошибок платежей, где есть описание ошибок Stripe, исторические кейсы, скрипты диагностики и шаблоны финальных отчетов.

Если все это закинуть в SKILL.md, то при каждом вызове модель будет заново читать его.

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

А у Anthropic подход совсем другой.

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

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

Весь процесс — постепенное раскрытие информации.

Ниже — очень рекомендую сохранить эту схему.

#03 Используйте скрипты по максимуму

Не стоит тратить ограниченный контекст и аналитические способности модели на повторяющуюся работу. Лучше делегировать это скриптам.

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

1. Запросить регистрационные данные; 2. Запросить платежные данные; 3. Посчитать конверсию; 4. Проанализировать причины ошибок.

Это, конечно, нормально. Модель может так сделать. Но при каждом запуске она заново проходит весь анализ.

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

Эти возможности уже проверены много раз. Почему бы не дать конкретный скрипт?

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

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

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

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

Инструкции — это опыт и суждения, скрипты — это способности и действия.

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

Если Stripe возвращает 200, не считать платеж успешным, а проверить таблицу payment_events.

Это — инструкция, потому что основана на опыте. А функция check_payment_events() — скрипт, потому что это действие.

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

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

#04 Описание — это скорее маршрутное правило

Многие неправильно пишут описание навыка.

Потому что обычно описывают его функции. Например: PR Management Skill помогает следить за статусом PR, решать CI-проблемы, автоматически делать merge.

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

И на основе текущей проблемы пользователя решает, какой навык загрузить.

Поэтому самое важное в описании — не что умеет навык, а в каких случаях его нужно запускать.

Описание — это своего рода маршрутизатор навыка.

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

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

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

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

Если не сможет — значит, нужно доработать.

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

Еще один важный момент — управление навыками.

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

Но я уверен, что у большинства команд рано или поздно возникнет вопрос: как управлять десятками или сотнями навыков? Как их обновлять? Как делиться ими внутри команды?

Опыт Anthropic в этом очень ценен.

Когда команда небольшая, навыки хранятся прямо в репозитории — в папке .claude/skills. Все используют один набор навыков и один подход.

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

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

Именно поэтому Anthropic начали делать Marketplace. Но интереснее то, как они управляют этим Marketplace.

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

У них же подход другой.

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

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

Они не обсуждают сразу ценность навыка. Сначала он проходит реальное тестирование в практике. Чем больше людей использует — тем быстрее он становится частью системы. А оставшиеся навыки — это действительно нужные навыки команды.