AGENTS.md, CLAUDE.md, SKILL.md и MCP: что выбрать

Что выбрать: AGENTS.md, CLAUDE.md, SKILL.md или MCP?

Выбирайте по тому, что требуется сохранить. Для постоянных правил Codex использует AGENTS.md, а Claude Code использует CLAUDE.md. Повторяемую процедуру оформляйте как SKILL.md. Если агенту нужны актуальные данные или действие во внешней системе, подключайте MCP.

AGENTS.md, CLAUDE.md, SKILL.md и MCP не являются четырьмя вариантами одного файла. Первые два задают постоянный контекст конкретного продукта. Skill хранит повторяемый процесс и загружается по необходимости. MCP подключает внешние данные и действия.

Здесь skill означает переносимую рабочую процедуру, issue tracker - систему задач, permissions - правила доступа, sandbox - изолированную среду, а hooks и CI - автоматические проверки проекта.

В сложной задаче не обязательно выбирать один механизм. Правила репозитория могут требовать обязательной проверки перед релизом. Сам чек-лист проверки хранится в skill. MCP даёт доступ к issue tracker, а техническая политика запрещает публикацию без подтверждения человека.

• AGENTS.md или CLAUDE.md: что агент должен знать постоянно в этом проекте.
• SKILL.md: как выполнить определённую повторяемую работу.
• MCP: к каким данным и действиям агент может подключиться.
• Permissions, sandbox, hooks или CI: что технически разрешено, запрещено или обязательно проверяется.

Если сам термин Agent Skill пока незнаком, начните с материала что такое Agent Skills.

Если механизм уже выбран и нужен первый рабочий пакет, используйте практическую инструкцию как создать Agent Skill с нуля.

Чем AGENTS.md, CLAUDE.md, SKILL.md и MCP отличаются на практике?

Механизмы выполняют разные роли в рабочем процессе. Постоянная инструкция влияет на каждую подходящую сессию. Skill добавляет нужную процедуру по запросу. MCP создаёт соединение с инструментом или источником данных.

Открытая спецификация Agent Skills задаёт общее ядро, но не обещает одинаковое поведение любого SKILL.md в каждом клиенте. Папки установки, расширения frontmatter и правила разрешений у продуктов отличаются.

Когда правила проекта нужно хранить в AGENTS.md?

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

Codex строит цепочку инструкций от общего к частному. Сначала он проверяет глобальный файл в Codex home. Затем проходит от корня проекта к текущей рабочей директории. В каждой папке учитывается не более одного подходящего файла: AGENTS.override.md, затем AGENTS.md, затем настроенное fallback-имя. Более близкая к рабочей папке инструкция идёт позже и может уточнять общую.

В монорепозитории корневой AGENTS.md может требовать единый формат отчёта, а файл внутри отдельного пакета может назначать свой набор тестов.

• Команды установки, сборки и проверки.
• Карта важных директорий.
• Правила именования и изменения публичных контрактов.
• Обязательные доказательства готовности.
• Ограничения, относящиеся ко всей области файла.

Не переносите в AGENTS.md большой редкий регламент. Codex собирает проектные инструкции один раз на run, а общий размер ограничен настройкой project_doc_max_bytes. Для многошаговой процедуры лучше оставить короткое правило вызова, а детали вынести в skill.

Когда проекту нужен CLAUDE.md?

Используйте CLAUDE.md, когда Claude Code должен получать один и тот же проектный контекст в каждой сессии. Это место для архитектуры, build-команд, соглашений команды и конкретных правил, которые действуют постоянно.

Claude Code поддерживает несколько уровней: управляемые правила организации, личный пользовательский файл, общий проектный CLAUDE.md или .claude/CLAUDE.md, а также CLAUDE.local.md для личных настроек конкретного проекта. Файлы от рабочей директории вверх загружаются при старте. Вложенные инструкции могут добавляться, когда Claude начинает работать с файлами соответствующей подпапки.

Для большой кодовой базы можно вынести узкие правила в .claude/rules и привязать их к путям. Если раздел превратился в многошаговую процедуру или нужен лишь иногда, ему ближе формат skill.

CLAUDE.md и AGENTS.md нельзя считать взаимозаменяемыми без настройки. Claude Code по умолчанию читает CLAUDE.md, а не AGENTS.md. Официальный вариант совместного источника для Claude Code заключается в импорте @AGENTS.md из CLAUDE.md. На Windows импорт практичнее символической ссылки, для которой могут потребоваться дополнительные права. Codex использует AGENTS.md, если другое fallback-имя не настроено явно.

Когда повторяемый процесс стоит оформить как SKILL.md?

Создавайте skill, когда одна и та же задача требует узнаваемого момента запуска, порядка шагов и проверяемого результата. Это может быть аудит навыка, подготовка отчёта, выпуск статьи, проверка интерфейса или развёртывание приложения.

По открытой спецификации минимальный skill хранится в папке с SKILL.md. В служебном заголовке frontmatter обязательны название (name) и описание (description). В теле находится рабочая инструкция. Рядом могут лежать скрипты, справочники и шаблоны.

1. Обнаружение

   Агент сначала видит имя и короткое описание доступных skills.

2. Активация

   При совпадении задачи с description или при явном вызове загружается полный SKILL.md.

3. Исполнение

   Справочники, assets и scripts используются только тогда, когда нужны процессу.

Ядро Agent Skills переносимо между совместимыми продуктами, но установка различается. Codex ищет репозиторные skills в .agents/skills, а Claude Code ищет их в .claude/skills. Claude Code также поддерживает собственные поля управления вызовом и исполнением. Поле allowed-tools в общей спецификации остаётся экспериментальным, поэтому его нельзя считать одинаковым разрешением во всех клиентах.

