Skills в Codex: что это и как написать свой сценарий для агента

Если вы раз за разом даёте Codex один и тот же порядок действий («найди упавший тест, воспроизведи, исправь причину, прогони всё снова»), этот порядок стоит оформить как skill. Skills в Codex это папки с инструкциями, которые агент подгружает, когда задача подходит под описание, или когда вы сами назвали навык. Ниже: что это такое, как написать свой сценарий и как он связан с плагинами и хуками.

Структура и пути взяты из документации OpenAI для Codex на 18 октября 2026. Формат развивается, поэтому детали сверяйте с текущей документацией.

Что такое skill

Skill это каталог, в котором обязательно лежит файл SKILL.md, а рядом могут быть скрипты, справочные материалы и шаблоны. Формат опирается на открытый стандарт agent skills.

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

В SKILL.md обязательны поля name и description в заголовке, дальше идёт текст инструкций.

Главная особенность: постепенная загрузка. Сначала Codex видит только имя и описание каждого навыка (и путь к файлу). Полный текст SKILL.md подтягивается, когда Codex решает применить навык. По документации, начальный список навыков занимает не более 2% окна контекста модели (или 8 000 символов, если окно неизвестно); при большом числе навыков описания сокращаются, а часть навыков может не попасть в список, о чём Codex предупредит. Бюджет меняется настройкой skills.max_context_tokens (до 10 000 токенов).

Как Codex выбирает навык

Есть два способа:

1. Явный вызов. В CLI и в расширении для IDE наберите /skills или начните сообщение с $ и имени навыка.
2. Неявный вызов. Codex сам применяет навык, если задача совпадает с description. Поэтому описание нужно писать очень чётко.

Отсюда практичное правило: вынесите в начало описания главный случай использования и слова-триггеры, чтобы навык нашёлся, даже если описание сократят. Укажите и границы: когда навык применять не надо.

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

Для репозитория Codex сканирует каталоги .agents/skills от текущей папки вверх до корня репозитория. Остальные места:

Если два навыка совпали по name, Codex их не объединяет, оба могут появиться в списке. Новые и изменённые навыки подхватываются автоматически, а если изменение не видно, перезапустите Codex.

Пример: навык для разбора упавших тестов

Создадим навык в репозитории: .agents/skills/fix-failing-tests/SKILL.md.

---
name: fix-failing-tests
description: Разобрать и исправить упавшие тесты pytest. Используй, когда пользователь просит починить тесты, разобрать красный CI или найти причину падения. Не используй для написания новых тестов.
---

## Починка упавших тестов

1. Запусти `scripts/run_tests.sh` и прочитай вывод. Не запускай весь набор повторно без нужды.
2. Выбери одно падение. Воспроизведи его отдельной командой `pytest <путь>::<имя> -x -q`.
3. Найди причину в коде, а не в тесте. Меняй тест только если он явно устарел, и объясни почему.
4. Внеси минимальную правку.
5. Запусти упавший тест, затем весь набор через `scripts/run_tests.sh`.
6. В конце кратко сообщи: что падало, в чём причина, что изменено, какие проверки зелёные.

Запреты: не отключай и не помечай тесты как skip ради зелёного результата; не трогай каталог migrations/.

И простой скрипт .agents/skills/fix-failing-tests/scripts/run_tests.sh:

#!/usr/bin/env bash
set -euo pipefail
pytest -q --maxfail=5 2>&1 | tail -n 60

Скрипт обрезает вывод до последних строк, чтобы не тащить в контекст километры логов: это и экономит токены, и помогает модели увидеть главное. Команды pytest приведены как пример, подставьте свои.

Вызвать навык можно так:

$fix-failing-tests разбери падения в tests/api

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

Помощники для создания навыков

• $skill-creator задаёт вопросы о том, что делает навык, когда он должен срабатывать и нужны ли скрипты, и создаёт заготовку. По умолчанию создаётся навык только с инструкциями.
• $skill-installer устанавливает готовые навыки, например $skill-installer linear. Тут обратите внимание: ставьте только то, чему доверяете, ведь навык может включать скрипты.

Чтобы отключить навык, не удаляя, добавьте в ~/.codex/config.toml:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

А если навык не должен срабатывать сам, в agents/openai.yaml в блоке policy задаётся allow_implicit_invocation: false, тогда он запускается только явным $навык.

Skills, plugins и hooks: чем отличаются

В запросах рядом со skills часто встречаются codex plugins и codex hooks. Это три разных механизма.

• Skills это инструкции (и необязательные скрипты) для решения задачи; модель сама решает, когда их применять, или вы вызываете по имени.
• Plugins упаковывают навыки (одну или несколько штук) и, по документации, могут включать подключения к MCP-серверам, чтобы раздавать их другим людям. Для одного репозитория достаточно каталога .agents/skills; плагины нужны, когда навык надо распространять.
• Hooks это скрипты, которые запускаются в определённых точках цикла агента (например, перед вызовом инструмента или при остановке хода) и могут, скажем, проверять промпты или логировать чат. Хуки выполняются независимо от решения модели. Неуправляемые хуки перед запуском нужно просмотреть и подтвердить.

Если нужно «модель должна делать так-то», берите skill. Если нужно «система обязательно проверит это», смотрите в сторону hooks. Об аналогичном файле инструкций для проекта читайте в статье AGENTS.md для Codex CLI↗.

Сколько стоит запуск навыка

Навык это обычная работа агента, оплачиваются токены модели. Допустим (условный пример), сценарий занимает 15 запросов, в среднем по 25 000 входных токенов и по 600 выходных. Вход 15 × 25 000 = 375 000, выход 15 × 600 = 9 000 токенов. На gpt-6.1-sol (вход $0.27, выход $1.32 за 1M, цены на 18 октября 2026), без учёта кэша: 0,375 × 0,27 + 0,009 × 1,32 = 0,10125 + 0,01188 = $0.1131.

У GPT-моделей шлюз видит чтение кэша; кэшированная часть входа оплачивается по цене чтения $0.013 за 1M, что снижает сумму на длинных сессиях. Запись в кэш у GPT отдельно не списывается. Короткий SKILL.md и обрезанный вывод скриптов экономят токены на каждом запросе. Сами навыки клиентская функция Codex и от провайдера не зависят.

Как подключить Codex к Zukko

Минимальный ~/.codex/config.toml:

model = "gpt-6.1-sol"
model_provider = "zukko"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
env_key = "ZUKKO_API_KEY"
wire_api = "responses"

Ключ fetch_... создаётся в кабинете↗ и кладётся в переменную ZUKKO_API_KEY. Подробности и второй способ через auth.json есть в документации по Codex↗. По данным документации Zukko, в Codex работают модели GPT и Claude, GLM не работают.

Частые вопросы

Навык не срабатывает сам, что делать?

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

Сколько навыков можно установить?

Ограничение связано с бюджетом списка навыков в контексте: при большом числе Codex сокращает описания и может часть навыков не показать. Держите навыки узкими и отключайте ненужные.

Можно ли поделиться навыком с командой?

Да, положите его в .agents/skills репозитория и закоммитьте. Для распространения вне одного репозитория упаковывайте навыки в плагины.

Навыки работают с моделями Zukko?

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

Создайте ключ в кабинете Zukko, подключите Codex и напишите первый навык из пяти шагов.