Уроки разработки в Claude Code: как мы применяем навыки

В Claude Code навыки — одна из самых популярных точек расширения. Они гибкие, их легко писать и распространять.

Обратная сторона этой гибкости — не всегда понятно, какой подход сработает лучше. Какие навыки стоит делать? В чем секрет хорошего навыка? Когда им пора делиться?

В Anthropic мы вовсю пользуемся навыками в Claude Code — счет идет на сотни. Ниже собраны наши наблюдения о том, как они ускоряют разработку.

Что такое навыки?

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

Многие думают, что навыки — это просто файлы разметки. На самом деле куда интереснее то, что это полноценные директории. В них могут лежать скрипты, ресурсы и данные, которые агент находит, изучает и использует.

К тому же в Claude Code у навыков есть множество настроек, включая регистрацию динамических хуков.

Самые крутые навыки, которые мы видели, нестандартно используют именно эти настройки и структуру директорий.

Типы навыков

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

1. Справочники по библиотекам и API

Они объясняют, как правильно использовать конкретную библиотеку, CLI или SDK. Это касается как внутренних инструментов, так и опенсорсных решений, с которыми у Claude Code возникают трудности. В таких навыках обычно лежит папка с кусками кода для примера и списком подводных камней, которых лучше избегать.

Примеры:

• billing-lib — внутренняя библиотека биллинга: корнер-кейсы, опасные места и так далее.
• internal-platform-cli — описание каждой подкоманды вашей внутренней утилиты и примеры их использования.
• frontend-design — учит Claude лучше работать с дизайн-системой компании.

2. Проверка продукта

Эти навыки описывают, как тестировать код и проверять его работоспособность. Часто они работают в связке с внешними инструментами вроде Playwright или tmux.

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

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

Примеры:

• signup-flow-driver — проходит путь от регистрации и проверки почты до онбординга в headless-браузере. На каждом шаге дергаются хуки для проверки состояния.
• checkout-verifier — прокликивает UI оплаты с тестовыми картами Stripe и убеждается, что счет перешел в нужный статус.
• tmux-cli-driver — для интерактивного тестирования консольных утилит, которым нужен полноценный TTY.

3. Сбор и анализ данных

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

Примеры:

• funnel-query — инструкция в духе «какие события собрать, чтобы построить воронку регистрация → активация → оплата», плюс указание на таблицу с правильным user_id.
• cohort-compare — сравнивает retention или конверсию двух когорт, подсвечивает статистически значимые отклонения и опирается на принятые в команде определения сегментов.
• grafana — UID источников, названия кластеров и таблица маппинга: какая проблема на какой дашборд ведет.

4. Автоматизация процессов и командной рутины

Они сводят рутинные задачи к одной команде. Чаще всего это простые инструкции, но иногда они завязаны на другие навыки или протокол MCP (Model Context Protocol). Если сохранять историю выполнения в логи, модель будет работать последовательнее и учитывать прошлые запуски.

Примеры:

• standup-post — собирает данные из таск-трекера, GitHub и прошлых сообщений в Slack, а на выходе выдает готовый статус для стендапа (только то, что изменилось).
• create-<ticket-system>-ticket — проверяет поля по схеме (правильные статусы, обязательные данные), а после создания задачи пингует ревьюера и кидает ссылку в Slack.
• weekly-recap — собирает смерженные PR, закрытые тикеты и деплои в еженедельный дайджест.

5. Генерация шаблонов кода (скаффолдинг)

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

Примеры:

• new-<framework>-workflow — создает каркас для нового сервиса или воркера с правильными аннотациями.
• new-migration — генерирует болванку миграции БД и напоминает о частых ошибках.
• create-app — поднимает новое внутреннее приложение с уже настроенной аутентификацией, логами и конфигами деплоя.

6. Контроль качества и код-ревью

Следят за стандартами кода и помогают на ревью. Внутрь можно зашить скрипты-линтеры, чтобы проверки работали детерминированно и надежно. Такие навыки удобно дергать автоматически — через хуки или прямо в GitHub Actions.

• adversarial-review — запускает субагента, который критикует код свежим взглядом. Агент сам вносит правки и повторяет процесс, пока не останутся только мелкие придирки.
• code-style — бьет по рукам за нарушение код-стайла. Особенно спасает с правилами, которые Claude по умолчанию игнорирует.
• testing-practices — объясняет, как у вас принято писать тесты и что конкретно нужно покрывать.

7. CI/CD и деплой

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

Примеры:

• babysit-pr — присматривает за PR: перезапускает упавший CI, решает конфликты мерджа и включает автомердж.
• deploy-<service>- сборка → smoke-тест → постепенное развертывание трафика со сравнением процента ошибок → автоматический откат при регрессии
• cherry-pick-prod — создает чистое рабочее дерево, делает черри-пик, решает конфликты и открывает готовый PR по шаблону.

