Как создать собственный навык для агента
Научитесь писать файлы SKILL.md на основе реальных ошибок агента. Разберем структуру файла, выбор условий активации и методы тестирования навыка в вашей среде.
Создание собственного навыка агента на основе реального сбоя
Лучший способ создать собственный навык агента — выделить его из одного реального сбоя. Найдите задачу, с которой ваш агент для написания кода не справился дважды, запишите исправление, которое вы вводили оба раза, и сохраните это исправление в виде файла 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. Через неделю, при выполнении другой задачи, повторяется та же ошибка. Этот второй случай — сигнал.
Запишите две вещи, пока сбой перед глазами: запрос, который вы ввели, и исправление, которое вы предложили, используя свои формулировки. Эти две строки становятся навыком. Запрос определяет, чему должен соответствовать триггер. Исправление — это полное содержание.
В собственных рекомендациях по созданию skills Anthropic ставит этот принцип на первое место. Сначала запустите agent на типовых задачах без skill и зафиксируйте, где он ошибается. Затем напишите минимальные инструкции, которые устраняют эти ошибки. Ошибки и есть спецификация. Поэтому skill, который нельзя связать с конкретной ошибкой, обычно никому не нужен. Этот же критерий применим к устанавливаемым skills, а не только к тем, которые вы пишете сами. 27 опубликованных skills Matt Pocock помогают разделить их на те, которые стоит установить разработчику, работающему самостоятельно на VPS, и те, которые дают результат только в команде.
Пример такой дистилляции можно найти в статье Ponytail превращает один повторяющийся сбой — агента, который переписывает гораздо больше, чем вы просили, — в навык, которую можно прочитать целиком, прежде чем приступать к написанию собственного.
Анатомия навыка
Навык представляет собой каталог, содержащий один обязательный файл.
.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│ └── proxy-headers.md
└── scripts/
└── check-and-reload.shSKILL.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 *)
---Разрешение действует в течение того этапа, на котором был вызван навык, и аннулируется при отправке вами следующего сообщения, поэтому оно не становится постоянным правом доступа без вашего ведома.
Как проверить срабатывание навыка
Наблюдение за загрузкой навыка подтверждает, что агент его обнаружил. Это не означает, что ответ изменился. Проверьте оба аспекта в новой сессии, так как сессия, в которой вы создавали навык, уже содержит всю историю вашего общения в процессе написания. Этот остаточный контекст скрывает пробелы в файле.
- Начните новую сессию с
claudeв проекте. - Введите запрос так, как вы сделали бы это в обычный рабочий день, своими словами, не называя навык.
- Дождитесь вызова. Если навык не срабатывает, исправьте описание. Проблема пока не в теле навыка.
- Вызовите его вручную с помощью
/nginx-config-changesв качестве контрольного теста. Правильное поведение при ручном вызове и неправильное при обычном запросе подтверждают проблему с триггером, а не с инструкциями. - Выполните тот же запрос с выключенным навыком и сравните ответы. В меню
/skillsвыделите навык, нажмитеSpace, чтобы переключить его состояние наoff, затемEnterдля сохранения. Это запишет элементskillOverridesв.claude/settings.local.json, а повторное нажатиеSpaceвернет его в состояниеon, когда вы закончите. - Напишите несколько запросов, которые не должны активировать навык, и убедитесь, что он на них не реагирует.
Чтобы автоматизировать этот цикл, установите плагин 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 glob-шаблона, ограничивающего его использование файлами, с которыми вы не работаете. Еще одна причина — нахождение навыка во вложенной директории .claude/skills/ ниже вашей текущей рабочей директории: он загружается только после того, как агент прочитает или отредактирует файл в этой поддиректории.
Что лучше: создать навык или добавить строку в файл правил?
Оцените, к какому количеству ваших задач это относится. Файл правил загружается в каждой сессии, поэтому в нем должны быть факты, верные для любой задачи, например, используемый менеджер пакетов или соглашение об именовании веток. Навык загружается только при активации, поэтому это подходящее место для процедуры, которая важна лишь для небольшой части задач. Никогда не дублируйте одну и ту же инструкцию в обоих местах: копии начнут расходиться, и вы не сможете определить, какой из них следовал агент.
Как понять, что навык действительно помог?
Сравните результат с базовым уровнем. Соберите несколько реальных запросов, выполните каждый из них в новой сессии с доступным навыком, затем выполните их снова, отключив навык в меню /skills, и сравните оба ответа. Новая сессия важна, так как диалог, в котором вы создавали навык, все еще содержит ваши пояснения, из-за чего неполный файл может выглядеть полным. Плагин skill-creator выполняет это сравнение за вас и отображает процент успешных результатов рядом со стоимостью в токенах.
Можно ли использовать один и тот же SKILL.md с другим агентом?
Да, если вы не выходите за рамки полей, определенных стандартом Agent Skills: name, description, license, compatibility, metadata и allowed-tools. Claude Code поддерживает гораздо больше полей, а также такие функции тела файла, как внедрение shell-команд, которые другие инструменты не выполняют. Загрузка навыка с полем, не входящим в стандарт, приведет к ошибке с явным перечислением разрешенных свойств, поэтому заранее решите, должен ли навык оставаться в Claude Code или быть переносимым.