Перевод. Оригинал: https://x.com/trq212/status/2033949937936085378?s=20
Навыки (Skills) стали одной из самых используемых точек расширения в Claude Code. Они гибкие, их легко создавать и просто распространять.
Но эта гибкость также усложняет понимание того, что работает лучше всего. Какие типы навыков стоит создавать? В чем секрет написания хорошего навыка? Когда стоит делиться ими с другими?
В Anthropic мы активно используем навыки в Claude Code — сотни из них находятся в постоянной эксплуатации. Вот уроки, которые мы извлекли об использовании навыков для ускорения нашей разработки.
Что такое Навыки?
Распространенное заблуждение о навыках заключается в том, что это «просто файлы markdown», но самое интересное в навыках то, что это не просто текстовые файлы. Это папки, которые могут включать скрипты, ресурсы, данные и т. д., которые агент может обнаруживать, изучать и которыми может манипулировать.
В Claude Code навыки также имеют широкий спектр параметров конфигурации, включая регистрацию динамических хуков. Мы обнаружили, что некоторые из самых интересных навыков в Claude Code творчески используют эти параметры конфигурации и структуру папок.
Типы Навыков
Каталогизировав все наши навыки, мы заметили, что они группируются в несколько повторяющихся категорий. Лучшие навыки четко вписываются в одну; более запутанные — охватывают сразу несколько. Это не окончательный список, но это хороший способ подумать о том, не упускаете ли вы что-то внутри своей организации.
1. Справочники библиотек и API
Навыки, объясняющие, как правильно использовать библиотеку, CLI или SDK. Это могут быть как внутренние библиотеки, так и распространенные библиотеки, с которыми у Claude Code иногда возникают трудности. Эти навыки часто включают папку с примерами кода и список «подводных камней» (gotchas), которых Claude должен избегать при написании скриптов. Примеры: billing-lib, internal-platform-cli, frontend-design.
2. Верификация продукта
Навыки, описывающие, как протестировать или проверить работоспособность вашего кода. Они часто работают в паре с внешними инструментами, такими как Playwright, tmux и т. д. Навыки верификации чрезвычайно полезны для обеспечения корректности вывода Claude.
Рассмотрите такие методы, как запись видео вывода Claude или использование программных проверок состояния (assertions) на каждом этапе. Эти навыки часто реализуются путем включения в навык различных скриптов.
3. Сбор и анализ данных
Навыки, которые подключаются к вашим стекам данных и мониторинга. Такие навыки могут включать библиотеки для получения данных с использованием учетных данных, идентификаторы конкретных дашбордов и т. д., а также инструкции по типичным рабочим процессам или способам получения данных.
4. Бизнес-процессы и командная автоматизация
Навыки, автоматизирующие повторяющиеся рабочие процессы в одну команду. Обычно это довольно простые инструкции, но они могут иметь сложные зависимости от других навыков или MCP. Для таких навыков сохранение предыдущих результатов в лог-файлах помогает модели оставаться последовательной и учитывать предыдущие выполнения рабочего процесса.
5. Шаблоны и генерация кода (Scaffolding)
Навыки, генерирующие заготовки (boilerplate) фреймворка для конкретной функции в кодовой базе. Вы можете объединять эти навыки со скриптами, которые можно комбинировать. Они особенно полезны, когда ваша генерация кода имеет требования на естественном языке, которые не могут быть полностью охвачены кодом.
6. Качество кода и ревью
Навыки, обеспечивающие соблюдение качества кода в вашей организации и помогающие в его проверке. Они могут включать детерминированные скрипты или инструменты для максимальной надежности. Вы можете запускать эти навыки автоматически как часть хуков или внутри GitHub Action.
7. CI/CD и развертывание
Навыки, которые помогают получать, отправлять и развертывать код внутри вашей кодовой базы. Эти навыки могут ссылаться на другие навыки для сбора данных.
8. Ранбуки (инструкции по эксплуатации)
Навыки, которые принимают «симптом» (например, тред в Slack, оповещение или сигнатуру ошибки), проводят исследование с использованием нескольких инструментов и создают структурированный отчет.
9. Инфраструктурные операции
Навыки, выполняющие рутинное обслуживание и операционные процедуры — некоторые из них включают деструктивные действия, требующие защитных барьеров. Они облегчают инженерам следование лучшим практикам в критических операциях.
Советы по созданию Навыков
Определившись с навыком, как вы его напишете? Вот некоторые из лучших практик, советов и приемов, которые мы нашли.
Не констатируйте очевидное
Claude Code много знает о вашей кодовой базе, а Claude много знает о программировании, включая множество мнений по умолчанию. Если вы публикуете навык, который в первую очередь касается знаний, постарайтесь сосредоточиться на информации, которая выводит Claude за рамки его привычного мышления.
Хорошим примером является навык frontend design — он был создан одним из инженеров Anthropic путем итераций с клиентами над улучшением дизайнерского вкуса Claude, избегая классических паттернов, таких как шрифт Inter и фиолетовые градиенты.
Создайте раздел «Подводные камни» (Gotchas)
Контент с самым высоким приоритетом (сигналом) в любом навыке — это раздел Gotchas. Такие разделы должны строиться на основе общих точек отказа, с которыми сталкивается Claude при использовании вашего навыка. В идеале вы будете обновлять свой навык со временем, чтобы фиксировать эти ошибки.
Используйте файловую систему и метод раскрытия по необходимости
Как мы говорили ранее, навык — это папка, а не просто файл markdown. Вы должны рассматривать всю файловую систему как форму проектирования контекста и прогрессивного раскрытия. Скажите Claude, какие файлы находятся в вашем навыке, и он прочитает их в нужное время.
Простейшая форма прогрессивного раскрытия — указывать на другие файлы markdown. Например, вы можете вынести подробные сигнатуры функций и примеры использования в references/api.md.
Еще один пример: если вашим конечным результатом является файл markdown, вы можете включить в папку assets/ файл шаблона для копирования и использования. Вы можете создавать папки со справочниками, скриптами, примерами и т. д., что поможет Claude работать эффективнее.
Не ограничивайте Claude слишком жестко
Claude обычно старается придерживаться ваших инструкций, и поскольку навыки многократно используются, вы должны быть осторожны, чтобы не быть слишком специфичными в своих инструкциях. Дайте Claude необходимую информацию, но позвольте ему адаптироваться к ситуации. Например:
Продумайте настройку
Хороший паттерн для этого — хранить информацию о настройке в файле config.json в директории навыка. Если конфигурация не задана, агент может спросить пользователя. Если вы хотите, чтобы агент задавал структурированные вопросы с вариантами выбора, вы можете проинструктировать Claude использовать инструмент AskUserQuestion.
Поле Description предназначено для модели
Когда Claude Code начинает сессию, он строит список всех доступных навыков с их описаниями. Именно этот список Claude сканирует, чтобы решить: «есть ли навык для этого запроса?». Это означает, что поле описания — это не краткая сводка, а описание того, когда следует активировать этот навык.
Память и хранение данных
Некоторые навыки могут включать форму памяти, сохраняя данные внутри себя. Вы можете хранить данные в чем угодно: от простого текстового лог-файла до JSON-файлов или базы данных SQLite. Например, навык standup-post может вести standups.log со всеми написанными им постами. Это значит, что при следующем запуске Claude прочитает свою историю и поймет, что изменилось со вчерашнего дня.
Данные в директории навыка могут быть удалены при его обновлении, поэтому их следует хранить в стабильной папке. На сегодня мы предоставляем ${CLAUDE_PLUGIN_DATA} как стабильную папку для каждого плагина.
Храните скрипты и генерируйте код
Одним из самых мощных инструментов для Claude является код. Готовые скрипты и библиотеки позволяют Claude тратить свои шаги на композицию — решение о том, что делать дальше, — вместо восстановления бойлерплейта.
Например, в навыке для анализа данных у вас может быть библиотека функций для получения данных из источника событий. С набором вспомогательных функций Claude сможет на лету генерировать скрипты для сложного анализа, отвечая на вопросы вроде «Что произошло во вторник?».
Динамические хуки (On Demand Hooks)
Навыки могут включать хуки, которые активируются только при вызове навыка и действуют до конца сессии. Используйте это для специфических проверок, которые не нужны постоянно.
Примеры:
/careful— блокируетrm -rf,DROP TABLE,force-push, когда вы знаете, что работаете с продакшеном./freeze— блокирует любые изменения вне конкретной директории при отладке.
Распространение Навыков
Одно из главных преимуществ навыков — возможность делиться ими с командой. Есть два основных пути:
- Добавлять навыки в репозиторий (в папку
./.claude/skills). - Создавать плагины — в Claude Code появится маркетплейс, где пользователи смогут загружать и устанавливать плагины.
Заключение
Навыки — это невероятно мощные и гибкие инструменты для агентов. Лучший способ понять их — начать действовать, экспериментировать и смотреть, что подходит именно вам. Большинство наших навыков начинались как несколько строк и один «подводный камень», и дополнялись по мере того, как Claude сталкивался с новыми крайними случаями.