8. Ранбуки (инструкции по инцидентам)

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

Примеры:

• <service>-debugging — связывает частые симптомы с инструментами и готовыми запросами для дебага самых нагруженных сервисов.
• oncall-runner — парсит алерт, пробивает базовые сценарии поломки и пишет выжимку.
• log-correlator — берет request ID и вытаскивает логи из всех смежных систем, через которые прошел запрос.

9. Работа с инфраструктурой

Берут на себя рутинное обслуживание серверов. Иногда они могут что-то удалять или перезапускать, поэтому в них встраивают защиту от дурака. Это помогает инженерам не ошибаться в критических ситуациях.

Примеры:

• <resource>-orphans — ищет зависшие поды или тома, пишет в Slack, ждет подтверждения от человека и аккуратно все зачищает.
• dependency-management — проводит новую библиотеку через корпоративный флоу согласования зависимостей.
• cost-investigation — выясняет, почему взлетел счет за инфраструктуру, и указывает на конкретные бакеты или тяжелые запросы.

Как писать навыки: советы и практики

Допустим, вы придумали идею навыка. С чего начать код? Вот несколько приемов, которые работают у нас.

Кстати, недавно мы выпустили Skill Creator — он здорово упрощает написание навыков под Claude Code.

Не объясняйте очевидное

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

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

Соберите раздел с подводными камнями (Gotchas)

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

Используйте файлы для дозированной подачи контекста

Повторюсь: навык — это директория, а не один текстовый файл. Файловую систему можно использовать, чтобы управлять контекстом и выдавать информацию порциями. Просто объясните Claude, что где лежит, и он сам заглянет в нужный файл, когда придет время.

Самый простой вариант — ссылки на другие Markdown-документы. Сигнатуры функций и громоздкие примеры лучше убрать куда-нибудь в references/api.md.

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

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

Не загоняйте Claude в жесткие рамки

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

Продумайте этап настройки (Setup)

Иногда навыку нужны вводные данные от человека. Скажем, если скрипт постит стендап в Slack, Claude должен узнать, в какой именно канал отправлять сообщение.

Удобно хранить такие вещи в файле config.json прямо в папке навыка. А если конфиг пустой — пусть агент сам спрашивает у пользователя.

Чтобы вопросы были структурированными, с вариантами ответов, пропишите в инструкциях использовать инструмент AskUserQuestion.

Поле Description читает сама модель

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

Память и хранение логов

Навыки могут запоминать контекст, сохраняя файлы. Для этого подойдет что угодно: от простых текстовых логов и JSON до полноценной базы SQLite.

Например, скрипт standup-post может дописывать каждый новый отчет в файл standups.log. При следующем запуске Claude прочитает историю и сам поймет, что изменилось со вчерашнего дня.

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

Используйте готовые скрипты и генерируйте код на лету

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

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

После этого на вопрос «Что было во вторник?» Claude на лету соберет из этих функций скрипт и проведет нормальный анализ.

Хуки по требованию

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

Например:

• /careful — перехватывает команды вроде rm -rf, DROP TABLE, force-push или kubectl delete на уровне Bash. Такая защита нужна только при работе с продакшеном. Оставь ее включенной по умолчанию — и сойдешь с ума от ограничений.
• /freeze — запрещает менять файлы вне конкретной директории.
• Сильно выручает на отладке, когда просишь модель добавить логи, а она заодно по своей инициативе чинит соседние файлы.

Как делиться навыками

Главный плюс навыков — ими легко делиться с командой.

Сделать это можно двумя способами:

• положить навыки прямо в репозиторий проекта (в папку ./.claude/skills);
• оформить плагин и поднять внутренний маркетплейс, откуда коллеги смогут всё скачивать (детали есть в документации).

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

Как управлять маркетплейсом

Как определить, что достойно попасть в общий реестр? Как вообще предлагать новые навыки?

У нас в Anthropic нет выделенных ревьюеров под эту задачу. Мы пополняем базу органически: если кто-то написал полезный инструмент, он просто заливает его в песочницу на GitHub и кидает ссылку в Slack.

Если идея взлетает (а это решает сам автор по фидбеку коллег), создается пулл-реквест на перенос навыка в официальный маркетплейс.

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

Как комбинировать навыки

Иногда один скрипт должен опираться на другой. Скажем, есть навык загрузки файлов, и есть генератор CSV, который собирает отчет и хочет его сразу залить. Пока в маркетплейсах нет нативного управления зависимостями. Зато вы можете просто сослаться на нужный навык по имени в текстовой инструкции, и модель сама дернет его, если он установлен.

Как собирать метрики по навыкам

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

Вместо итога

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

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

Надеюсь, статья была полезной. Пишите, если останутся вопросы.