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

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

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

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

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

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

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

Этот аргумент объясняет ценность данного формата, и дело здесь в контексте, а не в функциональных возможностях. Загрузка происходит поэтапно, что в спецификации называется прогрессивным раскрытием (progressive disclosure).

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

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

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

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

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

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

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

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

Навык агента — это не 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 токенов. Таким образом, тридцать навыков занимают около 3000 токенов еще до того, как какой-либо из них будет использован. Первым делом снижается качество сопоставления, а не скорость: большое количество навыков с пересекающимися описаниями затрудняет выбор подходящего инструмента моделью. Пишите описания, которые не дублируют друг друга, и удаляйте навыки, которыми перестали пользоваться.

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

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