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

Что такое навык агента

Навык агента — это папка на диске, содержащая файл с именем 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. Спецификация рекомендует ограничивать объем тела 5000 токенов, а размер файла — 500 строками. Файлы в references/ и scripts/ на этом этапе по-прежнему ничего не стоят. Справочный файл загружается только в том случае, если инструкции направляют к нему агента. С упакованным скриптом ситуация иная: агент выполняет его через shell, поэтому исходный код скрипта никогда не попадает в окно контекста, в него передается только результат выполнения.

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

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

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

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

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

Кратко: инструмент дает агенту новую возможность, а навык в основном дает ему суждение о тех возможностях, которые у него уже есть. Если навык и добавляет возможность, то через встроенный скрипт, который агент запускает с помощью уже имеющейся у него оболочки (shell). Если шаг должен каждый раз давать точный, проверенный результат, вам нужен инструмент или скрипт. Если к шагу нужно последовательно применять один и тот же подход, вам нужен навык. Навык может состоять только из логики принятия решений и при этом оставаться тем, к чему вы прибегаете чаще всего, как показывает Ponytail, который подталкивает агента к внесению минимально возможных изменений: он не добавляет новых функций, а лишь меняет способ использования уже имеющихся. Это суждение может работать и в обратную сторону: навык unlazy, который обходит дерево глубины (Depth Tree), чтобы агент не объявлял задачу выполненной раньше времени, использует тот же прием, но направлен на тщательность, а не на сдержанность.

Навык агента не является MCP-сервером

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

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

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

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

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

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

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

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

В Claude Code персональные навыки хранятся в ~/.claude/skills/<name>/SKILL.md и применяются ко всем вашим проектам. Проектные навыки хранятся в .claude/skills/<name>/SKILL.md и фиксируются в git, поэтому они доступны каждому человеку и каждому агенту, работающему с этим репозиторием. GitHub Copilot и VS Code считывают проектные навыки из .github/skills/ и .agents/skills/, а также из .claude/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, а спецификация Agent Skills требует, чтобы имя состояло из строчных букв, цифр и одиночных дефисов, соответствующих названию директории. Тот же алгоритм, оформленный как процедура, которую ваш агент может запустить повторно, является естественным дополнением к плановому резервному копированию 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) — это запущенный процесс, который предоставляет инструменты агенту через протокол. Он требует настройки и учетных данных, а его полные определения инструментов занимают контекст на протяжении всей сессии, если клиент не откладывает их загрузку (как это по умолчанию делает Claude Code). Навык агента — это папка, содержащая файл 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/, .claude/skills/ или .agents/skills/ в репозитории. Сам файл SKILL.md остается неизменным при переносе между ними.

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

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

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

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