Codex Skills: создание, запуск и проверка на задаче code review

Механизм Skills в Codex

Механизм навыков (skills), описанный в официальной документации, подключает к агенту инструкции и шаблоны под специализированные задачи без перегрузки системного контекста.

Навык представляет собой каталог с обязательным файлом SKILL.md. В его YAML frontmatter обязательны поля name и description, а тело содержит правила для модели:

.agents/skills/boundary-review/
└── SKILL.md

Codex использует progressive disclosure: на старте формируется компактный индекс доступных навыков. Полный текст SKILL.md считывается агентом только в момент принятия решения о применении конкретного навыка.

Поиск навыков выполняется по четырем уровням:

1. Репозиторий (REPO): .agents/skills в текущей директории и выше до корня Git.
2. Пользователь (USER): $HOME/.agents/skills.
3. Администратор (ADMIN): /etc/codex/skills.
4. Система (SYSTEM): системные каталоги окружения (bundled).

Вызов выполняется явно (через префикс $имя) либо неявно (по семантическому совпадению запроса с description). Доступность и конфликты регулируются в файле config.toml.

Предварительные требования и изоляция

Для воспроизведения сценария требуются:

• Python 3;
• Установленный и авторизованный интерфейс командной строки Codex CLI.

Тестовые данные зафиксированы 2026-09-16 на версии Codex CLI 0.153.3.

Все команды выполняются в подготовленном локальном каталоге вне репозитория Git. Поскольку текстовые инструкции в SKILL.md организуют поведение модели, но не гарантируют изоляцию операционной системы, запуск выполняется с флагами:

• --ephemeral: предотвращает сохранение состояния сессии;
• --skip-git-repo-check: разрешает запуск в изолированной папке без Git;
• --sandbox read-only: ограничивает доступ процесса на запись на уровне среды исполнения.

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

Создание навыка boundary-review

Создайте директорию навыка в текущем каталоге:

mkdir -p .agents/skills/boundary-review

Сохраните в .agents/skills/boundary-review/SKILL.md следующее содержимое:

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

Текстовое предписание запрещает модели изменять файлы и требует начинать ответ с сигнального маркера BOUNDARY_REVIEW с обязательным указанием одного сбойного входного значения.

Тестовый файл с дефектом

Создайте файл pages.py с типовой ошибкой смещения при вычислении количества страниц:

def page_count(total, size):
    return total // size + 1

Для условий size > 0 и total >= 0 функция дает сбой на граничном значении: при total = 1 и size = 1 возвращается 2 вместо 1. Кроме того, для пустого списка total = 0 функция вернет 1.

Запуск и верификация вызовов

Запросы передаются в одинарных кавычках, чтобы командный процессор не интерпретировал символ $ как переменную окружения.

1. Явный вызов по имени

Запустите явную проверку с прямым указанием навыка:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

Модель возвращает результат:

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

Наличие маркера BOUNDARY_REVIEW само по себе не является доказательством загрузки SKILL.md, так как текст маркера может быть сгенерирован по контексту запроса. В фактическом запуске от 2026-09-16 системный журнал зафиксировал вызов команды чтения файла .agents/skills/boundary-review/SKILL.md. Именно связка события чтения файла в журнале, префикса BOUNDARY_REVIEW и контрпримера page_count(1, 1) подтверждает исполнение целевой инструкции.

2. Неявный вызов по описанию

Сформулируйте задачу на естественном языке без упоминания идентификатора $boundary-review:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

В журнале этого запуска также зарегистрировано чтение .agents/skills/boundary-review/SKILL.md благодаря совпадению фразы из запроса с полем description. Агент сформировал аналогичный структурированный ответ с маркером BOUNDARY_REVIEW и разбором сбоя на входе (1, 1).

Проверка логики и шаги для читателя

Проверим исходное поведение функции локальным интерпретатором Python:

python3 -c "from pages import page_count; print(page_count(1, 1))"

Команда выводит 2, подтверждая наличие дефекта.

В рамках контрольного прогона от 2026-09-16 исходный файл pages.py оставался без изменений; повторный запуск CLI по модифицированному файлу не выполнялся. Математическая корректность предложенной формулы (total + size - 1) // size при total >= 0 и size > 0 проверена на граничных наборах:

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2.

Для самостоятельного исправления читатель может привести pages.py к виду:

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

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

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

Ожидаемый результат выполнения команды после ручного редактирования файла: OK.

Диагностика неполадок

Если навык не обнаруживается или не вызывается автоматически:

1. Путь к файлу: убедитесь, что путь относительно рабочей директории в точности равен .agents/skills/<skill-name>/SKILL.md.
2. Обновление реестра: если файлы добавлены во время открытой сессии, перезапустите процесс CLI для перечитывания каталогов.
3. Блокировка в конфигурации: проверьте ~/.codex/config.toml. Если навык отключался, запись вида:

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   блокирует его загрузку. Удалите блок или задайте enabled = true.
4. Конфликты имен: при наличии одинаковых name на уровнях репозитория и пользователя приоритет может приводить к неоднозначности.
5. Точность description: для неявного вызова ключевые триггеры («pagination boundaries», «boundary errors») должны находиться в начале описания.
6. Сторонние навыки: при необходимости загрузки внешних пакетов точкой входа служит служебный инструмент $skill-installer. Любые сторонние навыки требуют обязательного ручного аудита файлов SKILL.md и директории scripts/ перед запуском. В рамках описанного сценария сторонние компоненты не устанавливались.