Навыки агентов (skills)

Кому подойдёт

Урок для тех, кто работает с агентом в терминале (Claude Code) или в приложении и заметил, что раз за разом объясняет одно и то же: как оформлять коммиты, как выгружать отчёт, как проверять вёрстку. Достаточно ходить по каталогам и не пугаться YAML.

Что понадобится

Нужен Claude Code с подпиской Pro или Max либо ключ API с оплатой за токены: бесплатного тарифа под агентскую работу нет, и то и другое оформляется на зарубежную карту. Из России сервисы Anthropic без VPN не открываются — ни веб-приложение, ни api.anthropic.com, куда ходит терминальный клиент.

Что такое навык и когда он окупается

Навык — каталог с файлом SKILL.md внутри. В файле обычный текст: что делать, в каком порядке, каким должен быть результат. Рядом кладут справочники, шаблоны и скрипты. Особый язык учить не нужно — пишете так, как объяснили бы задачу новому человеку в команде.

Держится всё на постепенном раскрытии. На старте сессии агент видит по каждому навыку только имя и описание — пару строк. Тело SKILL.md он читает, когда решил, что задача подходит, а вложенные файлы — ещё позже и только те, на которые указывает инструкция. Поэтому длинный список навыков не мешает работе.

Навык окупается, когда процедура повторяется и у неё есть свои правила: релизные заметки из git-истории в вашем формате, разбор логов сервиса, месячный отчёт из выгрузки CRM, вычитка писем перед рассылкой. Признак — вы третий раз дописываете в чат одно и то же уточнение. Разовую задачу дешевле объяснить в диалоге.

Доступ и деньги: без иллюзий

Сами навыки бесплатны: это ваши файлы на вашем диске, их пишут в блокноте и хранят в git. Платите вы за агента, который их исполняет. Claude Code работает по подписке Pro или Max либо по ключу API с оплатой за токены — за объём запросов и ответов, а не за время сессии. Бесплатного тарифа под агентскую работу нет, оба варианта требуют зарубежной карты.

Домены Anthropic из России без VPN не открываются — ни веб-приложение, ни API-эндпоинт, куда ходит терминальный клиент. Россия не значится среди поддерживаемых стран в пользовательском соглашении, так что риск ограничения аккаунта реален; решение принимаете вы. Обещать, что всё пройдёт гладко, было бы нечестно; на механику навыков это не влияет.

Первый навык за один вечер

Личные навыки лежат в ~/.claude/skills/ и видны во всех проектах. Проектные — в .claude/skills/ репозитория, они уезжают к коллегам вместе с кодом. Внутри каталог с именем навыка, а в нём файл ровно SKILL.md, заглавными буквами. Имя каталога — строчные латинские буквы, цифры и дефисы: release-notes, weekly-report.

Файл открывается блоком метаданных между тройными дефисами; открывающие дефисы стоят в самой первой строке. Обязательных полей два: name: release-notes и description: «Собирает черновик релизных заметок из истории коммитов. Применять, когда просят changelog, release notes или список того, что вошло в релиз». Дальше закрывающие дефисы, пустая строка и тело.

Тело — пошаговая инструкция: порядок действий («возьми два последних тега, потом git log между ними»), формат результата («разделы Добавлено / Исправлено / Сломалось, в каждой строке короткий хеш коммита»), запреты («не выдумывай пункты, которых нет в истории») и один пример готового вывода. Пример работает лучше трёх абзацев объяснений. Сохраните файл, перезапустите сессию и попросите обычными словами: «собери релизные заметки».

Описание решает, сработает навык или нет

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

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

Держите описание в одном-трёх предложениях: формально туда влезет абзац, но длинное хуже отделяет свою задачу от чужой. Следите, чтобы описания не наезжали друг на друга: если два навыка обещают «работу с отчётами», агент выбирает наугад. Разводите конкретикой — «недельный отчёт по продажам» против «квартальный отчёт для инвесторов».

Многофайловый навык и настройки

Когда инструкция перерастает страницу, её разносят по файлам, а в SKILL.md оставляют маршрут: «форматы полей — в references/fields.md», «шаблон письма — в assets/letter.html». Пишите условие, при котором файл открывают, иначе он будет прочитан либо всегда, либо никогда.

Скрипт забирает у модели ту часть работы, где нужна точность, а не рассуждение: агент запускает его и разбирает вывод вместо счёта в уме. Исполняется скрипт на машине агента, с её правами, и требует установленного окружения — python, node. Опишите в инструкции, что делать, если запуск упал.

Из необязательных полей метаданных чаще прочих нужен allowed-tools — список разрешённых инструментов, например allowed-tools: Read, Grep, Glob для навыка, который только читает. Тело SKILL.md держите в пределах нескольких экранов, длинное выносите в references/.

references/ — справка по необходимости: поля выгрузки, правила оформления
assets/ — шаблоны и образцы: бланк договора, html-письмо, заготовка таблицы
scripts/ — код: пересчёт сумм, массовое переименование, запрос к API

Навык, CLAUDE.md, субагент и хук — кто за что отвечает

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

Субагент — отдельный исполнитель со своим окном контекста, ролью и набором инструментов; описания лежат в .claude/agents/. Его заводят, когда работа объёмная, а её черновик не должен засорять основной диалог: прочитать сорок файлов и вернуть три вывода. Навык нового окна не создаёт — он добавляет знание в текущий разговор, и субагент внутри может им пользоваться.

Хук — команда оболочки, которую среда запускает на событии: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop; настраивается в settings.json. Хук выполняется всегда — его запускает программа; навык подхватывает модель, то есть вероятностно. Обязательное правило («перед коммитом прогнать линтер», «не трогать файлы в prod/») делайте хуком.

