Команда Codex CLI /skills: как использовать навыки агента

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

/skills — это каталог специализированных возможностей Codex, а не универсальная кнопка «сделай всё правильно». Навык помогает организовать работу, но результат по-прежнему зависит от формулировки задачи, состояния проекта и доступных инструментов.

На практике команда особенно полезна в больших проектах, где одни и те же действия повторяются: подготовка релиза, ревью pull request, написание тестов, миграция API или проверка документации. В этой статье разберём, как пользоваться /skills, когда она действительно экономит время, чем навыки отличаются от плагинов, воспоминаний и инструкций репозитория, а также рассмотрим практические сценарии.

Как использовать /skills

Команда открывается непосредственно в интерактивной сессии Codex CLI. Обычно после ввода /skills пользователь получает список доступных навыков, их краткие описания и возможность выбрать нужный пункт. В зависимости от версии CLI, установленной конфигурации и интерфейса список может выглядеть немного по-разному.

Хороший навык отвечает на вопрос «как выполнять определённый класс задач», а не просто хранит отдельную команду или текстовую подсказку.

Типичный сценарий выглядит так: сначала пользователь вызывает список, затем изучает описание нескольких навыков, выбирает подходящий и формулирует конкретную задачу. Если навык рассчитан на работу с определённым каталогом, форматом файла или инструментом, это обычно указано в его описании.

Шаг	Действие пользователя	Зачем это нужно
1	Ввести /skills	Открыть список доступных навыков
2	Изучить названия и описания	Понять, какой навык соответствует задаче
3	Выбрать навык	Передать Codex дополнительный специализированный контекст
4	Сформулировать задачу	Объяснить, какой результат требуется получить
5	Проверить результат	Убедиться, что навык применён уместно и не изменил лишние файлы

Названия навыков могут зависеть от конкретной среды. В одном проекте будут доступны навыки для Python-тестирования и анализа SQL, в другом — сценарии для фронтенда, документации или работы с облачной инфраструктурой. Поэтому не стоит ожидать, что у всех пользователей список /skills будет одинаковым.

Как выбрать подходящий навык

При выборе ориентируйтесь не на красивое название, а на описание входных данных, результата и ограничений. Навык «code review» может быть полезен для поиска дефектов, но не обязательно предназначен для автоматического исправления файлов. Навык «release notes» может подготовить текст изменений, но не создать релиз в системе контроля версий.

Если задача звучит так	Подходящий тип навыка	Что уточнить заранее
«Проверь изменения перед слиянием»	Ревью кода	Нужно ли только найти проблемы или также исправить их
«Добавь тесты для модуля»	Генерация и анализ тестов	Какой фреймворк используется и какой уровень покрытия нужен
«Обнови документацию API»	Документация	Где лежит источник истины: OpenAPI, код или отдельные Markdown-файлы
«Подготовь миграцию базы данных»	Миграции и SQL	Какая СУБД используется и допустимы ли разрушающие изменения
«Подготовь изменения к релизу»	Релизный процесс	Нужен ли changelog, список breaking changes и проверка версий

Если два навыка кажутся одинаково подходящими, выбирайте более узкий. Специализированный сценарий обычно содержит меньше лишних предположений. Например, для проверки React-компонента лучше использовать навык, ориентированный на React и тестовый стек проекта, чем общий навык анализа JavaScript.

/skills

Доступные навыки:
1. code-review — поиск дефектов и рисков в изменениях
2. test-generation — создание тестов
3. api-docs — работа с документацией API
4. release-notes — подготовка описания релиза

Выберите навык или укажите, что нужно сделать.

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

/skills

Выбираю test-generation.
Задача: добавить unit-тесты только для src/cart/price.ts.
Используй существующий Vitest-стиль проекта.
Не меняй production-код и не устанавливай новые зависимости.

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

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

