Как написать собственный навык для агента

Написание собственного навыка агента на основе реального сбоя

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

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

Начните с задачи, которую агент выполнил неверно дважды

Один раз — случайность. Дважды — закономерность, а закономерность стоит того, чтобы создать для неё файл.

Вот сбой, который повторяется на реальных серверах. Вы просите агента добавить блок reverse proxy в nginx. Он редактирует /etc/nginx/conf.d/app.conf, а затем запускает sudo systemctl restart nginx. В правке допущена опечатка, поэтому nginx отказывается запускаться, и сайт недоступен, пока вы не исправите ошибку:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Вы исправляете её в чате. Протестируйте конфигурацию с помощью sudo nginx -t перед тем, как затрагивать сервис, а затем примените её командой reload вместо restart. Неделю спустя, при выполнении другой задачи, повторяется та же ошибка. Этот второй случай — сигнал.

Запишите две вещи, пока сбой перед глазами: запрос, который вы ввели, и исправление, которое вы предоставили, используя свои формулировки. Эти две строки становятся навыком. Запрос указывает, чему должен соответствовать триггер. Исправление — это всё содержимое.

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

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

Анатомия навыка

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

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md начинается с блока метаданных — нескольких настроек в формате YAML (такой же формат конфигурации используют файлы Docker Compose), заключенных между маркерами ---, за которыми следуют инструкции в формате markdown. Ниже приведен полный код навыка для описанной выше ошибки.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Этот файл содержит менее 20 строк и является полноценным навыком. Его составные части:

• name: до 64 символов, только строчные буквы, цифры и дефисы; не может содержать слова claude или anthropic. В персональном или проектном навыке это лишь отображаемое имя. Команда, которую вы вводите, определяется именем директории, поэтому данный навык вызывается через /nginx-config-changes.
• description: описание того, что делает навык и когда его использовать, до 1 024 символов. Эта строка выполняет основную задачу, и следующий раздел посвящен исключительно ей.
• Тело файла: инструкции, которые загружаются только в момент активации навыка.
• reference/: дополнительные файлы, которые агент считывает по запросу. Ссылайтесь на них из SKILL.md и сохраняйте глубину ссылок в один уровень, так как файл, на который ссылается другой файл, часто считывается лишь частично.
• scripts/: файлы, которые агент исполняет, а не считывает. В контекст попадает только их вывод, поэтому скрипт на 300 строк не создает большой нагрузки.

Место размещения директории определяет область действия навыка.

• .claude/skills/<name>/SKILL.md в репозитории: только для этого проекта; навык будет доступен всем, кто клонирует репозиторий.
• ~/.claude/skills/<name>/SKILL.md: для всех проектов на вашей машине; навык недоступен другим пользователям.
• <plugin>/skills/<name>/SKILL.md: внутри плагина; навык доступен везде, где включен этот плагин.

Создайте навык с помощью mkdir -p .claude/skills/nginx-config-changes и запишите содержимое файла. Claude Code отслеживает эти директории, поэтому изменения в существующем навыке вступают в силу в рамках текущей сессии. Если вы создаете директорию верхнего уровня для навыков, которой не существовало на момент запуска сессии, потребуется перезапуск, так как на момент старта сессии системе было нечего отслеживать.

Поле description — это самая важная строка в файле

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

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

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

Используйте слова, которые вы будете вводить на самом деле. description: Helps with nginx не соответствует ничему, так как никто не пишет "помогает с". В примере выше указаны /etc/nginx, server block, reverse proxy и TLS (transport layer security) certificate path — это примерно тот словарный запас, который встречается в любом запросе, требующем активации навыка.

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

Поддерживайте малый объем тела, так как оно остается в контексте

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

Anthropic рекомендует поддерживать SKILL.md объемом менее 500 строк и переносить детали в отдельные файлы. Механизм сжатия объясняет, почему это число не является произвольным. Когда диалог сокращается для освобождения контекста, Claude Code повторно прикрепляет последнее обращение к каждому навыку, сохраняет только первые 5,000 токенов каждого из них и заполняет общий бюджет в 25,000 токенов, начиная с навыка, вызванного последним. Длинный навык будет обрезан на середине. Несколько длинных навыков полностью вытеснят друг друга.

Поэтому пишите только то, чего модель еще не знает. Она знает, что такое nginx и что делает reverse proxy. Она не знает вашего внутреннего правила о предпочтении reload перед restart, и это правило — единственная причина существования данного файла.

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

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

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

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

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

1. Начните новую сессию с claude в проекте.
2. Введите запрос так, как вы сделали бы это в обычный рабочий день, своими словами, не называя навык.
3. Дождитесь вызова. Если навык не срабатывает, исправьте описание. Проблема пока не в теле навыка.
4. Вызовите его вручную с помощью /nginx-config-changes в качестве контрольного теста. Правильное поведение при ручном вызове и неправильное при обычном запросе подтверждают проблему с триггером, а не с инструкциями.
5. Выполните тот же запрос с выключенным навыком и сравните оба ответа. В меню /skills выделите навык, нажмите Space, чтобы переключить его состояние на off, затем Enter для сохранения. Это запишет элемент skillOverrides в .claude/settings.local.json, а повторное нажатие Space вернет его в состояние on, когда вы закончите.
6. Напишите несколько запросов, которые не должны вызывать навык, и убедитесь, что он остается неактивным в этих случаях.