Как раздать навык команде

Дешевле всего закоммитить .claude/skills/ в репозиторий проекта: у всех, кто сделал pull, навык появится на следующей сессии, правки пойдут через код-ревью, а история покажет, кто поменял формулировку.

Когда навыков много и нужны они в разных репозиториях, их собирают в плагин — набор навыков, команд и настроек, который ставится через /plugin из вашего маркетплейса, по сути git-репозитория с файлом описания. Обновление приезжает всем разом. Договоритесь, у кого право менять общие навыки, иначе через месяц никто не объяснит текущий формат отчёта.

Чужой навык — это инструкции и код, которые запустятся на вашей машине: читайте его как pull request от незнакомца, в первую очередь scripts/. Токены и пароли внутри не хранят, им место в переменных окружения. Держите в теле строку про владельца и дату последней правки.

Отладка: почему навык не срабатывает

Сначала выясните, где ломается. Попросите прямо: «используй навык release-notes». Отработал по имени, но сам не поднимается — дело в описании. Не работает и по имени — навык не обнаружен, проверяйте файлы:

Другой случай: навык поднимается, но делает не то. Виновато расплывчатое тело («оформи красиво» вместо формата), правило в CLAUDE.md, которое говорит обратное, или три похожих навыка, между которыми агент мечется.

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

путь ~/.claude/skills/имя/SKILL.md или .claude/skills/имя/SKILL.md, без лишней вложенности
имя файла ровно SKILL.md, заглавными буквами
тройные дефисы в первой строке: ни пустой строки, ни BOM перед ними
в YAML нет табов, значения с двоеточием — в кавычках
сессия перезапущена: список навыков собирается на старте
claude --debug показывает, что подхватилось, а /context — сколько это занимает

Практика

Выпишите три задачи, которые за месяц объясняли агенту повторно, и возьмите ту, у которой есть проверяемый результат — файл, отчёт, список.
Создайте каталог: mkdir -p ~/.claude/skills/имя-навыка (строчные латинские буквы и дефисы), а в нём файл SKILL.md.
Заполните метаданные между тройными дефисами в первой строке: name совпадает с именем каталога, description говорит, что навык делает и по каким словам его брать.
В теле распишите шаги, формат результата, явные запреты и один пример готового вывода. Уложитесь в одну-две страницы.
Перезапустите сессию и сформулируйте задачу обычными словами, не называя навык. Убедитесь, что он поднялся сам.
Повторите на трёх-четырёх формулировках, включая ту, которой попросил бы коллега, и на посторонней задаче, где навык браться не должен.
Вынесите длинную справку в references/, точный пересчёт — в scripts/, а в SKILL.md оставьте ссылки с условием, когда открывать.
Положите навык в .claude/skills/ рабочего репозитория, закоммитьте и попросите коллегу проверить на своей задаче.

Проверьте себя

Могу объяснить, что агент видит до срабатывания навыка и почему список навыков не съедает контекст.
Пишу описание так, что навык поднимается на живых формулировках задачи, а не только на придуманной мной.
Понимаю, когда правило должно быть навыком, когда строкой в CLAUDE.md, когда субагентом, а когда хуком.
Умею разнести навык по файлам: инструкция в SKILL.md, справка в references/, точные операции в scripts/.
Отличаю проблему обнаружения от проблемы описания и знаю, что смотреть в каждом случае.
Знаю, как отдать навык команде через репозиторий или плагин и что проверить в чужом навыке перед установкой.

Частые вопросы

Сколько навыков можно держать одновременно?

Технического потолка вы, скорее всего, не почувствуете: на старте в контекст попадают только имя и описание каждого навыка. Раньше упрётесь в другое — агент начнёт путать навыки с похожими описаниями. Предел задаёт не количество, а чёткость формулировок: срабатывают не по адресу — объедините навыки или перепишите описания.

Навык не срабатывает, хотя файл лежит на месте. С чего начать?

Попросите агента использовать навык по имени напрямую. Сработал — файлы в порядке, переписывайте описание словами, которыми задачу формулируете вы и коллеги. Не сработал — проверьте путь, точное имя SKILL.md заглавными, тройные дефисы в первой строке и табы в YAML. И перезапустите сессию: список собирается при старте.

Чем навык лучше длинного промпта в начале диалога?

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

Скрипты внутри навыка обязательны?

Нет, большинство полезных навыков — чистый текст. Скрипт нужен там, где важна точность, а не рассуждение: пересчёт, массовое переименование, обращение к API. Он выполняется на вашей машине с вашими правами и требует установленного окружения, поэтому опишите поведение при неудачном запуске.

Можно ли пользоваться навыками из России?

Файлы навыков — обычный текст, работать с ними ничего не мешает. Наружу ходит сам агент: серверы Anthropic из России без VPN не открываются, Россия не значится среди поддерживаемых стран в соглашении, подписка и ключ API оплачиваются зарубежной картой. Риск ограничения аккаунта реален, оценивать его вам.

Навык срабатывает, но результат каждый раз разный. Что делать?

Обычно виновато расплывчатое тело: «сделай нормально» модель понимает каждый раз по-новому. Задайте жёсткий формат вывода и добавьте один полный пример результата — он работает лучше нескольких абзацев объяснений. Проверьте заодно, нет ли в CLAUDE.md правила, которое противоречит навыку.

Чтобы пройти практику, нужен рабочий доступ

Подключим подписку на ваш аккаунт: оплата картой РФ, по СБП или криптой, пароль от аккаунта не нужен. Обычно за 15 минут в рабочее время.

Подключить Claude Pro — 2 490 ₽ Все уроки