Codex skills — это папка с файлом инструкции, в которой записана одна повторяемая процедура: как оформлять отчёт об ошибке, как готовить релиз, как проверять миграцию. Агент находит такую папку по описанию или по прямому вызову и действует по ней вместо импровизации. Для команды это способ превратить устную договорённость в файл, который лежит рядом с кодом, проходит ревью и одинаково работает у всех участников.
Что внутри папки
Skill в Codex — каталог с обязательным файлом SKILL.md, где в начале указаны имя и описание, а ниже порядок действий. Скрипты, справочные материалы и ресурсы добавляются по мере нужды.
По документации OpenAI, минимальный набор состоит из одного файла SKILL.md с двумя полями в начале: имя и описание. Остальное необязательно: каталог со скриптами, каталог со справочными материалами, каталог с ресурсами и файл настроек для интерфейса. Описание играет роль заголовка в каталоге: по нему агент решает, подходит ли пакет к текущей задаче.
Главное в этом файле — описание. Пишите его так, как вы объяснили бы новому коллеге, в какой ситуации открывать эту инструкцию: назовите тип задачи, входные данные и ожидаемый результат. Фраза вроде «помогает с кодом» бесполезна, потому что подходит ко всему, а фраза «готовит запись о выпуске по списку закрытых задач» работает как точный ярлык.
- Имя: короткое и уникальное в своей области.
- Описание: одна-две фразы о том, что делает пакет и когда его подключать.
- Тело инструкции: пошаговый порядок, критерии готовности, примеры.
- Скрипты: детерминированные действия, которые лучше выполнять кодом, чем словами.
- Справочные материалы: длинные таблицы и регламенты, которые загружаются по необходимости.
Принцип такой же, как у навыков в Claude Code: короткое описание лежит в контексте постоянно, а длинное тело подгружается, когда пакет выбран. Про рабочие процессы Codex в связке с ChatGPT мы писали в материале Codex в ChatGPT для команды разработки.
Где лежит пакет
Область действия пакета определяется местом хранения. Документация описывает четыре области: репозиторий, пользователь, администратор и встроенные навыки, и от выбора зависит, увидит ли инструкцию вся команда или только вы.
| Область | Где лежит | Для чего подходит |
|---|---|---|
| Репозиторий: текущий каталог | .agents/skills в каталоге, где идёт работа | Правила одного модуля или сервиса |
| Репозиторий: родительские каталоги | .agents/skills выше по дереву каталогов, вплоть до корня репозитория | Общие процедуры всего репозитория |
| Пользователь | ~/.agents/skills в домашнем каталоге | Личные приёмы, которые вы переносите между проектами |
| Администратор | /etc/codex/skills | Общие процедуры по умолчанию для всех на машине |
Каталог навыков ищется в текущем каталоге и в родительских, поэтому если в одном репозитории лежит несколько сервисов, папка внутри модуля работает только там, где вы находитесь: правила для платёжного модуля видны тем, кто работает внутри него. Папка в корне репозитория подходит для сквозных процедур вроде оформления коммитов, а личный уровень оставляйте для привычек, которые вы пока примеряете на себя.
Командные процедуры кладите в репозиторий: тогда они версионируются вместе с кодом и меняются через обычный запрос на слияние. Личное оставляйте в домашнем каталоге. Так новичок, склонировавший репозиторий, получает рабочие процедуры сразу и без отдельной настройки своей машины, а ревьюер видит любое изменение порядка действий в обычной истории правок. Административный уровень пригодится тому, кто должен задать одинаковые процедуры по умолчанию на всех рабочих машинах. Встроенные навыки OpenAI поставляются отдельным системным уровнем, и вашей правке они недоступны.
Явный и неявный вызов
Подключить пакет можно двумя способами. Явный: в интерфейсе ChatGPT пакет выбирают через знак @, в командной строке Codex называют его через знак $ и имя пакета. Неявный: агент сам выбирает пакет, когда задача совпадает с его описанием. Оба способа полезны, но требуют разной аккуратности.
- Явный вызов подходит для ответственных процедур: релиз, миграция, публикация. Вы сами решаете, когда пакет работает.
- Неявный вызов удобен для рутины: оформление коммита, формат отчёта. Здесь важно точное описание.
- Расплывчатое описание приводит к ложным срабатываниям, слишком узкое оставляет пакет без дела.
- Для рискованных действий в файле agents/openai.yaml можно запретить неявный вызов, и тогда агент запускает пакет только по вашей команде.
Практическое правило выбора: если ошибка в процедуре дорого стоит, вызывайте пакет явно и читайте результат; если процедура безобидна и повторяется по нескольку раз в день, доверьте выбор агенту и бегло просматривайте итог. Такой подход экономит внимание там, где оно нужно меньше всего.
Для создания заготовки есть встроенный помощник skill-creator, а для широкого распространения пакеты упаковывают в плагины вместе с коннекторами. Установка из внешнего источника равна запуску чужого кода у вас на машине, поэтому читайте содержимое и скрипты до первого применения. Общий взгляд на подключение Codex к рабочим процессам компании дан в статье Codex API для компании.
Проверка на задаче
Хорошо выглядящая инструкция остаётся гипотезой до первого опробования. Проверяйте пакет на реальной задаче и на пограничных случаях, прежде чем отдавать его команде.
- Выберите повторяемую процедуру, которую команда выполняет чаще всего, и запишите её порядок в черновик.
- Оформите черновик как SKILL.md с точным описанием: что делает и в каких случаях подключается.
- Прогоните пакет на трёх свежих задачах разного размера и сравните результат с тем, что получил бы опытный коллега.
- Проверьте границы: задача, которая лишь похожа на процедуру, и задача, где пакет обязан отказаться от действия.
- Попросите коллегу, далёкого от написания пакета, вызвать его по одному описанию.
- Зафиксируйте замечания в самом файле и повторяйте прогон до стабильного результата.
Тестовые задачи берите из реальной истории: закрытые обращения, недавние релизы, старые запросы на слияние. По ним сразу видно, где инструкция обходит острые углы. Результат сравнивайте по списку критериев, записанному до прогона, а ощущениям доверять рано.
Ищите две ошибки. Пакет срабатывает там, где он лишний, и молчит там, где он нужен. Первое лечится сужением описания, второе уточнением ключевых слов и примеров. Хороший признак готовности: два разных человека получают от пакета одинаковый по структуре результат.
Какую процедуру вашей команды стоит оформить первой?
Обновление и поддержка
Документация сообщает, что Codex автоматически замечает изменения в локальных пакетах, поэтому правка файла действует сразу; если после правки изменений нет, перезапустите приложение. Это удобно и одновременно опасно: случайная правка меняет поведение агента у всех, кто работает с этим репозиторием.
Правки командных пакетов проходят тот же путь, что и код: ветка, запрос на слияние, ревью, запись в журнале изменений. Так видно, кто и зачем поменял порядок действий.
Раз в квартал просматривайте набор целиком. Удаляйте пакеты, заброшенные всеми, объединяйте дубли и обновляйте описания, если процесс изменился. Назначьте владельца для каждого пакета: у процедуры без владельца инструкции быстро расходятся с практикой.
Если вам нужен общий набор процедур для команд разработки и аналитики, мы собираем его в рамках консалтинга по внедрению ИИ. Набор расширяйте после того, как первая процедура проверена на задачах. Первая удачная процедура задаёт образец: остальные пакеты команда будет оформлять по тому же шаблону, с тем же уровнем подробности и теми же критериями готовности, а ревьюеру станет проще сверять новые файлы со старыми.