Описание MCP-инструмента — это фраза, привязанная к одной вызываемой функции:
что она делает, что принимает, меняет ли что-нибудь. Оно едет с каждым запросом,
который клиент отправляет модели, вместе с описаниями всех остальных
инструментов. Скилл — это папка с файлом SKILL.md внутри, где лежит процедура:
сделай это, потом проверь то, а вот об этом спроси, — и её текст загружается
только тогда, когда модель решит, что ваш запрос ей соответствует.
В этом вся разница, и она про то, когда текст оказывается в контексте, а не про то, что в нём написано. Описания — плата за вход: вы платите за все, на каждом ходу, всегда. Инструкции скилла бесплатны, пока не понадобятся. Поэтому абзац, который невозможно оправдать в описании инструмента — триста слов о том, как разбирать накопившиеся записи встреч, — совершенно уместен в скилле.
Статья о том, как решить, какая инструкция куда идёт. Если сам протокол для вас в новинку, начните с материала что такое MCP-сервер — там словарь, а чем MCP отличается от плагинов и интеграций объясняет, где MCP стоит относительно прежних способов связывать вещи.
В спецификации MCP определение инструмента — небольшая фиксированная форма.
В ней есть name, необязательный человекочитаемый title, description,
inputSchema с описанием аргументов, необязательный outputSchema и
annotations — необязательные свойства, описывающие поведение инструмента,
например, только ли он читает. Клиент забирает весь список вызовом tools/list
и кладёт его перед моделью — именно поэтому инструменты MCP управляются
моделью: она сама выбирает нужный по ходу разговора.
Эта форма хорошо делает ровно одно: объясняет модели, что делает отдельный вызов, чтобы она выбрала правильный. Ещё в трёх вещах она плоха по устройству.
Она не описывает порядок. Ничто в определении инструмента не может сказать:
«сначала вызови list_channels, потом share_to_channel, потому что канал
должен существовать и его должен выбрать пользователь». Каждое описание —
остров.
В неё мало помещается. Каждое описание лежит в контексте при каждом запросе в каждом разговоре — включая все те разговоры, которые этого инструмента никогда не коснутся. Сервер с пятнадцатью инструментами и абзацем на каждый тратит заметную часть окна контекста ещё до того, как пользователь что-то напечатал.
В неё не записать ваши решения по ситуации. «Если не уверен, кому это можно видеть, повесь на запись тег, а не публикуй её» — это политика, а не описание функции. Две разные команды захотят от одного и того же инструмента двух разных политик.
Один клапан в протоколе всё же есть: при подключении клиента сервер может
вернуть строку instructions, и клиент может добавить её в системный промпт —
раньше списка инструментов. Это правильное место для короткой вводной: что это
за сервер, к чему он подключён, с чем быть осторожнее. Две оговорки. Текст всё
равно живёт всю сессию, поэтому он остаётся коротким. И спецификация говорит,
что клиенты могут его использовать, а не обязаны, — так что показывают ли его
модели на самом деле, зависит от клиента.
Скилл — это каталог с файлом SKILL.md: YAML-фронтматтер с полями name и
description, а дальше инструкции в markdown. Рядом можно положить и другое —
scripts/ с исполняемым кодом, references/ с подробной документацией,
assets/ с шаблонами, — и агент подтянет это, только если инструкции его туда
отправят.
Модель загрузки называется постепенным раскрытием (progressive disclosure), и спецификация раскладывает её на три стадии:
name и description
каждого доступного скилла — по бюджету примерно 100 токенов на скилл.
Достаточно, чтобы понять, когда он может пригодиться, и не больше.SKILL.md. Рекомендация — держать его примерно до 5000 токенов,
а сам файл — до 500 строк.То есть цена двадцати установленных скиллов — двадцать коротких описаний. Цена двадцати длинных описаний инструментов — двадцать длинных описаний инструментов, на каждом ходу. Ради этой асимметрии слой и появился.
Формат не привязан к клиенту. Agent Skills разработала Anthropic и выпустила как
открытый стандарт, опубликованный на agentskills.io; в витрине клиентов там
перечислены десятки продуктов, читающих одну и ту же папку, — среди них
Claude Code, Claude, ChatGPT и Codex, Cursor, VS Code, GitHub Copilot,
Gemini CLI, Goose, Roo Code, Kiro, Junie, Amp, Factory, Tabnine,
Snowflake Cortex Code и Databricks Genie Code. Проверено 14 августа 2026 года.
Обязательный фронтматтер намеренно тощий. name — до 64 символов, строчные
буквы, цифры и дефисы, и он должен совпадать с именем родительского каталога.
description — до 1024 символов, и в нём должно быть сказано и что скилл делает,
и когда его применять: эта строка — единственное основание, по которому агент
решает, открывать ли файл. Необязательные поля — license, compatibility,
metadata и экспериментальное allowed-tools.
Полю description стоит уделять больше внимания, чем ему обычно уделяют.
«Помогает с заметками по встречам» надёжно не совпадёт ни с чем; «разбирает и
раскладывает свежие записи: ставит теги, называет говорящих, публикует те, что
относятся к каналу команды; применять, когда пользователь просит навести
порядок, разобрать накопившееся или наверстать пропущенное» — совпадёт.
Между описаниями отдельных вызовов и скиллами по требованию есть слой, который не то и не другое: файлы, которые агент читает в начале сессии независимо от того, о чём вы спросили.
AGENTS.md — самый простой вариант: обычный markdown, обязательных полей нет, читается ближайший файл вверх по дереву каталогов. Его собственный сайт сообщает о более чем 60 000 открытых проектов, где он используется, и перечисляет поддержку в OpenAI Codex, Google Jules и Gemini CLI, агентах Claude, кодовом агенте GitHub Copilot, Aider, VS Code, Cursor, Zed, Warp, Factory, goose, Roo Code, Devin и Junie. Проверено 14 августа 2026 года.
Правила Cursor — та же идея, но с выключателем. Они лежат в .cursor/rules
как файлы .mdc, и когда каждое из них подключается, решают три поля
фронтматтера: alwaysApply: true кладёт правило в любую сессию чата;
description позволяет агенту самому оценить уместность; globs подключают
правило, когда открыт подходящий файл; а если не задано ничего из этого, правило
приходит, только когда вы упомянете его через @. Cursor поддерживает и
AGENTS.md, и теперь напрямую Agent Skills — скиллы лежат в .cursor/skills/
или .agents/skills/, — а вместе с ними есть инструмент миграции, который
превращает подходящие динамические правила и слэш-команды в скиллы. Проверено
14 августа 2026 года.
Перечитайте эти два абзаца, и закономерность видна: форматы сошлись, модели
загрузки — нет. SKILL.md сегодня читают все. Но правило с alwaysApply и
блок в AGENTS.md живут в масштабе сессии, а скилл — в масштабе задачи, и
никакая совместимость форматов этого не меняет.
Практическое следствие — правило, которое стоит больше, чем детали форматов:
| Куда идёт | Что там уместно | Чего это стоит |
|---|---|---|
description инструмента |
Одна фраза: что делает этот вызов и что он меняет | Каждый запрос, всегда |
instructions сервера |
Короткая вводная про сервер целиком | Каждая сессия с этим сервером |
AGENTS.md, всегда включённые правила |
Факты, верные для любой задачи в этом репозитории | Каждая сессия в этом проекте |
SKILL.md |
Процедуры, политики, разобранные примеры, решения по ситуации | Только когда задача совпала |
Всё длинное, всё условное, всё, что верно лишь иногда, — в скилл. Типичная
ошибка: положить полторы сотни строк процедуры под конкретный продукт в
глобальный AGENTS.md, где они лежат в контексте, пока человек полдня правит
совсем другой бэкенд.
У Speak-Y есть свой MCP-сервер, и он неплохая иллюстрация: оба слоя там заметно делают разную работу.
Описания инструментов покрывают вызовы: найти записи, прочитать транскрипт,
саммари или список задач, перечислить каналы и теги — а при запущенном
приложении ещё и повесить на запись тег, переименовать говорящего, поменять
заголовок, перетранскрибировать или отправить запись в канал команды. У каждого
есть аннотация о том, читает он или меняет: благодаря ей клиент может спросить
перед выполнением меняющих, а --read-only становится одним переключателем, а
не списком имён инструментов, который надо помнить. Чтение идёт локально по
библиотеке на вашей машине; меняющие команды проходят через запущенное
приложение и там же попадают в журнал — подробнее об этом
что делает право на запись безопасным.
Скилл покрывает работу целиком. Когда вы ставите интеграцию из
Настройки → Интеграции, Speak-Y кладёт рядом с конфигурацией сервера
скилл-организатор: с чего начинать, разбирая кучу записей, когда правильный
ответ — тег, а когда — канал, какие действия подтверждать перед выполнением.
Описания такого не вместят, а строке instructions сервера и пытаться не стоит.
Написан он так, как поощряет модель загрузки. Один подробный файл лежит в одном
месте, а каждый клиент получает короткую ссылку на него в том формате, который
читает: SKILL.md для Claude Code, правило .mdc для Cursor, помеченный блок
внутри AGENTS.md для Codex, такой же блок в GEMINI.md для Gemini CLI.
Клиенты с сессионным масштабом получают именно указатель — как раз потому, что
масштаб сессионный: полторы сотни строк про заметки со встреч не должны висеть
в контексте, пока вы отлаживаете чужой бэкенд. Блоки стоят между маркерами,
поэтому переустановка заменяет только этот участок и не трогает остальной файл.
Сам MCP-сервер бесплатен на любом тарифе, включая Free. Установка в один клик и ручная настройка под каждый клиент описаны в разделе AI-ассистенты (MCP).
Три вопроса, по порядку.
Инструкция описывает один вызов? Тогда это описание инструмента, и уместиться оно должно в одну-две фразы. Если пишете третью — вы нашли скилл.
Она верна для любой сессии, независимо от задачи? Тогда ей место в
AGENTS.md или во всегда включённом правиле — но честно проверьте часть
«независимо от задачи». «В этом репозитории pnpm» проходит. «А вот наш процесс
разбора встреч» — нет.
Она описывает процедуру с шагами, выборами или исключениями? Скилл.
Отнеситесь к name и description всерьёз: всю маршрутизацию делают именно эти
две строки, — а всё длинное вынесите в файл в references/ рядом с SKILL.md,
а не внутрь него.
Ошибётесь в дешёвую сторону — получите раздутый контекст и худшее попадание на всех посторонних вопросах. Ошибётесь в дорогую, втиснув процедуру в описания инструментов, — и модель будет читать вашу политику на каждом ходу и всё равно может ей не последовать: описание читается как документация к функции, а не как указание, которому надо подчиняться.
Если хотите увидеть разницу предметно, быстрее всего написать один скилл под работу, которую вы действительно повторяете, и сравнить его с промптами, которые вставляли раньше. Промпты, чтобы спросить AI про свои встречи — неплохой источник кандидатов: те, что вы запускаете больше двух раз, и есть те, которым место в файле.
Описание инструмента — одна фраза, привязанная к одной вызываемой функции; её пишет автор сервера, и она уходит модели с каждым запросом в составе списка инструментов. Скилл — это папка с файлом SKILL.md, в котором лежит процедура: несколько шагов, несколько инструментов, решения по ситуации. Пока модель не решит, что задача подходит, в контексте есть только имя и описание скилла. Описания отвечают на вопрос «что делает этот вызов», скиллы — на вопрос «как выполнять эту работу».
Для задач в один вызов — нет. Он нужен, когда работа занимает несколько инструментов в определённом порядке, когда выбор между двумя инструментами зависит от контекста, который описаниям не унести, или когда одну и ту же процедуру нужно повторять одинаково от сессии к сессии. Хорошие описания делают правильным каждый вызов; скилл делает повторяемой последовательность вызовов.
Нет. Agent Skills разработала Anthropic и выпустила как открытый стандарт, опубликованный на agentskills.io, и в витрине клиентов там перечислены десятки продуктов — среди них Claude Code, ChatGPT и Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie и Factory. Проверено 14 августа 2026 года.
AGENTS.md — обычный markdown без обязательных полей, который агент читает из ближайшего каталога вверх по дереву, и загружается он на всю сессию независимо от того, о чём вы спросили. Тело скилла загружается только после того, как агент сопоставит ваш запрос с его описанием. Полезны оба, но всё длинное относится в скилл: содержимое AGENTS.md занимает контекст в каждой сессии, включая те, которые не имеют к нему никакого отношения.
Спецификация Agent Skills рекомендует держать основной SKILL.md в пределах 500 строк и примерно 5000 токенов, а подробный справочный материал выносить в отдельные файлы, которые агент подгружает, только когда они понадобятся. На имя и описание заложено около 100 токенов — именно за них платит каждая сессия.