Признак	Что он может означать	Что проверить
Появился структурированный отчёт	Навык задаёт формат анализа	Все ли обязательные разделы заполнены
Используется проектный тестовый фреймворк	Навык учёл контекст репозитория	Проходят ли тесты без новых зависимостей
Изменены только ожидаемые файлы	Задача ограничена корректно	Проверить git diff и git status
Codex задаёт уточняющие вопросы	Для навыка не хватает входных данных	Не отвечать автоматически, если вопрос касается риска или удаления данных

Навык не отменяет обычную проверку. Если он создаёт миграцию, нужно посмотреть SQL. Если пишет тесты — проверить, что тесты действительно проверяют поведение, а не просто повторяют реализацию. Если готовит release notes — сверить список изменений с историей коммитов.

Когда применять /skills

/skills особенно полезна там, где задача повторяется и имеет понятный процесс выполнения. Это может быть не только программирование: навык способен задавать правила анализа документации, проверки конфигураций, подготовки отчётов или обработки типовых запросов команды.

Навык приносит максимальную пользу там, где важен воспроизводимый процесс, а не только разовый ответ.

Например, запрос «посмотри этот код» слишком расплывчатый. Запрос с навыком ревью может подразумевать проверку безопасности, обратной совместимости, производительности и тестового покрытия. В результате Codex смотрит на изменение не как на набор строк, а как на часть инженерного процесса.

Ситуация	Почему подходит навык	Ожидаемый результат
Ежедневное ревью изменений	Нужны одинаковые критерии проверки	Список замечаний с приоритетами и ссылками на строки
Подготовка тестов	Есть повторяемый шаблон и фреймворк	Тесты в стиле существующего проекта
Обновление документации	Нужно соблюдать формат и терминологию	Согласованные страницы или файлы документации
Миграция большого API	Важно пройти несколько этапов и ничего не пропустить	План, изменения, проверки и список рисков

Команда полезна и для обучения. Новичок может выбрать навык, который объясняет процесс пошагово: как найти точку входа в проекте, как проверить регрессию, как написать минимальный тест или как подготовить pull request. В этом случае навык выступает не заменой специалисту, а своеобразной памяткой с практическим маршрутом.

Когда навык лучше не использовать

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

Задача	Почему /skills может быть избыточной	Лучший подход
Объяснить одну строку кода	Нет отдельного повторяемого процесса	Обычный запрос с фрагментом кода
Исправить опечатку	Специализированный анализ не нужен	Точечное изменение с ограничением файла
Уточнить значение команды Git	Задача справочная	Короткий вопрос с указанием контекста
Исследовать незнакомый репозиторий	Сначала неясно, какой процесс нужен	Начать с анализа структуры и инструкций проекта

Не стоит выбирать навык только потому, что он звучит профессионально. Сложное название не превращает неясную задачу в ясную. Перед запуском проверьте три вещи:

• совпадает ли область навыка с вашей задачей;
• есть ли у Codex необходимые файлы, права и инструменты;
• понятно ли, как проверить полученный результат.

Задача: понять, почему команда npm test завершается с ошибкой.

Навык не выбираю: сначала нужен обычный диагностический анализ.
Покажи:
1. первую значимую ошибку;
2. файл и строку, где она возникает;
3. минимальный способ воспроизведения;
4. варианты исправления без изменения файлов.

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

Примеры использования /skills

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

Пример 1. Ревью изменений перед pull request

Навык ревью помогает проверить не только стиль кода, но и поведение, ошибки, безопасность и обратную совместимость. Особенно полезно заранее указать, что на первом этапе нужен отчёт, а не автоматическое редактирование файлов.

/skills

Выбираю code-review.
Проверь текущие изменения в ветке относительно main.

Фокус:
- ошибки обработки пустых значений;
- обратная совместимость API;
- утечки персональных данных в логах;
- отсутствие тестов для новых веток.

Сначала только отчёт. Не изменяй файлы.

Результат ревью должен иметь формат:

