Symptom: Codex can read your project but does not use Xcode guidance, or it invokes a skill without producing a valid build.
Fastest fix: Export the skills from the Xcode installation you use, put them in a Codex CLI discovery directory, then test skill discovery, permissions, and project builds separately.
This runbook is for independent developers using Codex CLI to maintain Swift, iOS, or macOS projects and reuse Xcode agent skills.
It also helps small teams checking project access and command permissions.
If you do not have a local Mac, use a suitable macOS environment for both setup and a real build test.
Last updated October 10, 2026. Version and export references were checked against Apple’s Xcode 27.1 RC release record, Apple’s agent extension documentation, the Xcode 27 release notes, and the Codex skills documentation. Recheck these sources if Apple changes its export guidance or Codex changes skill discovery.
SECTION 01What the Xcode skill import does—and does not—set up
An agent skill gives Codex task-specific instructions and, where included, supporting files. Importing one does not automatically give Codex permission to read every project file, run arbitrary shell commands, access signing credentials, or invoke a working Xcode build.
Keep these outcomes separate:
- Skill exported: Xcode generated skill files using the documented export flow.
- Skill discovered: Codex found the files in a location it scans and can identify the skill.
- Skill invoked: Codex selected the skill for a matching request and followed its instructions.
- Project access granted: Codex can read or edit the files needed for the task, within your configured permissions.
- Build verified: Xcode completed a project build, and you inspected the result.
This separation matters when a task fails. If Codex does not mention the skill, changing build settings will not fix discovery. If it invokes the skill but cannot read a project file, the issue is likely permission or context. If it follows the skill but the build fails, investigate the project, Xcode selection, dependencies, and build log rather than re-exporting immediately.
Apple lists Xcode 27.1 RC as released on October 5, 2026. That release record establishes the release date; it does not establish that this RC remains the latest Xcode version indefinitely. Apple’s documentation describes extending agents and exporting skills, but you should check the documentation that applies to your installed Xcode rather than treating a beta release-note workaround as a permanent requirement for every installation.
SECTION 02Before export: confirm the Xcode and Codex environments
Start from the shell environment where you run Codex CLI. A different shell, user account, or selected Xcode installation can produce a skill export that does not match the Xcode you use for project builds.
Check the active developer directory and Xcode version:
xcode-select -p
xcodebuild -version
The first command shows the developer directory selected for command-line tools; the second reports the Xcode version visible to xcodebuild. Apple documents the relationship between Xcode and command-line tools in its command-line tools installation guidance and command-line tools technical note.
If the selected directory is not the Xcode installation you intend to use, correct that before exporting. For example, after confirming your actual application path, you can select its developer directory:
sudo xcode-select --switch /Applications/Your-Xcode.app/Contents/Developer
Replace Your-Xcode.app with the installed application’s actual name and path. Do not copy the example literally if your installation is elsewhere. Then rerun the checks. Also confirm that Codex CLI starts under the expected user account and can see the project directory you plan to test.
Before moving on, note the Xcode version, the output of xcode-select -p, the Codex launch context, and the repository path. This gives you a baseline if the export or build later uses an unexpected toolchain.
Do not use a remembered beta workaround as a default fix. The Xcode 27 release notes describe version-specific information; check the applicable release notes and current agent documentation before changing your setup.
SECTION 03Export Xcode 27.1 RC agent skills
Apple’s documented export flow uses:
xcrun agent skills export
Follow the current Xcode agent extension guidance for the installed release. Do not add a destination flag, output argument, or other option based on an example from a different version unless Apple’s current instructions for your version document it.
After running the export, record the terminal output and inspect the generated files. Find the actual output location from the command’s output or the applicable Apple instructions; do not assume it is already a Codex skills directory. Check that the expected skill folders and instruction files are present and readable. Preserve the original export while you test a copy, so you can distinguish an export problem from a later file-placement or permission problem.
If the command is unavailable, stop before trying random variants. Recheck the selected developer directory, the installed Xcode version, and Apple’s instructions for that version. The command not being available in one environment does not prove that all Xcode versions lack the feature.
A successful export establishes only that Xcode generated files. It does not prove Codex can discover them, that their instructions match your repository, or that any project build will pass.
SECTION 04Import into a directory Codex actually scans
Use the current Codex CLI skills documentation to choose a destination. Codex’s documented skill structure includes a skill folder with a SKILL.md file; the location determines whether the skill is available to a project or more broadly. Check the Codex skills guide for the discovery locations and file requirements supported by the version you run.
For a repository-specific skill, use a project-level location recognized by Codex, such as .agents/skills/<skill-name>/. For a user-level installation, use the location specified in the current documentation for your Codex setup; do not assume that an Xcode export path or a folder from an older Codex guide is still scanned. If you work across multiple repositories, decide deliberately whether the instructions belong in one project or should be available to your user account.
Copy the exported skill folder into the chosen destination without flattening its structure. Verify that the skill’s SKILL.md sits at the expected level and that any referenced files remain alongside it. If you rename the folder, check for instructions or references that rely on the original name.
Then open a fresh Codex CLI session. Avoid treating an already-running session as proof that it has reloaded changed skill files. Ask it to identify the relevant skill for a harmless, read-only task, and compare its response with the skill’s stated purpose. If it does not discover the skill, recheck the path, folder nesting, file readability, and current Codex discovery rules before changing project permissions.
SECTION 05Check invocation and permissions separately
Use a request that is narrow enough to show whether Codex selected the skill, but does not ask it to edit files or run a build. For example:
Read the project structure and explain which Xcode build scheme the imported skill says to validate. Do not edit files or run commands.
Then inspect whether the response reflects the imported guidance rather than generic advice. If it does not, check the skill’s metadata and description, its placement, and whether the current session has reloaded it. Codex skills are instructions for relevant tasks, not a guarantee that every request will trigger them. OpenAI’s skills material also describes skills as structured guidance that must be discoverable and relevant to the task.
Only after discovery and invocation work should you test project access. Confirm that Codex can read the repository and any files the task requires. If the task needs a shell command, approve only the command or scope needed for that task under your configured permission model. Broad, unrestricted command access is not a prerequisite for importing a skill.
Use this checklist before allowing an edit or build:
- [ ] The active
xcode-select -poutput points to the intended Xcode installation. - [ ]
xcodebuild -versionreports the Xcode version you intend to test. - [ ] The exported files are present, readable, and preserved separately from your test copy.
- [ ] The skill folder is in a Codex-recognized location and contains the expected
SKILL.md. - [ ] A fresh Codex CLI session can identify the skill during a read-only matching task.
- [ ] Codex can read the target repository without being granted unrelated file access.
- [ ] Any command permission is limited to the commands needed for the test.
If Codex sees the skill but does not invoke it, debug the description, task match, folder structure, and session state first. Expanding shell permissions will not make a skill more discoverable.
SECTION 06Frequently asked questions
How do I export Xcode agent skills for Codex CLI?
Use the Xcode installation selected for your current command-line tools, then follow Apple’s documented xcrun agent skills export flow. Check the documentation and command options for that installed version before adding flags. Save the command output and inspect the exported files; a successful export only confirms that files were generated, not that Codex has discovered them.
Where should I put exported Xcode skills for Codex?
Use a skills directory that the current Codex CLI documentation recognizes: a project-level .agents/skills location when the skill belongs to one repository, or the documented user-level location when you want it available across projects. Keep each skill in its own folder with its required SKILL.md file, and do not assume Xcode’s export folder is automatically a Codex discovery folder.
Why can Codex see an Xcode skill but not call it?
Check the skill’s folder and SKILL.md metadata first, then start a fresh Codex session and ask for a small, read-only task that clearly matches the skill description. Also check whether the skill is enabled and whether the current project context matches its instructions. Discovery, permission to access project files, and permission to run commands are separate checks.
How can I verify that Codex can build an iOS project after importing skills?
Run a build separately from the skill-discovery test. Confirm the active Xcode developer directory, list the project’s schemes, and build a reversible test branch or sample project with an explicit simulator destination. Review the build log and resulting output. A skill being invoked successfully does not prove that Xcode, dependencies, signing, or the project configuration can complete a build.
SECTION 07Validate a real project build before relying on the setup
Use a disposable branch or a test project before asking Codex to change release code. First identify the project or workspace and the scheme you intend to build. For example, list schemes for a project with:
xcodebuild -list -project "$PROJECT"
For a workspace, use the corresponding -workspace "$WORKSPACE" argument instead. Set the variables to paths that exist in your environment; do not leave placeholder values in a command you run.
Once you have confirmed the scheme and destination, run a build that matches your validation goal. A simulator build can check compilation without claiming that distribution signing or App Store submission works:
xcodebuild \
-project "$PROJECT" \
-scheme "$SCHEME" \
-destination 'generic/platform=iOS Simulator' \
build
If you use a workspace, substitute -workspace "$WORKSPACE" for the project argument. Review the command’s exit status, the build log, and the output location reported by Xcode. If the build fails, categorize the failure before changing the skill: a missing scheme, dependency-resolution error, simulator destination issue, compiler error, or signing problem requires a different investigation.
For an archive or release workflow, validate signing and distribution requirements as a separate stage. Do not report a successful simulator build as proof that an archive can be signed, uploaded, or accepted. Likewise, a Codex response that says it followed the skill is not build evidence. Keep the build log and the exact Xcode selection with your test notes so another team member can reproduce the result.
The practical acceptance criteria are simple: Codex discovers and invokes the intended skill for a matching task; it can access only the project resources you authorize; and Xcode independently completes the build you actually need. If one of those checks fails, troubleshoot that layer rather than repeating the entire import.
SECTION 08When you do not have a local Mac
A Windows or Linux workstation can remain useful for editing and general development, but it does not replace the macOS environment needed to run Xcode and validate an Xcode build. If you need to export Xcode skills and then test the real project, you need access to a Mac environment for those steps.
A remote Mac can be a practical fit when you need a temporary macOS setup, a second environment for validation, or an online machine for Xcode-related work without buying dedicated hardware. Before choosing one, check how you will connect, where project files and credentials will live, how you will clean up the environment, and whether the service’s actual configuration fits your build. A remote session also depends on network access, so it is not ideal when you need local physical interfaces or continuous heavy workloads that justify owning and maintaining a Mac.
If you are comparing temporary access with ownership, review the actual options on the MACNOX pricing page rather than assuming a rental is always cheaper. If you lack a suitable macOS environment for export and build verification, you can also review MACNOX remote Mac options. Treat the rental as a way to obtain a Mac environment for the work you need; still verify the Xcode version, Codex discovery path, permissions, and project build yourself.
For this task, the deciding point is not whether a skill file exists. It is whether Codex can use the guidance safely and whether the Xcode build passes in the environment you plan to rely on. A local Mac makes sense when you need permanent hardware access or have sustained workloads; when you only need a temporary setup or a separate build-verification environment, evaluate a remote Mac against those same requirements before committing.