Skills в OpenAI Codex — как расширить возможности coding-агента

Skills — это способ расширить Codex за пределы генерации кода. Skill упаковывает инструкции, ресурсы и скрипты в один переиспользуемый модуль, чтобы агент надёжно выполнял специфические рабочие процессы — от CI-пайплайнов до code review по стандартам команды.

Что такое Skill и зачем он нужен

Без Skills Codex — сильный агент для кода. Со Skills — настраиваемый инструмент под конкретные задачи команды: CI-пайплайны, документация, ревью по внутренним стандартам, интеграция с корпоративными сервисами.

Что Skill умеет:

• Давать Codex конкретные инструкции по рабочему процессу (не только код)
• Подключать внешние скрипты и ресурсы
• Вызываться автоматически по контексту задачи или явно по имени
• Делиться между членами команды и с сообществом
• Комбинироваться с Automations в Codex app для рутинных задач

Что Skill НЕ делает:

• Не заменяет AGENTS.md (правила поведения агента в проекте)
• Не является MCP-сервером (Skill — инструкция, не инструмент с API)

Skills vs Tools vs System Prompts

Три слоя настройки агента — каждый для своего:

Правило: не дублируйте Skills в system prompt. Иначе теряется весь смысл — переиспользуемость, версионирование и условная загрузка.

Структура Skill

Skill — это директория с обязательным файлом SKILL.md и опциональными скриптами и ресурсами.

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

SKILL.md — минимальная структура

---
name: generate-changelog
description: Генерирует CHANGELOG.md на основе коммитов с момента последнего тега
---

## Инструкция

1. Запусти `git log --oneline <last-tag>..HEAD`
2. Сгруппируй коммиты по типу: feat, fix, chore
3. Запиши результат в CHANGELOG.md в формате Keep a Changelog

Расширенный frontmatter (agents/openai.yaml)

Формат openai.yaml позволяет настроить UI, политику вызова и зависимости:

interface:
  display_name: "Generate Changelog"
  short_description: "Генерирует CHANGELOG.md по git-истории"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Подготовь changelog для текущего релиза"

policy:
  allow_implicit_invocation: true   # Codex сам подключает Skill по контексту

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

Как Codex находит и загружает Skills

Codex использует progressive disclosure — двухэтапную загрузку:

1. Читает метаданные — name, description, путь и данные из agents/openai.yaml всех доступных Skills
2. Решает, нужен ли Skill — если подходит, загружает полный SKILL.md
3. Выполняет задачу с инструкциями Skill

Преимущество: контекстное окно не засоряется инструкциями всех Skills подряд — только нужные загружаются в нужный момент.

Где размещать Skills

Codex сканирует Skills из нескольких расположений с разной областью действия:

Codex поддерживает симлинки на директории Skills и следует по ним при сканировании. Если два Skills имеют одинаковое name, Codex не объединяет их — оба отображаются в селекторе.

Как вызвать Skill

Автоматически (implicit invocation)

Codex сам подбирает Skill по контексту задачи — если description достаточно точный и в openai.yaml параметр allow_implicit_invocation не выставлен в false.

Явно в промпте

В CLI или IDE используйте /skills или символ $ для упоминания Skill:

$generate-changelog подготовь релизные заметки для v2.3.0

Через Codex app (UI)

1. Открыть проект в Codex app
2. Нажать Skills в боковой панели — там видны все Skills из ваших проектов
3. Выбрать нужный Skill → нажать Run или вызвать в чате

Создание Skills

Через встроенный skill-creator

Самый быстрый способ — использовать встроенную команду:

$skill-creator

Creator спрашивает, что Skill делает, когда должен срабатывать и нужны ли скрипты. По умолчанию создаёт instruction-only Skill.

Установка готовых Skills

Для установки Skills из репозиториев используйте $skill-installer:

$skill-installer linear

Codex автоматически обнаруживает новые и изменённые Skills. Если обновление не подхватывается — перезапустите Codex.

Включение/выключение Skills

Можно отключить Skill без удаления через ~/.codex/config.toml:

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

После изменения конфига нужен перезапуск Codex.

Встроенные инструменты внутри Skills

Практические примеры

Skill: ревью по стандарту команды