Критичность: high / medium / low
Файл и строка: путь:строка
Проблема: что может произойти
Рекомендация: как исправить
Проверка: каким тестом подтвердить исправление

Если проблем нет, явно напиши, какие области были проверены.

Пример 2. Создание тестов для существующего модуля

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

/skills

Выбираю test-generation.
Добавь тесты для src/auth/token.ts.

Условия:
- используй Jest, который уже настроен в проекте;
- проверь срок действия токена, неверную подпись и отсутствие заголовка;
- не меняй src/auth/token.ts;
- не добавляй новые пакеты;
- после создания запусти только соответствующий набор тестов.

Перед написанием тестов:

1. Найди существующие тесты авторизации.
2. Определи, какие функции экспортируются.
3. Проверь формат тестовых фикстур.
4. Не дублируй проверки, которые уже есть.
5. В конце перечисли сценарии, которые остались непокрытыми.

Пример 3. Обновление документации API

Навык документации полезен, когда описание должно совпадать с фактическим поведением кода. Простое поручение «обнови README» может привести к красивому, но устаревшему тексту, поэтому стоит указать источник данных и формат результата.

/skills

Выбираю api-docs.
Обнови документацию для endpoint POST /v1/orders.

Сверь описание с:
- маршрутом в src/routes/orders.ts;
- схемами в src/schemas/order.ts;
- существующим OpenAPI-файлом.

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

Не меняй реализацию endpoint.

Проверь согласованность:

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

После правок выведи таблицу:
поле | тип | обязательность | описание.

Пример 4. Подготовка миграции базы данных

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

/skills

Выбираю database-migration.
Нужно добавить индекс по users.email.

Уточни:
- какая СУБД используется;
- есть ли уже дубликаты email;
- можно ли создавать индекс без длительной блокировки таблицы;
- как откатить изменение.

Сначала подготовь план и SQL-файл.
Не применяй миграцию к базе.

Проверка перед созданием миграции:

1. Найти текущую схему таблицы users.
2. Проверить тип и длину поля email.
3. Определить, есть ли уже похожий индекс.
4. Оценить влияние на большую таблицу.
5. Добавить обратную миграцию, если это поддерживается проектом.

Не выполняй DROP INDEX и не меняй production-базу.

Пример 5. Подготовка release notes

Навык подготовки релизных заметок собирает изменения в понятный для пользователя текст. Он особенно полезен, когда в проекте есть договорённый формат: отдельные разделы для новых возможностей, исправлений, несовместимых изменений и известных ограничений.

/skills

Выбираю release-notes.
Подготовь release notes для версии 3.8.0 по изменениям между тегами v3.7.0 и текущей веткой.

Разделы:
- новые возможности;
- исправления;
- изменения API;
- breaking changes;
- действия для обновления.

Не включай внутренние рефакторинги, которые не влияют на пользователей.
Для каждого пункта укажи ссылку на issue или pull request, если она есть.

Проверь итоговый текст:

Нельзя писать: «улучшена производительность» без указания затронутого сценария.
Нужно писать: какой пользовательский процесс изменился и требуется ли действие при обновлении.

Если breaking changes не найдены, укажи это отдельной строкой.

Чем /skills отличается от других команд

В Codex CLI рядом с /skills могут использоваться команды /plugins, /memories и /init. Их названия связаны с настройкой рабочего пространства, но назначение различается. Точные пункты меню и доступность отдельных возможностей могут зависеть от версии Codex CLI.

Навык описывает способ выполнения задачи, плагин расширяет доступные возможности, воспоминание сохраняет полезный контекст, а инструкция репозитория задаёт правила работы именно с проектом.

