Кастомизация Codex: AGENTS.md, Skills, MCP и Subagents

Документация ChatGPT Codex описывает кастомизацию как набор слоёв, которые работают вместе и дополняют друг друга. Это не конкурирующие механизмы — каждый закрывает свою задачу: одни хранят инструкции, другие — контекст, третьи — повторяемые процессы, четвёртые — подключение к внешним системам. В этом обзоре разберём каждый слой, его границы применимости и порядок внедрения.

Зачем нужна кастомизация

Codex «из коробки» знает общие практики работы с кодом, но не знает вашу кодовую базу, соглашения команды и любимые инструменты. Без кастомизации агент вынужден каждый раз угадывать конвенции, что ведёт к повторяющимся ошибкам и трате контекстного окна на изучение очевидного. Кастомизация превращает эти догадки в явные правила — и закрепляет их в репозитории, чтобы не объяснять заново каждую сессию.

Согласно документации, в Codex пять основных слоёв кастомизации:

• AGENTS.md — постоянные инструкции проекта
• Memories — полезный контекст, извлечённый из прошлой работы
• Skills — переиспользуемые процессы и доменная экспертиза
• MCP — доступ к внешним инструментам и системам
• Subagents — делегирование задач специализированным подагентам

Эти слои комплементарны. AGENTS.md задаёт поведение, memories переносят локальный контекст между сессиями, skills упаковывают повторяемые процессы, а MCP подключает Codex к системам за пределами рабочего каталога.

AGENTS.md: постоянные инструкции проекта

AGENTS.md — это файл с долговременными инструкциями, который живёт рядом с кодом и применяется до того, как агент начал работу. Документация подчёркивает: держите его компактным.

Что писать в AGENTS.md

Используйте этот файл для правил, которые Codex должен соблюдать каждый раз:

• команды сборки и тестирования
• ожидания по code review
• соглашения, специфичные для репозитория
• инструкции для конкретных директорий

Если агент делает неверные предположения о кодовой базе — исправьте их в AGENTS.md и попросите агента обновить файл, чтобы фикс закрепился. Это превращает разовое исправление в постоянное правило и работает как петля обратной связи.

Когда обновлять AGENTS.md

• Повторяющиеся ошибки. Если агент регулярно ошибается в одном и том же — добавьте правило.
• Слишком много чтения. Если Codex находит нужные файлы, но читает лишние документы — добавьте маршрутизацию: какие директории или файлы приоритетны.
• Частые замечания в PR. Если вы оставляете один и тот же фидбек больше одного раза — зафиксируйте его в файле.
• В GitHub. В комментарии к PR упомяните @codex с просьбой (например, @codex добавь это в AGENTS.md), чтобы обновление сделал облачный чат.
• Автоматизация проверок. Используйте scheduled tasks для периодических проверок (например, ежедневных), которые ищут пробелы в инструкциях и предлагают, что добавить.

Документация рекомендует связывать AGENTS.md с инфраструктурой, которая эти правила обеспечивает: pre-commit hooks, линтеры, type-checkers ловят проблемы до того, как вы их увидите. Так система становится умнее в предотвращении повторяющихся ошибок.

Расположение файлов

Codex умеет загружать инструкции из нескольких мест: глобального файла в домашней директории Codex (для вас как разработчика) и файлов в репозитории (для команды). Чем ближе файл к рабочей директории — тем выше его приоритет. Глобальный файл задаёт общий стиль общения (например, стиль ревью, уровень детализации), а файлы в репозитории описывают правила команды и кодовой базы.

~/.codex/
  AGENTS.md            — глобальный (для вас как разработчика)

<корень-репозитория>/
  AGENTS.md            — для репозитория (для команды)

Skills: переиспользуемые процессы

Skills дают Codex переиспользуемые возможности для повторяющихся процессов. Документация подчёркивает: skills — лучший выбор для повторяющихся процессов, потому что они поддерживают более богатые инструкции, скрипты и ссылки, оставаясь переиспользуемыми между задачами. Skills загружаются и видны агенту (как минимум их метаданные), поэтому Codex может обнаруживать и выбирать их неявно. Это держит богатые процессы доступными, не раздувая контекст заранее.

Формат skill

Skill — это, как правило, файл SKILL.md плюс опциональные скрипты, ссылки и ассеты.

my-skill/
  SKILL.md       — обязательно: инструкции + метаданные
  scripts/       — опционально: исполняемый код
  references/    — опционально: документация
  assets/        — опционально: шаблоны, ресурсы

Директория skill может содержать папку scripts/ с CLI-скриптами, которые Codex запускает как часть процесса (например, заполнение данными или прогон валидаций). Если процесс требует внешних систем (issue-трекеры, дизайн-инструменты, серверы документации), объедините skill с MCP.

Когда использовать skills

• повторяющиеся процессы (шаги релиза, процедуры ревью, обновления документации)
• доменная экспертиза команды
• процедуры, которым нужны примеры, ссылки или вспомогательные скрипты

Skills бывают глобальными (в пользовательской директории — для вас как разработчика) и репозиторными (лежат в .agents/skills — для команды). Кладите репозиторные skills в .agents/skills, когда процесс относится к конкретному проекту; используйте пользовательскую директорию для skills, которые нужны во всех репозиториях.

Прогрессивное раскрытие

Codex использует прогрессивное раскрытие для skills:

1. начинает с метаданных (name, description) для обнаружения
2. загружает SKILL.md, только когда skill выбран
3. читает ссылки или запускает скрипты, только когда они нужны

Skills можно вызывать явно, а Codex может выбирать их и неявно, когда задача совпадает с описанием skill. Чёткие описания skill повышают надёжность срабатывания.

Пример SKILL.md:

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

MCP: подключение к внешним системам

MCP (Model Context Protocol) — стандартный способ подключить Codex к внешним инструментам и источникам контекста. Это особенно полезно для удалённых систем вроде Figma, Linear, GitHub или внутренних баз знаний, от которых зависит команда.

Используйте MCP, когда Codex нужны возможности, живущие за пределами локального репозитория: issue-трекеры, дизайн-инструменты, браузеры или общие системы документации.

Полезно держать в голове тройку:

• Host — Codex
• Client — MCP-подключение внутри Codex
• Server — внешний инструмент или источник контекста

MCP-серверы могут предоставлять:

• Tools (действия)
• Resources (читаемые данные)
• Prompts (переиспользуемые шаблоны промптов)

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

На практике MCP чаще всего полезен в связке со skills: skill описывает процесс и называет нужные MCP-инструменты.

Subagents: делегирование задач

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

Skills + MCP вместе

Skills плюс MCP — это место, где всё сходится: skills описывают повторяемые процессы, а MCP подключает их к внешним инструментам и системам. Если skill зависит от MCP, объявите эту зависимость в agents/openai.yaml, чтобы Codex автоматически установил и подключил её.

Порядок внедрения

Документация предлагает собирать кастомизацию постепенно:

1. Custom instructions через AGENTS.md, чтобы Codex следовал конвенциям репозитория. Добавьте pre-commit hooks и линтеры, чтобы эти правила автоматически обеспечивались.
2. Установите plugin, когда подходящий процесс уже существует как переиспользуемый. Иначе создайте skill и упакуйте его в plugin, когда захотите поделиться с другими.
3. Подключите MCP, когда процессу нужны внешние системы (Linear, GitHub, серверы документации, дизайн-инструменты).
4. Добавьте subagents, когда будете готовы делегировать шумные или специализированные задачи подагентам.

Этот порядок даёт базовый уровень дисциплины (AGENTS.md + хуки) раньше, чем усложнение через skills и MCP, и оставляет subagents напоследок — когда уже понятно, какие задачи стоит изолировать.

Итог

Кастомизация Codex — это не про одну «магическую» настройку, а про композицию пяти слоёв. AGENTS.md фиксирует правила, memories переносят контекст, skills упаковывают процессы, MCP подключает внешние системы, subagents изолируют специализированные задачи. Хорошо настроенный репозиторий использует их вместе: AGENTS.md держит инструкции рядом с кодом, skills повторяют то, что команда делает каждый день, MCP закрывает интеграции, а subagents помогают не утонуть в шуме.