Чтобы автоматизировать этот цикл, установите плагин skill-creator из официального магазина.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Если в выводе установки указано Run /reload-plugins to activate., выполните эту команду. Затем попросите Claude оценить ваш навык по имени. Плагин сохраняет тестовые сценарии в evals/evals.json внутри каталога навыка и запускает каждый случай в отдельном субагенте, поэтому каждый прогон начинается с чистого контекста. Затем он создает сравнение результатов с навыком и без него — это и есть объективный показатель: улучшение процента успешных ответов, измеренное с учетом затраченных токенов и времени выполнения навыка.

Режим сбоя: навык не активируется

Вы вводите запрос, агент выполняет старое некорректное действие, и строка навыка не появляется. Выполните следующие проверки по порядку.

• В описании указано, что делает навык, но не сказано, когда его использовать, поэтому ваш запрос не соответствует условиям активации.
• В описании отсутствуют слова, которые вы вводите. Если вы пишете "nginx", это слово должно присутствовать в описании навыка.
• Параметр disable-model-invocation: true установлен в метаданных (frontmatter). Это полностью исключает описание из контекста модели, и навык можно вызвать только вручную с помощью /name.
• Шаблон paths в метаданных ограничивает активацию только соответствующими файлами, а файл, с которым вы работаете, не подходит под этот шаблон.
• Навык находится во вложенном каталоге .claude/skills/ ниже вашего рабочего каталога. Такие навыки загружаются только после того, как агент прочитает или отредактирует файл внутри этого подкаталога, поэтому до этого момента навык недоступен.

Режим сбоя: навык срабатывает постоянно

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

Сузьте описание до условий, которые действительно имеют значение, и укажите файлы или команды, к которым относится навык. Добавьте paths glob, если навык применим только к определенным файлам. Для любых действий с побочными эффектами, таких как развертывание или коммит, установите disable-model-invocation: true и вызывайте их самостоятельно с помощью /name. Это гарантирует, что агент никогда не примет решение о выполнении развертывания по собственной инициативе.

Режим сбоя: навык должен находиться в файле правил

Файл правил, такой как CLAUDE.md или AGENTS.md, загружается в начале каждого сеанса и применяется к каждой задаче. Тело навыка загружается только при его активации. Решающим фактором является частота использования. Факт, справедливый для каждой задачи в репозитории (например, используемый менеджер пакетов), должен находиться в файле правил. Процедура, применимая лишь к небольшой части задач (например, правило для nginx выше), должна находиться в навыке, где она не потребляет ресурсы в те дни, когда никто не редактирует nginx.

Настоящая ошибка — размещать инструкцию в обоих местах. Две копии со временем начинают различаться, и когда агент выполняет неверное действие, невозможно определить, какой именно копии он следовал. Выберите одно место для каждой инструкции. граница между навыками, MCP-серверами и файлами правил подробно рассматривает более сложные случаи, включая ситуации, когда правильным решением является использование MCP (model context protocol) сервера, который предоставляет агенту новый инструмент вместо новой инструкции.

Делитесь навыком, когда он доказал свою полезность

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

Важное замечание о переносимости. Claude Code поддерживает длинный список полей frontmatter, но стандарт Agent Skills допускает только шесть: name, description, license, compatibility, metadata и allowed-tools. Если вы загрузите навык в claude.ai или упакуете его для Skills API, добавив в frontmatter что-то еще, процесс завершится ошибкой, а не просто проигнорирует лишнее поле:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

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

FAQ

Какой длины должен быть файл SKILL.md?

Держите объем в пределах 500 строк; большинство полезных навыков значительно короче. Содержимое файла попадает в контекст беседы при вызове навыка и остается там до конца сессии, поэтому каждая строка — это постоянные расходы токенов, а не разовая трата. Переносите объемные справочные материалы в отдельные файлы в каталоге навыка и ссылайтесь на них из SKILL.md на один уровень глубже, чтобы агент считывал их только при необходимости. Вложенные скрипты выполняются, а не считываются, поэтому они расходуют токены только на свой вывод.

Почему мой навык не срабатывает?

Обычно причина кроется в описании, так как это единственная часть навыка, которая находится в контексте, когда модель принимает решение. Убедитесь, что описание содержит информацию о том, когда следует использовать навык, а не только о том, что он делает, и включает слова, которые вы реально используете в своих запросах. Если описание составлено верно, проверьте метаданные (frontmatter) на наличие disable-model-invocation: true, который полностью скрывает навык от модели, и paths, который ограничивает его использование файлами, с которыми вы не работаете. Еще одна причина — расположение навыка во вложенном каталоге .claude/skills/ ниже начальной директории: он загружается только после того, как агент прочитает или отредактирует файл в этой поддиректории.

Что выбрать: навык или строку в файле правил?

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

Как узнать, помог ли навык на самом деле?

Сравните результат с базовым уровнем. Соберите несколько реальных запросов, выполните каждый в новой сессии с доступным навыком, а затем повторите их с отключенным навыком через меню /skills и сравните ответы. Новая сессия важна, так как беседа, в которой вы создавали навык, все еще содержит ваши пояснения, из-за чего неполный файл может казаться полным. Плагин skill-creator выполняет это сравнение автоматически и выводит процент успешных ответов рядом с затратами токенов.

Можно ли использовать один и тот же SKILL.md с другим агентом?

Да, если вы не выходите за рамки полей, определенных стандартом Agent Skills: name, description, license, compatibility, metadata и allowed-tools. Claude Code поддерживает гораздо больше полей, а также такие функции тела файла, как внедрение shell-команд, которые другие инструменты не выполняют. Загрузка навыка с полем вне стандарта приведет к ошибке с перечислением разрешенных свойств, поэтому заранее решите, должен ли навык оставаться в Claude Code или быть переносимым.