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

Skills превращают повторяемый рабочий процесс в модуль, который ChatGPT или Codex подключает к подходящей задаче. В Skill можно собрать инструкции, справочные материалы, шаблоны и исполняемые скрипты.

Интерфейсы, пути, API-параметры и лимиты в руководстве проверены 10 сентября 2026 года по официальной документации OpenAI.

Материал основан на официальной документации OpenAI; приведённые команды и API-запросы в рамках этой проверки не запускались.

Содержание

1. Место Skill в Codex
2. Структура и метаданные
3. Обнаружение и вызов
4. Создание, установка и проверка
5. Полезные сценарии
6. Инструменты и безопасность
7. Skills через OpenAI API
8. Чеклист нового Skill

Место Skill в Codex

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

Skill может объяснить, как работать с GitHub или Notion, но соответствующий инструмент должен быть доступен и авторизован отдельно. Для распространения Skills вместе с интеграциями используется Plugin.

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

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

При этом Skill не заменяет постоянные правила проекта, не повышает права агента и не делает произвольный скрипт безопасным.

Структура и метаданные

Минимальный Skill — директория с файлом SKILL.md:

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

Минимальный SKILL.md:

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

1. Найди последний Git-тег.
2. Получи коммиты после него.
3. Сгруппируй изменения по типам.
4. Подготовь CHANGELOG.md.
5. Покажи diff и не создавай коммит без отдельного подтверждения.

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

Файл agents/openai.yaml может задавать отображение в интерфейсе, политику вызова и зависимости:

interface:
  display_name: 'Generate Changelog'
  short_description: 'Генерирует CHANGELOG.md по истории Git'
  default_prompt: 'Подготовь changelog для текущего релиза'

policy:
  # false отключает автоматический вызов в Codex
  allow_implicit_invocation: true

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

Параметр allow_implicit_invocation по умолчанию равен true. При значении false Codex не выбирает Skill автоматически; явный вызов по-прежнему работает.

Обнаружение и вызов

ChatGPT и Codex используют поэтапную загрузку контекста, или progressive disclosure. Сначала они получают имя и описание Skill, а Codex также видит путь. Полный SKILL.md загружается после выбора навыка.

Начальный список Skills занимает не более 2% контекстного окна либо 8 000 символов, если размер окна неизвестен. При большом количестве навыков описания сокращаются, а часть Skills может не попасть в начальный список. Поэтому подробную процедуру размещайте в теле SKILL.md, а description оставляйте коротким.

Где Codex ищет локальные Skills

В Git-репозитории Codex сканирует .agents/skills в каждой директории от текущей рабочей директории до корня репозитория. Символические ссылки на директории Skills поддерживаются. Skills с одинаковым name не объединяются и могут одновременно появиться в селекторе.

Автоматический и явный вызов

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

Подготовь changelog для следующего релиза и покажи изменения.

В Codex CLI и IDE конкретный Skill можно выбрать через /skills или упоминание с $:

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

В ChatGPT для выбора Skill используется @. В desktop app доступные навыки отображаются в разделе Skills боковой панели.

Standalone Skills доступны в IDE-расширении. Skills, bundled in Plugins, также доступны в ChatGPT web, desktop и mobile, в Codex в desktop app и через Codex CLI, но не в IDE-расширении.

Создание, установка и проверка

Встроенный создатель

Для создания Skill в Codex вызовите:

$skill-creator

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

Создание вручную

Создайте директорию в одном из поддерживаемых путей и добавьте SKILL.md. Codex обнаруживает изменения автоматически; если Skill не появился, перезапустите Codex.

Установка готового Skill

Кураторский Skill можно установить через встроенный установщик:

$skill-installer linear

Установщик также поддерживает Skills из указанных репозиториев. Перед использованием стороннего пакета прочитайте SKILL.md, скрипты и зависимости.

Отключить локальный Skill без удаления можно в ~/.codex/config.toml:

[[skills.config]]
path = '/path/to/skill/SKILL.md'
enabled = false # Отключает Skill без удаления его файлов

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

Проверка результата

Для локального Skill выполните явный тестовый вызов, затем повторите аналогичный запрос без имени Skill. Проверка пройдена, если явный вызов использует нужную процедуру, а автоматический выбор срабатывает только для запроса, соответствующего description.

Для hosted shell после подключения дайте модели явную инструкцию использовать Skill, если нужна более предсказуемая проверка: документация допускает автоматический выбор, но рекомендует явную формулировку для большей детерминированности.

При создании новой версии через API проверьте ответ: он должен описывать объект skill.version и содержать поля id, created_at, description, name, skill_id и version.

Полезные сценарии

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

Задача: проверять запрос на слияние (pull request) по единым критериям.

Действие Skill: прочитать правила проекта, проверить сравнение изменений (diff) и тесты, классифицировать замечания как [BLOCK], [WARN] и [NOTE].

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

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

Подготовка развёртывания на тестовую среду (staging)

Задача: пройти известные проверки перед обновлением тестовой среды.

Действие Skill: проверить ветку и незакоммиченные изменения (dirty state), запустить обязательные тесты, собрать артефакт, показать план изменения и отката.

Наблюдаемый результат: зафиксированы версия, результаты проверок и состояние проверки работоспособности (healthcheck).

Ограничение: наличие Skill не даёт разрешения на развёртывание. Внешняя запись требует доступных прав и подтверждения.

Подготовка документа требований к продукту (PRD)

Задача: создавать продуктовые документы одной структуры.

Действие Skill: собрать Problem, Target user, Proposed solution, Success metrics, Risks и Out of scope.

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

Ограничение: Skill не должен выдумывать исследования, метрики или бизнес-результаты.

Инструменты и безопасность

Skill использует только инструменты текущей среды. Доступ к shell, MCP, сети или внешнему сервису должен быть настроен отдельно. Запрет среды нельзя обойти инструкцией внутри Skill.

Не предоставляйте конечным пользователям произвольный выбор Skills из непроверенного открытого каталога. Безопаснее заранее сопоставить проверенные навыки с конкретными сценариями продукта.

Skills через OpenAI API

API поддерживает два режима выполнения: локальный режим (local shell) и hosted shell в контейнерной среде.

В hosted shell используются загруженные skill_reference, которые подключаются через tools[].environment.skills. В local shell передаются локальные name, description и path; формат skill_reference там не поддерживается.

Skill можно загрузить как multipart-директорию или zip-архив с одной верхнеуровневой директорией:

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'

Пример подключения к hosted shell в Responses API:

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model = 'gpt-6-astra',
    tools = [{
        'type': 'shell',
        'environment': {
            'type': 'container_auto',
            'skills': [
                {'type': 'skill_reference', 'skill_id': '<skill_id>'},
                {'type': 'skill_reference', 'skill_id': '<skill_id>', 'version': 2}
            ]
        }
    }],
    input = 'Use the skills for this task.'
)

print(response.output_text)

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

Локальный режим также поддерживает Skills, но требует локальных путей и полей name, description и path. skill_reference для него не используется.

Версии и лимиты

• целое значение version фиксирует конкретную версию;
• version со значением latest выбирает последнюю загрузку;
• без version используется default_version;
• новая версия Skill является immutable, то есть неизменяемой после создания.

Имена файлов skill.md и SKILL.md сопоставляются без учёта регистра. Проверка служебных полей верхней части файла (front matter) следует спецификации Agent Skills.

Для воспроизводимого боевого процесса (production) фиксируйте модель и версию Skill.

Официальные ссылки

• Build skills
• Skills в OpenAI API
• API reference версий

Чеклист нового Skill

Следующий шаг

Если вы планируете распространять навыки вместе с интеграциями, прочитайте руководство «Skills и Plugins в Codex App».

Связанные материалы

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

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov