10 октября 2026 г.

Скиллы для Codex: как подключить и применять в проектах

Андрей Присекин
Автор

Андрей Присекин

Создаю AI-агентов, автоматизирую бизнес-процессы

Скиллы для Codex - это папки с инструкцией SKILL.md, которые помогают агенту повторять рабочий процесс: проверять патч, готовить релиз или запускать тесты по правилам проекта. Положи папку в .agents/skills/ внутри репозитория или в ~/.agents/skills/ для личного использования. Затем вызови навык через $имя-скилла и проверь результат на маленькой задаче.

У меня больше всего времени уходит не на объяснение задачи агенту, а на повторение одних и тех же оговорок: какие тесты запускать, какие файлы не трогать, что показать перед коммитом. Скилл удобно использовать именно для такого повторяемого договора. Ниже - пример с настоящим файлом, местами установки и проверкой, что Codex увидел инструкцию.

Скиллы для Codex: что они делают и чего не делают

Документация OpenAI по skills описывает навык как каталог с обязательным SKILL.md и необязательными скриптами, справочниками и шаблонами. В шапке файла нужны name и description. Сначала Codex видит имя и описание, а полный текст читает, когда решает применить навык. Поэтому описание должно говорить о конкретной задаче: «проверь изменения и запусти связанные тесты», а не «помогай программировать».

Это не новая модель и не волшебное разрешение на доступ к твоему компьютеру. Инструкция влияет на план работы агента в рамках уже выданных ему прав. Если навык предлагает исполнить скрипт, тот нужно проверить как обычный чужой код. Codex может выбрать скилл сам по описанию, но надёжнее первый запуск сделать явно: указать $имя-скилла в запросе. В CLI и расширении IDE список доступных навыков можно открыть через /skills.

AGENTS.md решает соседнюю задачу: он хранит общие правила проекта, которые агент читает независимо от конкретного сценария. «Перед правкой проверь тесты» - кандидат для AGENTS.md; «после правки формы оплаты собери чек-лист релиза» - кандидат для отдельного скилла. Не размножай одни и те же ограничения в обоих местах: потом придётся выяснять, какая версия актуальная.

Куда положить SKILL.md: проект и личные навыки

Для команды я бы начал с .agents/skills/имя-скилла/SKILL.md в корне репозитория. Тогда файлы навыка видны в Git, попадают в ревью и доступны коллегам, которые запускают Codex в этом проекте. Для собственных процедур есть $HOME/.agents/skills/имя-скилла/SKILL.md; они не требуют изменения чужого репозитория. OpenAI перечисляет также уровни администратора и системные навыки, но для обычного старта хватит этих двух.

Если запустить Codex из вложенной папки репозитория, он ищет .agents/skills по цепочке вверх до корня. Это полезно для монорепо: можно держать общий навык в корне и узкий - рядом с конкретным приложением. Одноимённые навыки не сливаются в единый файл. Поэтому дай им разные имена, иначе в списке будет сложно понять, какую процедуру агент взял.

Схема папки выглядит так:

project/
  AGENTS.md
  .agents/
    skills/
      review-change/
        SKILL.md
        references/
          checklist.md

references/ здесь необязательна: это место для длинных критериев проверки, которые не нужны в каждом разговоре. Скрипты тоже можно положить рядом, но сначала попробуй текстовую инструкцию. Чем меньше сторонних исполняемых файлов, тем проще проверить, что навык делает на самом деле. Если навыки не появились после правки, OpenAI советует перезапустить Codex.

Структура проектного скилла: папка навыка, файл SKILL.md и необязательный справочник

Как создать и подключить свой скилл

Покажу текстовый навык для проверки небольшого изменения. Предполагается, что Codex уже установлен и ты открыл существующий Git-проект. Если сам агент пока не запущен, начни с инструкции по установке Codex. Команды ниже создают папку в текущем проекте; перед вводом проверь pwd и git status --short, чтобы не добавить её в чужое рабочее дерево.

  1. Создай директорию: mkdir -p .agents/skills/review-change. Эта команда создаст папку навыка, но не тронет существующие исходники.
  2. Создай внутри SKILL.md с YAML-шапкой и простыми действиями. Важно именно имя файла с заглавными буквами, чтобы коллеги не гадали, какой манифест искать.
  3. Открой файл и проверь смысл инструкции: агент должен перечислить изменённые файлы, запустить подходящие тесты и отдельно указать то, чего не проверил. Не давай ему права самому отправлять изменения в продакшен.
  4. Перезапусти Codex, если открытая сессия не обнаружила новый навык. В интерфейсе CLI открой /skills или явно упомяни $review-change в следующем запросе.

Минимальное содержимое SKILL.md:

---
name: review-change
description: Проверяй небольшие правки кода перед ревью; применяй, когда пользователь просит оценить конкретный diff и запустить связанные тесты.
---