---
name: team-review
description: Проводит code review по внутренним стандартам команды. Используй при pull request review. Не используй для архитектурных решений.
---

При ревью проверяй:
1. Есть ли тесты на все новые публичные функции
2. Соответствие naming convention из STYLE_GUIDE.md
3. Отсутствие прямых SQL-запросов вне репозитория
4. Наличие docstring на функциях сложнее 5 строк

Формат вывода: список пунктов с уровнем критичности [BLOCK / WARN / NOTE]

Skill: автоматический деплой на staging

---
name: deploy-staging
description: Деплоит текущую ветку на staging. Используй когда просят задеплоить или обновить staging. Не используй для production-деплоя.
---

1. Убедись, что все тесты прошли: `npm run test`
2. Собери образ: `docker build -t app:staging .`
3. Задеплой и проверь healthcheck
4. Если статус не 200 — откати и сообщи

Skill: создание PRD по шаблону

---
name: create-prd
description: Создаёт PRD для новой фичи по корпоративному шаблону. Вызывай явно — не использовать автоматически.
---

Используй Notion MCP для создания страницы.
Заполни разделы: Problem, Solution, Success Metrics, Out of Scope.

Skills через API

Skills можно загружать и использовать программно через OpenAI API — полезно для CI/CD, автоматизации и массовой настройки.

Загрузка Skill

Вариант A: отдельные файлы (multipart)

curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'files[]=@./my-skill/SKILL.md;filename=my-skill/SKILL.md;type=text/markdown' \
  -F 'files[]=@./my-skill/run.py;filename=my-skill/run.py;type=text/plain'

Вариант B: zip-архив (рекомендуется)

zip -r my-skill.zip my-skill
curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'files=@./my-skill.zip;type=application/zip'

Использование в Responses API

Skills монтируются через tools[].environment.skills:

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    tools=[{
        "type": "shell",
        "environment": {
            "type": "container_auto",  # или "local"
            "skills": [
                {"type": "skill_reference", "skill_id": "<skill_id>"},
                {"type": "skill_reference", "skill_id": "<skill_id>", "version": 2},
            ],
        },
    }],
    input="Используй skill для анализа CSV и запиши результат в /mnt/output."
)

Версионирование

• version: 2 — пин на конкретную версию (для продакшна)
• version: "latest" — всегда последняя версия
• Без указания — используется default_version

Лимиты API

Community Skills и agentskills.io

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

Где искать готовые Skills:

• agentskills.io — официальный каталог
• GitHub-поиск: filename:SKILL.md — тысячи публичных Skills
• OpenAI Cookbook — примеры использования Skills через API
• $skill-installer — встроенный установщик в Codex

Совместимость с Claude Code

Оба инструмента используют единый открытый стандарт agentskills.io — Skills переносимы между ними.

Skills от Claude Code работают в Codex с минимальными правками:

• Скопировать из .claude/skills/ в .agents/skills/
• Добавить agents/openai.yaml с policy.allow_implicit_invocation (вместо invoke: auto)
• Убрать hooks — Codex их пока не поддерживает

Best practices

1. Держите Skills фокусированными — один Skill = одна задача
2. Предпочитайте инструкции скриптам — скрипты нужны только для детерминированного поведения или внешних инструментов
3. Пишите императивные шаги с явными входами и выходами
4. Добавляйте негативные примеры в description: «когда НЕ использовать» — это улучшает маршрутизацию
5. Проектируйте Skills как маленькие CLI — запускаются из командной строки, выводят детерминированный stdout, падают громко с ошибками
6. Не дублируйте Skills в system prompt — иначе теряется переиспользуемость и версионирование
7. Осторожно с сетевым доступом — если нужен, используйте строгие allowlists и считайте вывод инструментов недоверенным

Чеклист: создание нового Skill

Ссылки

По теме

• Статья: 12 приёмов, которые превращают ИИ-агента из игрушки в рабочий инструмент
• Блог: Пять правил, которые сделают вашего ИИ-агента по-настоящему полезным
• База знаний: OpenAI Codex — облачный coding-агент для параллельной разработки

Если вы настраиваете Codex для команды и хотите разобраться, какие Skills создать первыми — давайте обсудим.