Команда или механизм	Главный вопрос	Роль
/skills	«Как выполнить конкретный тип задачи?»	Выбор специализированного рабочего сценария
/plugins	«Какие дополнительные возможности подключены?»	Управление расширениями и интеграциями
/memories	«Что стоит сохранить или использовать из прошлого контекста?»	Работа с долговременными или сессионными воспоминаниями
/init	«Как подготовить проект к работе Codex?»	Создание или настройка проектных инструкций
Инструкции репозитория	«Какие правила действуют в этом коде?»	Контекст проекта, соглашения и ограничения

/plugins: расширения и интеграции

Плагин — это более широкое расширение среды. Он может добавлять интеграцию с внешним сервисом, новый инструмент, особый источник данных или набор функций. Навык, напротив, обычно описывает конкретный способ решить задачу с использованием доступных возможностей.

Критерий	Навык	Плагин
Масштаб	Узкий процесс или класс задач	Расширение возможностей среды
Пример	Проверить миграцию SQL	Подключить внешний сервис или инструмент
Зависимость	Может работать на основе уже доступных инструментов	Может требовать установки, авторизации или настроек
Основной результат	План, анализ, изменения или отчёт	Новый источник данных, команда или интеграция

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

/plugins

Проверяю подключённые расширения.
Нужен инструмент для работы с системой задач.

После подключения плагина выбираю навык:
/skills → issue-triage

Задача:
найти открытые issues с меткой bug, сгруппировать их по компонентам
и предложить приоритеты. Ничего не закрывать и не изменять автоматически.

/memories: сохранённый контекст

Воспоминания предназначены для информации, которую полезно учитывать в будущих сессиях: предпочитаемый формат ответа, устойчивые особенности проекта, часто используемые команды или договорённости команды. Это не пошаговый алгоритм выполнения задачи и не замена файлу с инструкциями.

Вопрос	Если речь о навыке	Если речь о воспоминании
Что хранится?	Метод или сценарий работы	Факт, предпочтение или устойчивый контекст
Как долго полезно?	Пока нужен конкретный процесс	В нескольких будущих сессиях или задачах
Пример	«Проверь API по этому чек-листу»	«В проекте используется pnpm»
Риск	Навык может быть неприменим к другой задаче	Устаревшее воспоминание может ввести в заблуждение

Важные сведения не следует бездумно сохранять в памяти. Секреты, токены, персональные данные и временные решения не подходят для долговременного контекста. Если правило критично для каждого участника проекта, его лучше оформить в репозитории, а не полагаться только на память отдельного рабочего окружения.

/memories

Покажи сохранённые сведения, связанные с этим проектом.
Проверь, нет ли устаревшего правила о пакетном менеджере.

Если найдено:
«Использовать npm»,
а в репозитории есть pnpm-lock.yaml,
предложи обновить или удалить это воспоминание.
Не сохраняй секреты и значения переменных окружения.

/init: инструкции репозитория

Команда /init обычно используется для первичной настройки проекта под работу Codex: анализа структуры и создания или подготовки файла с инструкциями. Такие инструкции могут описывать команды сборки, правила тестирования, архитектурные ограничения, формат коммитов и каталоги, которые нельзя менять.

Источник правил	Область действия	Пример содержания
Навык	Конкретный рабочий процесс	Как выполнять ревью или готовить миграцию
Плагин	Доступные инструменты и интеграции	Работа с внешним трекером задач
Воспоминание	Сохранённый контекст	Предпочтительный формат краткого отчёта
Инструкция репозитория	Правила конкретного проекта	Запуск тестов через pnpm test

Инструкции репозитория имеют особое значение: навык должен учитывать их, а не заменять. Если выбранный навык предлагает запускать npm test, но проект прямо требует pnpm test -- --runInBand, приоритет должны иметь фактические правила репозитория и явно заданные ограничения.

/init

Проанализируй репозиторий и подготовь проектные инструкции.

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

Не добавляй в инструкции пароли, токены и содержимое .env.

Как использовать механизмы вместе