1. Покажи список изменённых файлов и объясни назначение правки.
2. Запусти связанные тесты, предварительно проверив команды проекта.
3. Назови непротестированные сценарии и причины пропуска.
4. Не делай commit или push без явного запроса пользователя.

Поле description отвечает и за автоматический подбор. Если описание слишком широкое, Codex может доставать навык на любой вопрос о коде. Если слишком узкое - не найдёт его, когда попросишь «проверь мой патч». Я бы сначала оставил явное имя в запросе, а автоподбор проверял уже после нескольких ручных прогонов. Официальный пример OpenAI использует ту же пару полей name и description.

Как применить навык в реальной задаче

Допустим, ты поправил форму регистрации и хочешь пройти ревью до коммита. Вводишь: «$review-change Проверь текущий diff формы регистрации. Укажи, какие тесты запустил, и ничего не коммить». После ответа сравни перечисленные файлы с git status --short. Если агент пропустил важный модуль, это не повод автоматически расширять ему права: сначала выясни, была ли задача сформулирована точно и видел ли он нужную ветку.

Проверка изменения: запрос к навыку, просмотр diff, запуск тестов и ручное решение

Есть и второй способ: написать «Проверь изменение перед ревью», не называя навык. Codex может подобрать подходящий скилл по description. Для проверки механики я бы попросил его сообщить, какую процедуру он применил, и сопоставил ответ с фактическим списком тестов. Само упоминание названия не доказывает, что тесты прошли: в отчёте нужны команда, результат и ограничения проверки.

Отдельно проверь разницу между задачей и правилом проекта. Если навык велит «всегда запускай полный набор тестов», а маленькая правка затрагивает лишь текст, цена проверки может стать несоразмерной. Лучше записать: «подбери связанные тесты; если не можешь установить их по конфигу проекта, объясни это и предложи полный прогон». Тогда процедура остаётся полезной и для скрипта, и для документации.

Когда нужны scripts и references, а когда достаточно текста

У текстовой инструкции есть граница: она может попросить Codex запускать одни и те же команды, но не гарантирует одинаковую обработку вывода каждый раз. Если нужен детерминированный отчёт, добавь скрипт в scripts/ и явно укажи вход, выход и способ проверить ошибку. В references/ держи длинные правила команды, а в assets/ - шаблон результата. Такой состав допускает официальный формат навыков; все три дополнительные папки необязательны.

Я бы не ставил пакет из интернета ради первой версии скилла. Файл на десяток строк уже позволяет убрать повторяющиеся указания из промпта. Если позже понадобится точная автоматическая проверка, добавляй один скрипт под конкретный сбой: например, верификацию обязательных полей отчёта. Проверить его можно отдельно от агента, обычной командой в терминале. Иначе при поломке ты не поймёшь, ошибся Codex или твоя автоматизация.

Навык, скачанный из чужого репозитория, может предлагать читать файлы или отправлять данные в сеть. Прежде чем включить его на рабочем проекте, открой SKILL.md, скрипты и их зависимости. Пользователю Codex доступен установщик готовых навыков $skill-installer, но удобство установки не заменяет чтение кода. Секреты и файлы клиентов особенно не подходят для первого эксперимента.

Типичные ошибки и короткая проверка перед командным использованием

Первая ошибка - путать скилл Codex с облачным навыком Responses API. Обе формы используют SKILL.md, но публикация пакета через API с версиями - другой способ доставки, со своими правами и оплатой. Для проектного Codex достаточно локального каталога .agents/skills/; не нужно загружать его в API ради теста на своём компьютере. Это разделение есть в документации по skills API.

Вторая ошибка - дать описанию невыполнимое обещание. «Проверь безопасность всего проекта» не объясняет ни границы, ни критерии готовности. Укажи входной артефакт, например diff текущей ветки; проверку, например запуск тестов из конфигурации проекта; и выход, например список рисков со ссылками на файлы. Если агент не смог запустить тесты из-за окружения, пусть пишет «не запущены», а не выдаёт анализ кода за результат тестирования.

Третья - встраивать в общий скилл персональные пути, секреты или команды git push. Тогда одно повторно используемое правило неожиданно становится инструкцией для всех участников команды. После создания проверь git diff -- .agents/skills/, проведи ревью текста как обычного кода и только потом добавляй папку в коммит. В большом проекте запиши владельца процедуры: кто исправит её, если команда сборки изменится.

Я бы считал скилл готовым к повторному применению, когда выполнил три проверки: он виден через /skills, явный вызов $review-change даёт ожидаемые действия на небольшом diff, а отчёт не скрывает ошибки запуска тестов. Для автоподбора проведи отдельный тест без имени навыка. Если процедура не вызвалась, улучши description, а не дописывай сто строк в тело инструкции. У навыка должна быть одна понятная работа.

← Все статьи