Экспортируйте Skills из нужной установки Xcode 27, поместите их в каталог, который распознаёт Codex CLI, а затем отдельно проверьте вызов навыка, доступ к проекту и реальную сборку. Видимый Skill не означает, что Codex получил разрешение запускать Xcode или что компиляция прошла.
Эта инструкция предназначена независимым разработчикам, которые сопровождают Swift- и iOS-проекты через Codex CLI и хотят использовать инструкции Xcode Agent. Она также подойдёт небольшим командам, настраивающим доступы, и разработчикам без локального Mac, которым нужно провести проверку в macOS.
Последняя проверка сведений о выпуске — 10 октября 2026 года: страница Apple указывает выпуск Xcode 27.1 RC 5 октября 2026 года. Это дата конкретного выпуска, а не утверждение, что эта версия останется последней. Команды и расположение Skills следует повторно сверить с документацией Apple по расширению агентов Xcode и текущей документацией Codex по Skills.
SECTION 01Перед экспортом: ту ли установку Xcode и среду Codex вы проверяете?
Skills — это инструкции для агента, а не перенос всего рабочего процесса Xcode. Подключение навыка не выдаёт Codex доступ к файлам репозитория, не разрешает выполнять произвольные команды и не подтверждает, что инструменты разработчика настроены. Эти проверки проводятся раздельно.
У Xcode Agent есть механизм расширения, а Apple описывает экспорт агентных Skills. Однако наличие такой возможности в документации не означает, что каждая версия и каждая конфигурация Xcode работают одинаково. Сверьте поведение с документом Apple об агентных расширениях и примечаниями именно к установленному выпуску, а не переносите известное ограничение бета-версии на Xcode 27.1 RC без подтверждения.
Проверьте активный путь разработчика
Откройте терминал в той macOS-среде, где будете выполнять экспорт и запускать Codex CLI. Сначала проверьте выбранный каталог инструментов:
xcode-select -p
Затем узнайте версию Xcode, которую видит командная строка:
xcodebuild -version
Если на машине установлено несколько копий Xcode, один только факт установки нужного приложения не гарантирует, что команды используют именно его. Сопоставьте путь и вывод версии с приложением, из которого собираетесь экспортировать Skills. Apple объясняет выбор активного каталога и использование инструментов командной строки в технической заметке о командах сборки. Установка дополнительных инструментов и выбор установленной среды — отдельные действия; описание Apple находится в руководстве по установке Command Line Tools.
Заодно убедитесь, что запускаете Codex CLI в ожидаемой учётной записи и из нужного репозитория. Домашний каталог, переменные окружения и текущая рабочая директория могут отличаться, например, если CLI запускается из отдельной оболочки или автоматизированного задания. Не начинайте экспорт, пока не можете однозначно ответить, какая установка Xcode и какой каталог проекта задействованы.
SECTION 02Шаг экспорта: как получить файлы Skills без догадок о пути?
Для экспорта используйте документированную Apple команду:
xcrun agent skills export
Перед выполнением сверьте её доступность и ожидаемое поведение с текущей документацией Xcode Agent. Не добавляйте неподтверждённые параметры и не считайте, что одна и та же команда во всех версиях принимает одинаковые аргументы. Если на вашей установке Apple указывает отдельный способ экспорта для конкретного агента или конкретного выпуска, применяйте его только при выполнении описанных условий.
После команды зафиксируйте фактический результат: что сообщил терминал, куда записаны файлы и какие элементы появились. Не подменяйте эту проверку предположением, будто папка обязательно создана в текущем репозитории или уже совпадает с каталогом Codex. На этом этапе вы подтверждаете только экспорт, а не обнаружение навыка другим инструментом.
Проверьте содержимое экспортированного каталога. Найдите файл SKILL.md, прочитайте инструкции и сохраните связанные с навыком материалы, если они присутствуют. Не копируйте только текст описания, если рядом есть необходимые ресурсы. Если экспорт завершился сообщением об ошибке или файлов нет, сначала вернитесь к проверке выбранной установки Xcode и документации для неё — не переходите к настройке прав Codex, пока неясно, что именно было создано.
Для воспроизводимости запишите путь источника и перечень полученных файлов в заметки проекта. Это позволит отличить проблему экспорта от ошибки копирования или индексации. Сам факт, что команда завершилась без видимого сообщения об ошибке, ещё не доказывает, что Codex сможет найти и применить Skills.
SECTION 03Шаг импорта: разместите навык в каталоге, который обнаруживает Codex CLI
Официальная документация Codex описывает расположение Skills и правила их обнаружения; применяйте их к версии CLI, которой пользуетесь. Для навыка, относящегося к конкретному репозиторию, используйте структуру внутри проекта:
<путь-к-проекту>/
└── .agents/
└── skills/
└── <имя-навыка>/
└── SKILL.md
Для личного навыка, который нужен из разных проектов, используйте пользовательский каталог:
<домашний-каталог>/
└── .agents/
└── skills/
└── <имя-навыка>/
└── SKILL.md
Это примеры расположения, а не инструкция переименовать экспорт вслепую. Сохраните структуру, требуемую актуальными правилами Codex, и скопируйте весь каталог навыка, а не только SKILL.md, если экспорт содержит дополнительные файлы. В описании механизма Skills от OpenAI и материале о структуре и обнаружении навыков Codex проверьте, какие каталоги CLI сканирует и как он обрабатывает инструкции.
Если документация для используемой версии указывает специализированный путь или способ экспорта, сначала установите, к какому режиму он относится. Не считайте упоминание Codex в примечаниях к предварительному выпуску универсальным решением для любого Xcode и любой установки. Apple ведёт примечания к выпускам Xcode 27; сверяйте конкретную запись с версией, а не превращайте отдельный workaround в обязательную процедуру для всех.
После копирования откройте новую сессию Codex CLI или перезапустите текущую, если этого требует актуальная документация обнаружения. Затем проверьте, что навык появляется в доступном перечне. Если он не виден, проверьте путь, имя каталога, наличие SKILL.md и то, от имени какого пользователя запущен CLI. Перенос навыка в случайное место и расширение системных разрешений не исправят неверный каталог.
SECTION 04Что проверить после импорта: обнаружение, выбор и права — разные этапы
Сначала проведите безопасную проверку без редактирования исходников. Попросите Codex найти импортированный Skill и кратко пересказать, какие инструкции он применил бы к подходящей задаче. Не запрашивайте изменение проекта на первом проходе. Так вы проверите обнаружение и применение навыка, не смешивая результат с правами записи или поведением сборки.
Если Codex знает о Skills, но не выбирает конкретный, проверьте описание и область применения в SKILL.md. Инструкции должны соответствовать задаче, которую вы задаёте; расплывчатое описание может позволить обнаружить навык, но не помочь выбрать его для запроса. Сформулируйте задачу точнее и снова попросите объяснить применённые инструкции, всё ещё не меняя файлы. Править следует описание навыка или запрос, а не открывать доступ к дополнительным командам без необходимости.
Затем отдельно проверьте контекст проекта. Запустите Codex из ожидаемого репозитория и убедитесь, что он может читать нужные файлы. Если он не видит проект, проверьте рабочую директорию и действующие ограничения среды. Навык может находиться в пользовательском каталоге и быть доступен агенту, тогда как файлы проекта остаются вне разрешённой области.
Наконец, проверьте разрешения на команды. Успешное чтение исходников не означает, что CLI может запускать xcodebuild, тесты или скрипты. Запрашивайте только тот доступ, который необходим для выбранной операции, и учитывайте политику команды. Не делайте широкое разрешение на запуск любых команд обязательным условием импорта Skills: это самостоятельное решение по безопасности, а не требование формата навыка.
SECTION 05Проверьте проект: вызов навыка не равен успешной сборке
Перед реальной проверкой создайте обратимый контекст: отдельную ветку или тестовый проект, в котором можно обнаружить изменения и вернуть исходное состояние. Укажите Codex конкретную схему и задачу, попросите сначала описать предполагаемые действия, затем разрешайте только нужные операции. Не храните в запросе реальные секреты подписи и не помещайте учётные данные App Store Connect в материалы Skill.
После попытки сборки проверьте результат независимо от отчёта агента. Сверьте вывод Xcode, код завершения команды и наличие ожидаемого артефакта; если ваша задача включает тесты, проверьте и их результат. Для публикационного процесса Archive, подпись и загрузку тоже принимайте отдельными этапами — успешный вызов навыка не доказывает, что проект подписан или готов к отправке.
Полезно разделять четыре результата:
- Экспорт прошёл — Xcode создал файлы, которые вы можете проверить.
- Codex обнаружил Skill — файл находится в каталоге, который распознаёт CLI.
- Codex применил инструкции — содержание навыка использовано в ответе или плане действий.
- Проект собрался — команда Xcode выполнилась, а журнал и артефакт подтверждают результат.
Первые три пункта не заменяют четвёртый. Если сборка не стартует, выясните, какая именно граница не пройдена: доступ к проекту, разрешение на команду, выбранная установка Xcode, схема или настройки самого проекта. Не переустанавливайте Skills, если журнал показывает, что проблема относится к среде сборки.
Для повторной проверки записывайте источник экспорта, каталог назначения, способ запуска Codex и результат каждой стадии. Тогда после обновления Xcode или CLI вы сможете повторить процедуру и определить, изменилось ли обнаружение Skills или только поведение сборки. Команды и расположение файлов нужно перепроверить, если Apple меняет документацию Agent, выходит новый Xcode или Codex обновляет правила обнаружения.
SECTION 06Пройдите контрольный список до передачи настройки команде
- [ ]
xcode-select -pуказывает на ожидаемую среду разработчика. - [ ]
xcodebuild -versionподтверждает нужную установку Xcode, а не другую копию. - [ ] Команда
xcrun agent skills exportи её применимость сверены с документацией установленного выпуска. - [ ] Вы записали фактический путь экспорта и проверили наличие
SKILL.mdи связанных файлов. - [ ] Полная папка навыка размещена в пользовательском или проектном каталоге, который текущая документация Codex CLI определяет для Skills.
- [ ] Новая сессия Codex CLI обнаруживает навык; тестовый запрос позволяет проверить его выбор без изменения исходников.
- [ ] Доступ к файлам проекта и разрешение на запуск команд проверены независимо от импорта.
- [ ] Реальная сборка выполнена в обратимом контексте, а её журнал и ожидаемый результат проверены отдельно.
Если не выполнен один из первых пяти пунктов, не переходите к выводу о проблеме сборки: сперва исправьте выбор Xcode, экспорт или размещение файлов. Если навык виден и применяется, но сборка не проходит, исследуйте инструменты, разрешения и конфигурацию проекта как отдельный слой.
SECTION 07FAQ: что уточнить перед использованием Skills?
Как передать навыки агента из Xcode 27 в Codex CLI?
Проверьте, что командная строка использует нужный Xcode, и выполните документированную Apple команду экспорта. Зафиксируйте путь, показанный в вашей среде, и проверьте созданные файлы, прежде чем что-либо копировать. Затем перенесите полную папку навыка в каталог Codex CLI, откройте новую сессию и подтвердите, что CLI обнаруживает и применяет инструкции.
В какой каталог поместить экспортированный Skill?
Для навыка, относящегося к проекту, используйте .agents/skills/<имя-навыка>/ в корне репозитория; для личного — пользовательский .agents/skills/ в домашнем каталоге. Сохраняйте SKILL.md и дополнительные файлы. Перед настройкой сверьте правила для своей версии Codex: не путайте каталог навыков с настройками Xcode и не считайте произвольную папку автоматически обнаруживаемой.
Почему Codex показывает навык, но не использует его?
Обнаружение подтверждает, что CLI нашёл файл, но не что описание навыка подходит к запросу. Сверьте назначение в SKILL.md, сформулируйте задачу конкретнее и проверьте применение инструкций на безопасном запросе. Также проверьте, что сессия видит актуальную копию. Не предоставляйте более широкие права на команды только потому, что агент не выбрал подходящий Skill.
Как принять сборку iOS после импорта?
Проводите сборку отдельно от проверки обнаружения навыка: используйте обратимую ветку или тестовый проект, проверьте схему и разрешение на запуск Xcode, а затем изучите журнал и артефакт. Для тестов, Archive, подписи и публикации нужны собственные критерии приёмки. Утверждение Codex о завершении работы или видимый вызов Skill не доказывают, что приложение скомпилировано и готово к выпуску.
На локальном Mac вы контролируете установку Xcode и можете сразу проверить доступ к проекту, но отдельная постоянно доступная машина означает расходы на оборудование и обслуживание, потребление локального диска и необходимость самостоятельно поддерживать среду. Если Mac нужен лишь для экспорта, настройки Codex и реальной проверки сборки, аренда может быть удобнее покупки; если же вам постоянно нужна одна и та же машина, продолжительная интенсивная работа или физическое подключение устройств, локальный компьютер может оказаться разумнее. Для предварительной оценки посмотрите описание удалённой среды MACNOX, а условия и стоимость аренды Mac у MACNOX сверяйте отдельно. Выбирайте удалённый вариант только при соответствии вашей задаче: без доступного macOS/Xcode-окружения вы не сможете подтвердить реальную сборку одним лишь импортом Skills.