В реальной работе эти возможности не конкурируют, а дополняют друг друга. Сначала /init помогает понять правила проекта, затем /plugins при необходимости добавляет внешний инструмент, /memories сохраняет устойчивые предпочтения, а /skills запускает нужный процесс.

Этап	Механизм	Пример результата
Подготовить проект	/init	Инструкции о командах и структуре репозитория
Подключить внешний источник	/plugins	Доступ к трекеру задач или другому сервису
Учесть постоянное предпочтение	/memories	Согласованный формат отчётов
Выполнить конкретную процедуру	/skills	Ревью, тестирование, миграция или документация
Проверить результат	Инструкции и ручной контроль	Тесты, diff, логи и подтверждение рисковых действий

/init
Сначала изучи инструкции репозитория и команды проверки.

/plugins
Проверь, доступен ли подключённый трекер задач.

/memories
Учти сохранённое предпочтение: отчёт должен быть кратким,
но с отдельным разделом «Риски».

/skills
Выбери release-readiness.
Проверь готовность версии к выпуску, но не создавай релиз
и не закрывай задачи без моего подтверждения.

Практические рекомендации и типичные ошибки

Даже правильно выбранный навык не гарантирует качественный результат, если задача поставлена слишком широко. Codex должен понимать границы работы, критерии успеха и допустимый уровень самостоятельности. Это особенно важно, когда навык способен изменять несколько файлов или запускать команды с побочными эффектами.

Лучше один раз явно описать границы полномочий, чем потом восстанавливать файлы после слишком инициативного автоматического исправления.

Перед запуском полезно указать:

• область файлов или каталогов;
• цель и ожидаемый формат результата;
• команды, которые разрешено выполнять;
• действия, требующие отдельного подтверждения;
• способ проверки результата;
• условия остановки, если обнаружены рискованные изменения.

Ошибка	Последствие	Как исправить формулировку
«Сделай всё необходимое»	Неясные границы и лишние изменения	Перечислить файлы, этапы и запреты
Выбран слишком общий навык	Много нерелевантного анализа	Использовать более узкий сценарий
Нет критерия успеха	Непонятно, когда задача завершена	Указать тест, команду или ожидаемый формат отчёта
Автоматически доверен отчёт	Можно пропустить ошибочный вывод	Проверить diff, тесты и исходные данные
В память записан временный факт	Будущие ответы опираются на устаревший контекст	Сохранять только устойчивые и безопасные сведения

Плохая формулировка:
«Используй навык и исправь проект».

Улучшенная формулировка:
«Выбери навык для анализа TypeScript.
Проверь только src/payments/.
Сначала подготовь отчёт.
Изменения разрешены только после моего подтверждения.
Не трогай конфигурацию CI и зависимости.
Критерий успеха: pnpm typecheck и pnpm test проходят».

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

Не делай:
«Выбери database-migration и примени изменения в production».

Делай:
«Подготовь миграцию, проверь её на тестовой схеме,
покажи план выполнения и потенциальные блокировки.
Применение к production запрещено без отдельного подтверждения».

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

Что проверять	Когда обновлять	Признак устаревания
Команды сборки и тестов	После смены инструментов	Навык запускает несуществующую команду
Пути к файлам	После реорганизации каталогов	Codex ищет конфигурацию в старом месте
Правила API	После изменения контракта	Документация расходится со схемами
Ограничения безопасности	После изменения инфраструктуры	Сценарий предлагает чрезмерные права
Формат отчёта	При изменении командного процесса	Результаты невозможно использовать в review или issue

В итоге /skills стоит воспринимать как удобный слой специализации поверх обычного диалога с Codex. Команда помогает быстро найти подходящий рабочий процесс, но не заменяет ясную постановку задачи, инструкции репозитория и проверку результата. Наилучшая связка выглядит так: проектные правила задают рамки, плагины предоставляют инструменты, воспоминания сохраняют безопасный устойчивый контекст, а навык помогает выполнить конкретную работу последовательно и воспроизводимо.