Навыки: упаковать повторяемую работу

Есть задачи, которые вы объясняете агенту снова и снова: как собрать описание MR, как прогнать e2e на стенде, как оформить миграцию. Держать это в AGENTS.md дорого — файл читается в каждой сессии. Писать каждый раз в промпте — утомительно и неодинаково. Навык (skill) решает именно это: инструкция, которая лежит рядом и подгружается только тогда, когда нужна.

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

Навык — это каталог с обязательным файлом SKILL.md. В начале файла — YAML-шапка с двумя обязательными полями, name и description, дальше — инструкции в свободной форме. Рядом могут лежать необязательные папки:

• scripts/ — исполняемые скрипты, когда нужен детерминированный результат;
• references/ — справочные материалы, схемы, примеры;
• assets/ — шаблоны и файлы, которые навык копирует или заполняет;
• agents/openai.yaml — метаданные для интерфейса, политика вызова, зависимости от MCP.

Формат основан на открытом стандарте Agent Skills. Если вы проходили курс по навыкам в Claude Code, структура будет знакомой: это тот же стандарт.

Как агент находит навык: постепенное раскрытие

Главная идея — постепенное раскрытие (progressive disclosure). В начале сессии Codex видит только список: имя, описание и путь каждого навыка. Под этот список по умолчанию отводится не больше 2% контекстного окна модели, или 8000 символов, если размер окна неизвестен. Бюджет меняется ключом skills.max_context_tokens, максимум — 10 000 токенов. Если навыков много, Codex сначала укорачивает описания, а потом может часть навыков вовсе не показать и предупредить об этом.

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

Отсюда практический вывод: решение «включать навык или нет» модель принимает по одному полю description. Описание — это не аннотация для людей, а условие срабатывания.

Где лежат навыки

В монорепозитории удобно класть общие навыки в корень, а специфичные — в папку модуля: Codex просканирует все уровни от текущей папки вверх. Если два навыка называются одинаково, Codex их не объединяет, и в списке окажутся оба — следите за уникальностью имён. Символьные ссылки поддерживаются: можно держать навыки в отдельном репозитории и подключать симлинком.

Обратите внимание: папка называется .agents, а не .codex. В песочнице workspace-write каталоги .agents и .codex защищены от записи, поэтому агент не может молча переписать собственные навыки во время работы.

Как вызвать навык

Явно. В CLI и IDE наберите $ и имя навыка или откройте список командой /skills:

$mr-description опиши изменения в текущей ветке относительно main

Неявно. Codex сам выбирает навык, если задача совпадает с его описанием. Попросите «подготовь описание MR» — и навык с подходящим description подключится без упоминания.

Неявный вызов можно запретить для отдельного навыка — например, для того, который что-то публикует или удаляет:

policy:
  allow_implicit_invocation: false

Тогда навык сработает только по явному $release-notes.

Встроенные помощники

Два системных навыка стоит знать сразу.

• $skill-creator задаёт вопросы — что делает навык, когда должен срабатывать, нужны ли скрипты — и собирает черновик. По умолчанию получается навык только из инструкций.
• $skill-installer ставит кураторские навыки из github.com/openai/skills, например $skill-installer linear. Его можно попросить скачать навыки и из другого репозитория.

Codex замечает новые и изменённые навыки автоматически; если навык не появился — перезапустите сессию. В десктопном приложении на macOS есть ещё Record & Replay: вы показываете процесс один раз, а Codex составляет из записи черновик навыка.

Навык, AGENTS.md, MCP или плагин

Эти механизмы легко перепутать. Простое правило выбора:

• AGENTS.md — то, что должно действовать всегда: команды сборки и тестов, соглашения, запреты. Подробнее — в уроке про AGENTS.md в большом репозитории.
• Навык — процедура для определённого типа задач: шаги, формат результата, шаблоны. Нужна иногда, но тогда — целиком.
• MCP-сервер — доступ к живым данным и действиям во внешней системе: GitLab, база, браузер. Навык может учить агента, в каком порядке вызывать инструменты сервера.
• Плагин — упаковка для распространения: несколько навыков, MCP-серверы и хуки, которые ставятся одной операцией. Разберём в уроке про плагины.

Признак, что правило пора вынести из AGENTS.md в навык: оно длиннее десятка строк и нужно в одной задаче из пяти.

Как выключить навык

Если навык мешает — срабатывает не к месту или устарел, — его можно выключить, не удаляя:

[[skills.config]]
path = "/Users/me/.agents/skills/old-deploy/SKILL.md"
enabled = false

После правки config.toml перезапустите Codex.

Если вы читали старые инструкции. Раньше повторяемые промпты хранили в ~/.codex/prompts/*.md и вызывали как /prompts:<имя>. Этот механизм (custom prompts) объявлен устаревшим, вместо него используйте навыки.

Какие навыки нужны веб-команде

Хорошие первые кандидаты — то, что вы уже делаете по шаблону:

• описание MR по диффу и задаче из трекера;
• разбор упавшего e2e-теста: воспроизвести, собрать логи, найти причину до правки;
• создание миграции плагина OctoberCMS по принятым в проекте правилам;
• проверка вёрстки по матрице разрешений;
• релиз-ноутс для клиента по списку смерженных MR.

У каждого из этих примеров один понятный результат и стабильная процедура. Навык «всё про наш проект» — плохой кандидат: он сработает не вовремя и съест контекст.