Перенос скилла из Claude в Codex: пошаговое руководство

Скилл (skill) — это папка с файлом SKILL.md, которая даёт ИИ-агенту готовый навык: инструкции, при необходимости скрипты и справочные материалы под конкретную задачу. Это руководство показывает, как перенести скилл из Claude Code в OpenAI Codex: что переедет без единой правки, а что придётся поправить руками.

Что переносится, а что нет: картина целиком

Три вещи, важные до начала переноса:

• Тело и метаданные скилла общие. name, description и markdown-инструкции работают в обоих агентах одинаково.
• Различается расположение папки. Claude читает скиллы из .claude/skills, Codex — из .agents/skills. Это самая частая причина, по которой перенесённый навык «не виден».
• Часть полей frontmatter есть только у Claude. Их нужно либо убрать, либо заменить на механизм Codex.

Анатомия скилла

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

summarize-changes/
├── SKILL.md          # обязательно: метаданные + инструкции
├── scripts/          # опционально: исполняемый код
├── references/       # опционально: справочные материалы
└── assets/           # опционально: шаблоны, ресурсы

SKILL.md состоит из двух частей: YAML-фронтматтер между --- (что это за навык и когда его применять) и markdown-инструкции (что именно делать).

Оба агента используют прогрессивное раскрытие: при старте в контекст попадают только name, description и путь к скиллу, а полное тело SKILL.md подгружается, только когда агент применяет навык. Поэтому description — это рабочий триггер: по нему агент и решает, включать навык.

Где лежат скиллы: Claude против Codex

В Codex навык можно вызвать явно (/skills или $имя-скилла) или положиться на неявный вызов по description. В Claude — командой /имя-скилла или автоматически.

Соответствие полей frontmatter

Сквозной пример: скилл «summarize-changes»

Возьмём реальный навык из официальных примеров Claude Code: он показывает незакоммиченные изменения в git и помечает рискованные места. Удобно для код-ревью и сообщений к коммитам. В нём есть Claude-специфичная вставка, на которой обычно спотыкается перенос.

Исходный скилл в Claude

Файл ~/.claude/skills/summarize-changes/SKILL.md:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
allowed-tools: Read Grep
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

Здесь две Claude-специфичные детали:

• allowed-tools: Read Grep — список инструментов, разрешённых без запроса. В стандарте Agent Skills этого поля нет.
• Строка !git diff HEAD — динамическая вставка: Claude выполняет команду и подставляет результат в текст до того, как скилл попадёт в модель. Codex так не умеет.

Пошаговый перенос

1. Создайте папку в Codex-расположении. Для личного навыка — ~/.agents/skills/summarize-changes/, для командного — .agents/skills/summarize-changes/ в репозитории.
2. Скопируйте SKILL.md и папки scripts/, references/, assets/ (если они есть) без изменений.
3. Почистите frontmatter. Оставьте name и description, уберите allowed-tools.
4. Замените динамические вставки. Строку !git diff HEAD уберите из тела и добавьте явный шаг «выполни git diff HEAD». Либо вынесите команду в scripts/diff.sh.
5. Перенесите управление вызовом. Если в Claude стоял disable-model-invocation: true, добавьте agents/openai.yaml с policy.allow_implicit_invocation: false.
6. Проверьте пути и зависимости скриптов, чтобы они запускались в окружении Codex.
7. Перезапустите Codex и проверьте навык в /skills, затем явным и неявным вызовом.

Эталонный результат для Codex

Структура папки:

~/.agents/skills/summarize-changes/
├── SKILL.md
└── agents/
    └── openai.yaml   # опционально: имя, иконка, политика вызова

SKILL.md:

---
name: summarize-changes
description: Summarizes uncommitted git changes and flags risky spots. Use when the user asks what changed, wants a commit message, or asks to review a diff.
---

## Instructions

1. Run `git diff HEAD` to read the current uncommitted changes.
2. Summarize them in two or three bullet points.
3. List any risks: missing error handling, hardcoded values, or tests that need updating.
4. If the diff is empty, say there are no uncommitted changes.

Опциональный agents/openai.yaml — если хотите задать отображаемое имя и запретить неявный вызов:

interface:
  display_name: "Summarize changes"
  short_description: "Обзор незакоммиченных изменений и рисков"
policy:
  allow_implicit_invocation: false   # вызывать только явно через $summarize-changes

Что изменилось по сравнению с Claude-версией:

• allowed-tools убрано.
• Динамическая вставка git diff HEAD превратилась в явный шаг 1.
• Управление вызовом переехало в agents/openai.yaml.
• name, description и логика инструкций остались без изменений.

Частные случаи

Скиллы со скриптами

Скрипты переносятся как есть: положите их в scripts/ и ссылайтесь из SKILL.md. Проверьте, что интерпретатор и зависимости (Python, Node и так далее) доступны в окружении Codex. Надёжнее всего так и заменять Claude-вставки команд: детерминированная логика в скрипте работает одинаково везде.

Многофайловые скиллы

Папка references/ и дополнительные markdown-файлы переносятся без изменений. Главное — сохранить относительные ссылки на них внутри SKILL.md, чтобы прогрессивное раскрытие работало: агент подгрузит файл, только когда он понадобится.

Скиллы с аргументами

Если в Claude использовались подстановки $ARGUMENTS или $1, в Codex опишите ожидаемые аргументы словами: «возьми номер задачи из запроса пользователя». Codex подставит контекст запроса сам.

Распространение навыка

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

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

1. Запустите /skills в Codex — навык должен появиться в списке.
2. Вызовите его явно: $summarize-changes. Это проверяет сам факт загрузки.
3. Дайте запрос, который должен включить навык неявно (например, «что я изменил?»). Это проверяет description.
4. Если в скилле есть скрипты — убедитесь, что они отрабатывают без ошибок окружения.

Типичные ошибки

Чеклист быстрого переноса

Ссылки

• Codex — Agent Skills
• Claude Code — Skills
• Открытый стандарт Agent Skills
• Спецификация Agent Skills
• Примеры скиллов: OpenAI · Anthropic

По теме

• Статья: Мой первый публичный репозиторий на GitHub — и это Codex-скилл для GPT Pro review
• Блог: CEO Obsidian лично написал скиллы для Claude Code
• База знаний: Skills: Codex vs Claude Code — сравнение и совместимость

Если собираете собственный набор скиллов и хотите, чтобы они одинаково работали в Claude и Codex, это реально выстроить как единую систему под ваши задачи.

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