Практическую установку для обоих продуктов смотрите в инструкции по Agent Skills в Codex и Claude Code.

После подключения проверьте пользу на одинаковых задачах по статье как оценить эффективность Agent Skill.

Когда вместо файла инструкций нужен MCP?

MCP нужен, когда агенту требуется получить внешний инструмент или актуальные данные. Через MCP агент может читать документацию, запрашивать базу, работать с браузером, получать задачи из issue tracker или вызывать API.

Model Context Protocol использует архитектуру host, client и server. AI-приложение выступает host и создаёт отдельный client для каждого сервера.

• Tools: функции, которые выполняют действия.
• Resources: данные и материалы для контекста.
• Prompts: повторно используемые шаблоны взаимодействия.

Локальный сервер обычно работает как отдельный процесс через STDIO. Удалённый сервер подключается через Streamable HTTP и может требовать OAuth. Codex хранит MCP-настройки в config.toml, включая проектный вариант для доверенных проектов. Claude Code использует собственные local, project и user scopes, а общий проектный сервер может описываться в .mcp.json.

MCP не заменяет skill. Сервер даёт функцию create_issue, но не обязан знать, когда её разрешено вызывать, какие поля проверить и кто подтверждает публикацию. Skill способен объяснить порядок работы с issue tracker, но без подключённого инструмента не получит актуальную задачу.

Перед подключением проверьте происхождение сервера, запрашиваемые OAuth scopes, доступные tools и последствия каждого вызова. Порядок проверки пакета инструкций собран в чек-листе проверки AI-навыка.

Можно ли использовать AGENTS.md, CLAUDE.md, SKILL.md и MCP вместе?

Да. В сложном рабочем процессе механизмы можно сочетать, если каждый слой отвечает за свою часть.

1. Постоянные правила Codex

   AGENTS.md сообщает, где находятся схемы данных, какие тесты обязательны и что production нельзя менять без подтверждения.

2. Постоянный контекст Claude Code

   CLAUDE.md даёт Claude Code эквивалентный контекст для той же кодовой базы с учётом продуктовых отличий.

3. Рабочая процедура

   Skill описывает этапы, входные данные, критерии результата и точку остановки перед внешним действием.

4. Внешнее подключение

   MCP подключает CRM, issue tracker или корпоративную документацию с ограниченными правами.

5. Техническая граница

   Permission policy требует подтверждения перед записью во внешнюю систему или отправкой сообщения.

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

Почему инструкция не заменяет техническое ограничение?

Текст говорит модели, как следует поступить. Enforcement определяет, что система фактически позволит сделать. Формулировка о запрете отправки без проверки полезна, но не равна блокировке инструмента отправки.

• Permission rules с режимами allow, ask и deny.
• Sandbox для файловой системы и сети.
• OAuth scopes и отдельные тестовые учётные записи.
• Allowlist доступных MCP-серверов и tools.
• Hook, который блокирует конкретное действие.
• CI-проверка, без которой изменение нельзя принять.
• Ручное подтверждение перед внешним или необратимым действием.

У skill могут быть скрипты. MCP по определению может предоставить действие. Поэтому риск определяется сочетанием инструкции, доступных инструментов, окружения и разрешений.

Как выбрать механизм за пять шагов?

Начните с одного рабочего требования и последовательно проверьте постоянство, повторяемость, внешние данные и цену ошибки. Не начинайте с создания четырёх файлов.

1. 1. Нужен ли этот контекст почти в каждой задаче?

   Если да, поместите короткое правило в AGENTS.md для Codex или CLAUDE.md для Claude Code. Для двух клиентов спроектируйте общий источник и продуктовые адаптации.

2. 2. Это отдельная повторяемая процедура?

   Если да, оформите skill. Опишите точный trigger, шаги, ограничения и критерии готовности.

3. 3. Нужны ли внешние данные или действия?

   Если да, добавьте MCP или другой поддерживаемый tool layer. Отдельно определите сервер, transport, аутентификацию и минимальные scopes.

4. 4. Может ли ошибка изменить внешний мир или раскрыть данные?

   Если да, настройте permissions, sandbox, allowlist, подтверждение человека и журналирование.

5. 5. Можно ли проверить результат на тестовом сценарии?

   Зафиксируйте ожидаемый итог, проведите пробный запуск без production-доступа и сохраните доказательства. После изменения skill, MCP-сервера, модели или разрешений повторите проверку.

Частые ошибки: хранить длинный редкий workflow в постоянном контексте, прятать обязательное правило только внутри skill, ожидать подключения сервиса от SKILL.md, считать MCP готовым регламентом и выдавать серверу больше прав, чем требует сценарий.

Итоговая схема проста. AGENTS.md и CLAUDE.md держат постоянные правила своих продуктов. SKILL.md хранит вызываемый процесс. MCP даёт инструменты и данные. Техническая политика ограничивает действия.

Три примера выбора без лишней архитектуры

Правила репозитория храните в AGENTS.md или CLAUDE.md, повторяемую процедуру — в SKILL.md, а доступ к CRM или другому внешнему сервису — через MCP. Сочетайте механизмы только тогда, когда задаче действительно нужны разные слои.

Где сверить поведение продуктов и спецификаций?

• Custom instructions with AGENTS.mdОбнаружение, область и приоритет инструкций Codex.
• Build skills in CodexЗагрузка, вызов и области skills в Codex.
• How Claude remembers your projectCLAUDE.md, auto memory и область проектных инструкций.
• Extend Claude CodeСравнение CLAUDE.md, Skill, MCP и технических ограничений.
• Agent Skills specificationПереносимое ядро SKILL.md и экспериментальное поле allowed-tools.
• MCP architecture overviewHost, client, server, tools, resources, prompts и transports.