Skip to main content
Все гайды
Содержание гайда

Содержание гайда

Время на изучение: 14 мин
#ai_agents#codex#skills#workflows#automation#openai
Средний14 мин

Codex Skills для начинающих: автоматизация рабочих сценариев ИИ-агента

Практическое руководство по созданию и использованию Skills в Codex: анатомия SKILL.md, явная и авто-активация, разница между навыками, скриптами и тулами, Skills API и настройка безопасности.

Опубликовано:

1. Что такое Codex Skill: переход от разовых промптов к повторяемым сценариям

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

Codex Skill (навык) — это сохраненный, повторно используемый рабочий сценарий для определенного типа задач. Создание навыка не является дообучением (fine-tuning) модели: веса нейросети остаются неизменными. Вместо этого агент получает четкий регламент действий, который динамически подгружается в контекстное окно именно тогда, когда возникает соответствующая задача.

mermaid
flowchart LR subgraph AdHoc ["Традиционный подход (Ручной ввод)"] User1["Пользователь"] -->|Каждый раз вводит длинные правила| Prompt["Длинный разовый промпт"] Prompt --> Agent1["Codex"] end subgraph Modular ["Подход на основе Skills"] User2["Пользователь"] -->|Краткий запрос: $code-review| Agent2["Codex"] SkillsDir["Репозиторий Skills (SKILL.md)"] -->|Автоматическая загрузка правил| Agent2 Agent2 --> Output["Стандартизированный результат"] end
Примечание

В официальной экосистеме OpenAI навыки уже стали стандартом автоматизации. Например, для перевода кодовой базы на актуальные модели OpenAI предоставляет готовый Skill openai-docs, знающий все нюансы свежего SDK без необходимости вручную прикреплять документацию.

2. Критерии выбора: когда нужен Skill, а когда достаточно обычного промпта

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

Критерий оценкиОбычный разовый промптCodex Skill
Частота использованияРазовая уникальная задачаРегулярный сценарий (ежедневно или перед релизом)
Сложность процесса1–2 простых действияМногошаговый регламентированный пайплайн с проверками
Дополнительные ресурсыНе требуютсяТребует вспомогательных скриптов, справочников или чеклистов
Требования к результатуПроизвольный текстФиксированная структура отчета (таблица, JSON)
Границы безопасностиСтандартные настройки сессииЧетко зафиксированные права на чтение и запись

Типичные кандидаты для оформления в виде Skill

  • Предрелизный аудит репозитория: Запуск линтеров, поиск забытых отладочных инструкций (console.log, TODO), валидация типов.
  • Стандартизированное код-ревью: Проверка изменений на соответствие внутренним соглашениям команды без внесения несанкционированных правок.
  • Генерация релизных заметок: Сбор списка объединенных PR, их структурирование по категориям и обновление CHANGELOG.md.
  • Миграция компонентов: Пошаговый рефакторинг устаревших конструкций по утвержденному шаблону.
Совет

Инженерное правило трех раз: Если вы ловите себя на том, что уже в третий раз объясняете Codex один и тот же порядок действий («сначала прочитай этот файл, запусти тесты, ничего сам не меняй, оформи ответ в виде таблицы») — этот процесс пора упаковать в отдельный Skill.

3. Механика активации: явный вызов через $name против автоматического подбора

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

Явный вызов (Explicit Invocation)

Пользователь напрямую указывает имя нужного навыка через знак доллара $:

bash
$code-review проверь последние изменения в ветке feature/auth

Этот способ дает 100% предсказуемость: Codex мгновенно активирует указанный Skill, делает его инструкции базовым регламентом и применяет их к переданным аргументам.

Автоматическая активация (Semantic Auto-Match)

Если префикс $name не указан, Codex анализирует текст запроса и сопоставляет его с полем description всех доступных навыков:

