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

Создание собственного навыка агента на основе реального сбоя

Лучший способ создать собственный навык агента — выделить его из одного реального сбоя. Найдите задачу, с которой ваш агент для написания кода не справился дважды, запишите исправление, которое вы вводили оба раза, и сохраните это исправление в виде файла 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: описание того, что делает навык и когда его использовать, до 1024 символов. Эта строка выполняет основную работу, и следующий раздел посвящен исключительно ей.
• Тело: инструкции, которые загружаются только в момент запуска навыка.
• reference/: дополнительные файлы, которые агент считывает по запросу. Ссылайтесь на них из SKILL.md и сохраняйте глубину ссылок в один уровень, так как файл, на который ссылается другой файл, часто считывается лишь частично.
• scripts/: файлы, которые агент исполняет, а не считывает. Только их вывод расходует контекст, поэтому скрипт на 300 строк обходится «дешево».

Навык дорастает до полной структуры, когда исправляемое им поведение оказывается настолько устойчивым, что для него требуется отдельная схема. Навык unlazy использует это пространство для дерева глубины, набора gate-файлов и контракта PLAN.md, чтобы агент не объявлял работу завершённой, пока целые ветви остаются нетронутыми.

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

• .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 обрезает запись в списке на 1,536 символах. Существует необязательное поле 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 внутри директории навыка и запускает каждый случай в отдельном субагенте, поэтому каждый запуск начинается с чистого контекста. Затем он создает сравнение результатов с использованием навыка и без него — это и есть объективный показатель: улучшение процента успешных ответов, измеренное с учетом затраченных токенов и времени работы навыка.

Навык также может содержать собственное доказательство работоспособности, вместо того чтобы полагаться на отдельный запуск оценки. Именно так работает навык the Old Coder, когда он заставляет агента выдать отчет с доказательствами, который вы можете перепроверить самостоятельно.

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

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

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

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

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

Сузьте описание до условий, которые действительно важны, и укажите файлы или команды, к которым оно относится. Добавьте paths glob, если навык применим только к определенным файлам. Для любых действий с побочными эффектами, таких как развертывание (deploy) или фиксация изменений (commit), установите 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, так и в любой другой системе, поддерживающей данный стандарт. Место загрузки файла по-прежнему определяет его возможности, поскольку Cowork работает в песочнице Anthropic, а Claude Code — на вашей локальной машине или VPS. Поэтому навык для nginx, описанный выше, стоит передать коллеге, но он будет бесполезен в песочнице, у которой нет доступа к серверу. Написание самих инструкций так, чтобы они оставались эффективными при переходе на другую модель — это отдельная задача, которая рассматривается в написании навыков, работающих с любой моделью.

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 или должен быть переносимым.