Что такое навык агента и как он работает

Что такое навык агента на самом деле

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

Папка может содержать не только этот файл. Спецификация Agent Skills определяет три необязательные директории: scripts/ для кода, который выполняет агент, references/ для документов, которые он считывает при необходимости, и assets/ для шаблонов и данных. Ни одна из них не является обязательной. Папка, в которой нет ничего, кроме SKILL.md, является полноценным навыком.

restore-drill/
  SKILL.md
  references/retention-policy.md
  scripts/verify_snapshot.sh

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

Почему навык почти ничего не стоит, пока он не используется

Это аргумент, который делает данный формат важным для понимания; дело в контексте, а не в функциях. Загрузка происходит поэтапно, что в спецификации называется прогрессивным раскрытием.

При запуске агент загружает name и description каждого установленного навыка и больше ничего. Спецификация Agent Skills оценивает это примерно в 100 токенов на навык (согласно опубликованному руководству на август 2026 года). Установите дюжину навыков, и вы потратите объем контекста, равный одному длинному абзацу.

Когда запрос соответствует описанию, агент считывает тело этого конкретного SKILL.md. Спецификация рекомендует сохранять объем тела менее 5,000 токенов, а размер файла — менее 500 строк. Файлы в references/ и scripts/ на данном этапе по-прежнему ничего не стоят. Справочный файл загружается только в том случае, если инструкции направляют к нему агента. Со скриптом в составе пакета ситуация иная: агент выполняет его через shell, поэтому исходный код скрипта никогда не попадает в окно контекста, туда передается только результат его выполнения.

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

Один нюанс часто сбивает людей с толку. Как только навык загружается, его тело остается в контексте до конца сессии, поэтому длинный SKILL.md становится повторяющимися расходами, а не разовыми. Перенос деталей в references/ — это не наведение порядка. Это механизм, работающий так, как было задумано.

Навык агента — это не вызов инструмента

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

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

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

Навык агента — это не MCP-сервер

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

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

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

Навык агента — это не системный промпт и не AGENTS.md

Оба этих элемента представляют собой инструкции в формате markdown, поэтому такая путаница оправдана. Разница заключается в моменте их загрузки. AGENTS.md, CLAUDE.md и системный промпт активны всегда. Навык же активируется по запросу.

Для проверки задайте один вопрос: будет ли ошибкой игнорирование этого абзаца при выполнении задачи, которая к нему не относится? Корпоративный стиль, команда сборки и правила именования веток применимы к любой задаче, поэтому они должны находиться в файле, который активен всегда, так как его постоянная загрузка является целевым поведением. Чек-лист для релиза, который вы используете дважды в месяц, не относится к каждой задаче, поэтому его место — в навыке. Если раздел вашего постоянно активного файла превратился в нумерованную процедуру, это сигнал к тому, что его пора перенести.

У этих файлов есть свои соглашения, которые стоит соблюдать. Ознакомьтесь с тем, что должно быть в AGENTS.md, а что в файле для человека и design.md, который описывает структуру кодовой базы — это два документа, которые мы используем.

Как выглядит минимальный навык

В Claude Code персональные навыки хранятся в ~/.claude/skills/<name>/SKILL.md и применяются ко всем вашим проектам. Проектные навыки хранятся в .claude/skills/<name>/SKILL.md и фиксируются в git, поэтому они доступны каждому человеку и каждому агенту, работающему с этим репозиторием. GitHub Copilot и VS Code считывают навыки рабочей области из .github/skills/. Файл внутри этих директорий идентичен.

mkdir -p ~/.claude/skills/restore-drill

---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---

# Restore drill

1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.

If `restic snapshots` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

Это полноценный навык. Имя директории становится командой, которую вы вводите, поэтому в данном случае это /restore-drill. В Claude Code меню /skills отображает список установленных навыков; это самый быстрый способ убедиться, что файл был распознан. Если навык отсутствует в этом меню, значит, допущена ошибка в имени: файл должен называться SKILL.md, а имя директории должно состоять из строчных букв, цифр и одиночных дефисов. Тот же алгоритм, оформленный как процедура, которую может повторно запустить ваш агент, является естественным дополнением к плановому резервному копированию restic на VPS, где процесс создания резервной копии отличается от процесса её восстановления.

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

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

Во-первых, исходный код скрипта не занимает место в контекстном окне. Парсер на 300 строк потребляет только свой результат, в то время как та же логика, описанная в виде инструкций Markdown, при каждой загрузке навыка расходует объем контекста, равный своей полной длине.

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

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

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

Причина в том, что ваше description описывает, что делает навык, но не указывает, когда его использовать. Эта единственная строка — всё, с чем агент может сопоставить ваш запрос. Фраза «помогает с работой с базами данных» не соответствует ничему конкретному. Фраза «выполняет миграцию схемы для базы данных staging. Используйте, когда пользователь просит мигрировать таблицу, добавить столбец или изменить схему» содержит слова, которые человек действительно вводит, поэтому навык активируется.