mermaid
flowchart TD Req["Запрос: 'Подготовь релизные заметки для v2.1.0'"] --> Router{"Семантический анализ запроса"} Router -->|Match: description release-notes| LoadSkill["Загрузка .codex/skills/release-notes/SKILL.md"] Router -->|No Match| Standard["Обычный диалог без накладных расходов"] LoadSkill --> Exec["Выполнение регламентированного сценария"]
text
Удачное описание (высокая точность активации): description: Проверяет измененные файлы проекта на регрессии, ошибки типов и стиль перед релизом. Используйте при аудите PR. Неудачное описание (размытые границы): description: Помогает разработчику писать хороший код.

4. Анатомия навыка и структура SKILL.md: метаданные, правила и ресурсы

Минимальный Skill состоит всего из одного файла — SKILL.md. Более зрелые навыки могут содержать вложенные скрипты автоматизации, справочные руководства и шаблоны.

text
project-review/ ├── SKILL.md # Основной файл (метаданные + инструкции) ├── scripts/ └── check-deps.sh # Скрипт для быстрых автоматических проверок ├── references/ └── styleguide.md # Справочник: внутренний код-стайл команды └── templates/ └── report-template.md # Шаблон итогового отчета

Структура файла SKILL.md

Файл состоит из двух частей: блока метаданных YAML Frontmatter в начале и пошаговых инструкций в формате Markdown.

markdown
--- name: project-review description: Проводит комплексный аудит кода перед релизом, проверяет типы и формирует отчет об ошибках без внесения изменений. --- Инструкции по аудиту: 1. Запустить "npm run typecheck" для поиска ошибок компиляции TypeScript. 2. Изучить git diff относительно основной ветки main. 3. Разбить найденные замечания на категории: Critical, Warning, Suggestion. 4. Категорически запрещено изменять исходные файлы проекта. 5. Предоставить сводный отчет по шаблону templates/report-template.md.
Важно

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

5. Области хранения: проектные навыки против персональных глобальных

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

mermaid
flowchart TD subgraph GlobalScope ["Глобальные навыки (~/.codex/skills/)"] G1["Персональный стиль коммитов"] G2["Генератор лицензионных заголовков"] end subgraph ProjectScope ["Проектные навыки (.codex/skills/)"] P1["Архитектурный линтер репозитория"] P2["Генератор миграций БД и DTO"] P3["Чек-лист перед выкаткой в прод"] end Dev["Разработчик"] -->|Личные привычки| GlobalScope Team["Команда через Git"] -->|Общие стандарты| ProjectScope

Проектные навыки (.codex/skills/ или .agents/skills/)

Хранятся в корне репозитория и фиксируются в Git.

  • Назначение: Стандартизация процессов для всей команды разработчиков.
  • Преимущество: Любой инженер или CI/CD раннер, клонирующий репозиторий, сразу получает единый набор инструментов.

Персональные навыки (~/.codex/skills/)

Располагаются в домашней папке пользователя операционной системы.

  • Назначение: Личные рабочие сценарии конкретного разработчика.
  • Преимущество: Доступны во всех проектах и терминалах на данной машине.

6. Практический воркшоп: создание навыка проверки кода с помощью $skill-creator

Самый быстрый способ создать новый навык — использовать встроенный в Codex инструмент $skill-creator.

Шаг 1. Запуск мастера создания

В терминальной сессии Codex вызовите команду:

bash
$skill-creator

Опишите желаемый сценарий простыми словами:

text
Создай проектный навык с именем "pr-validator". Задача: проверка измененных файлов в текущем pull request. Правила: 1. Запустить npm run lint и npm test. 2. Проверить наличие тестов для новых утилит. 3. Запретить агенту самостоятельно исправлять найденные дефекты. 4. Вывести результат в виде таблицы: Файл, Строка, Проблема, Уровень риска.

Шаг 2. Проверка сгенерированного файла

Мастер создаст директорию .codex/skills/pr-validator/ и запишет файл SKILL.md:

markdown
--- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity |

Шаг 3. Тестирование навыка в новой сессии

Откройте новую сессию Codex и протестируйте работу созданного навыка:

bash
$pr-validator проверь текущую ветку перед открытием PR

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

7. Триада возможностей агента: навык (Skill), скрипт (Script) и инструмент (Tool)

Разработчики иногда путают понятия навыка, скрипта и инструмента (Tool / MCP). Они решают разные технические задачи и взаимно дополняют друг друга.

mermaid
flowchart TD subgraph Triad ["Триада возможностей автономного агента"] Skill["SKILL (Навык)<br><i>'Мышление и регламент'</i><br>Определяет алгоритм, контекст и правила"] Script["SCRIPT (Скрипт)<br><i>'Детерминированное вычисление'</i><br>Быстро и надежно выполняет действия на диске"] Tool["TOOL (Инструмент / MCP)<br><i>'Органы чувств и руки'</i><br>Предоставляет доступ к API, терминалу, базам данных"] end Skill -->|Управляет логикой| Script Skill -->|Использует| Tool Script -->|Выполняется через| Tool

Сравнительная таблица триады

КомпонентРоль в системеСпособ выполненияПример
Skill (Навык)Регламент и принятие решенийИнтерпретируется языковой модельюИнструкция по аудиту безопасности
Script (Скрипт)Вычислительное действиеЗапускается в оболочке ОСBash-скрипт парсинга тегов версий
Tool (Инструмент)Интерфейс доступа к окружениюВызывается через Tool CallingMCP-сервер для работы с GitHub API
Примечание

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

8. Программное управление через Skills API и версионирование

OpenAI предоставляет Skills API для программного управления наборами навыков в серверных приложениях и облачных пайплайнах.

bash
# Создание нового навыка через HTTP API curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Автоматическая валидация и создание безопасных миграций базы данных", "instructions": "Проверь схему Prisma, убедись в отсутствии деструктивных drop column..." }'

Зачем нужно версионирование Skills

  1. Неизменность продакшна (Immutability): При обновлении создается новая версия (v1, v2). Автоматизированные CI/CD процессы жестко фиксируют номер версии, защищая пайплайн от неожиданных изменений.
  2. Мгновенный откат (Rollback): Если новая формулировка привела к ошибкам, можно в одну секунду переключиться на стабильную предыдущую версию.
  3. A/B тестирование промптов: Возможность запускать параллельные тесты двух вариантов инструкций для оценки точности и скорости выполнения.

9. Безопасность, границы автономии и правила подтверждения действий

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

mermaid
flowchart LR Action["Действие агента"] --> Decision{"Категория риска"} Decision -->|Безопасное: Read-Only| Auto["Автономное выполнение без пауз<br><i>(Чтение файлов, запуск тестов)</i>"] Decision -->|Опасное: Write / Network| Confirm["Обязательный запрос подтверждения<br><i>(Удаление данных, деплой)</i>"]

Матрица уровней доверия

Внимание

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

10. Итоговая шпаргалка и чек-лист создания надежного Skill

Используйте эту сводку в качестве ориентира при разработке и аудите каждого нового навыка.

Справочник команд разработчика

bash
# ─── Управление навыками в Codex ───────────────────────────────── $skill-creator # Запуск интерактивного мастера создания $<skill-name> <описание задачи> # Явный детерминированный вызов навыка /skills # Просмотр списка доступных навыков # ─── Расположение файлов в системе ─────────────────────────────── .codex/skills/<name>/SKILL.md # Проектный навык (версионируется в Git) ~/.codex/skills/<name>/SKILL.md # Персональный навык (для всей рабочей машины)

Чек-лист готовности навыка к релизу

  • Корректное имя: До 64 символов, строчные буквы латиницы через дефис (kebab-case).
  • Двусоставное описание: Поле description содержит четкую формулу «что делает навык» и «в каких случаях его вызывать».
  • Лаконичное тело: Объем SKILL.md не превышает 500 строк и содержит только специфику проекта.
  • Нумерованная структура: Инструкции оформлены последовательными шагами (1., 2., 3.).
  • Определены границы безопасности: Зафиксированы разрешенные файлы для чтения и операции, требующие подтверждения.
  • Протестировано в новой сессии: Навык проверен как прямым вызовом $name, так и через автоматический семантический подбор.
Этот гайд полностью бесплатный. Если он сэкономил вам вечер — вы можете поддержать развитие проекта.
Поддержать автора