Противоположная ошибка — навык, который срабатывает постоянно. Описание вроде «использовать для любых изменений кода в этом репозитории» подходит ко всему, поэтому тело навыка загружается при каждой задаче и остаётся в контексте до конца сессии. Сузьте описание до конкретного случая, который вы имели в виду. В Claude Code вы также можете задать disable-model-invocation: true в метаданных (frontmatter), что предотвратит автоматическую загрузку и сохранит навык доступным только при вводе его имени.

Третья ошибка — навык, дублирующий инструмент. Инструкции, предписывающие агенту curl API, который уже предоставлен его MCP-сервером, или выполнять grep по файлам, когда в окружении есть инструмент поиска, создают более медленный путь выполнения и два набора инструкций, которые могут противоречить друг другу. Удалите дубликат и опишите вместо этого намерение.

Не пытайтесь угадать, какая из этих трёх проблем у вас. Запустите один и тот же промпт дважды в новой сессии: один раз с включённым навыком, другой — с выключенным, а затем сравните ответы. Новая сессия важна, так как сессия, в которой вы написали навык, уже содержит всё, что в нём сказано, что скрывает пробелы в написанной версии. Плагин skill-creator от Anthropic автоматизирует это сравнение внутри Claude Code, включая генерацию промптов, которые должны и не должны активировать навык, а также измерение частоты срабатывания для каждого из них.

Это формат одного поставщика или стандарт?

Компания Anthropic опубликовала этот формат в конце 2025 года, а затем выпустила его как открытый стандарт, размещенный на agentskills.io. По состоянию на август 2026 года эта спецификация определяет обязательные поля name и description, необязательные поля license, compatibility, metadata и allowed-tools, три необязательных каталога, а также поведение поэтапной загрузки. В комплект также входит эталонный валидатор, поэтому skills-ref validate ./my-skill позволяет проверить папку на соответствие спецификации перед тем, как вы предоставите к ней доступ.

Список клиентов — это главный показатель. Одну и ту же папку могут читать Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands, opencode и другие. Microsoft публикует собственные навыки в этом формате по адресу github.com/microsoft/skills и поставляет настольный инструмент под названием Skill Recorder. Он отслеживает выполнение задачи один раз, реконструирует её как намерение с упорядоченными шагами и записывает результат в виде навыка. Если поставщик создает инструмент записи, чей формат вывода соответствует чужой спецификации, это хороший признак того, что формат перестал быть функцией одного конкретного продукта.

С чего начать

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

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

FAQ

В чем разница между навыком агента (agent skill) и MCP-сервером?

MCP-сервер (model context protocol) — это запущенный процесс, который предоставляет агенту инструменты через протокол. Он требует настройки и учетных данных, а описания его инструментов обычно занимают место в контексте на протяжении всей сессии, независимо от того, используются они или нет. Навык агента — это папка, содержащая файл SKILL.md; у него нет собственного процесса или протокола, и он потребляет около 100 токенов только тогда, когда агент решает его прочитать. Используйте MCP-сервер, чтобы предоставить агенту доступ к системе. Используйте навык, чтобы объяснить агенту процедуру эффективного использования этого доступа. Многие конфигурации используют оба варианта.

Работают ли навыки агента только с Claude Code?

Нет. Компания Anthropic разработала этот формат и выпустила его как открытый стандарт на agentskills.io. Эту же папку могут считывать Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands и другие клиенты. Разница заключается в том, где именно каждый клиент ищет файлы и какие дополнительные поля метаданных (frontmatter) он распознает. Claude Code считывает ~/.claude/skills/ и .claude/skills/, в то время как GitHub Copilot и VS Code считывают .github/skills/ в репозитории. Сам файл SKILL.md остается неизменным при переносе между ними.

Сколько навыков можно установить, прежде чем это замедлит работу?

Ограничением является бюджет токенов при запуске, а не количество навыков. Каждый установленный навык добавляет свое имя и описание — примерно 100 токенов согласно спецификации. Таким образом, тридцать навыков потребуют около 3 000 токенов еще до того, как хоть один из них будет использован. Первым делом снижается качество выбора: большое количество навыков с пересекающимися описаниями затрудняет выбор подходящего инструмента моделью. Пишите описания, которые не дублируют друг друга, и удаляйте навыки, которыми вы перестали пользоваться.

Стоит ли помещать эту инструкцию в навык или в AGENTS.md?

Задайте себе вопрос: относится ли она к каждой задаче в репозитории? Команды сборки, стиль оформления кода и правила именования применимы ко всем задачам, поэтому им место в постоянно активном файле, где их загрузка при каждом обращении оправдана. Процедуру, которую вы выполняете изредка, например, чек-лист релиза или тренировку по восстановлению данных, лучше оформить как навык. Это позволит не тратить токены на задачи, где эти действия не требуются. Раздел в AGENTS.md, который разросся до нумерованного списка шагов, обычно является навыком, ожидающим своего выделения в отдельный файл.