症状：Codex 已经能读到 Xcode skill 文件，但你不确定它是否真的会调用，更无法确认项目能不能编译。
最快解法：先从当前选中的 Xcode 导出技能，再放入 Codex CLI 实际使用的技能目录；随后分别验收技能调用、项目权限和构建结果，不要把其中一项通过当成全部通过。
这篇教程适合用 Codex CLI 编写或维护 Swift、iOS 项目的独立开发者，也适合负责 Agent 配置与权限的小团队成员。
如果你没有本地 Mac、需要配置 Xcode 工具链并真实构建项目，也可以按文中的验收步骤评估远程 Mac。
最后更新于 2026 年 10 月 10 日；版本与命令说明核对自 Apple Developer 发布页、Xcode 27.1 RC 发布说明、Xcode 27 Release Notes，以及 Codex 官方技能文档。 Apple 发布页记录 Xcode 27.1 RC 于 2026 年 10 月 5 日发布。
SECTION 01先划清边界：导入的是技能，不是整套 Xcode 工作流
Xcode agent skills 是给 Agent 使用的任务指引，帮助它理解某类工作应遵循的流程；它们本身不会自动给 Codex CLI 项目文件权限，也不会替你配置 Xcode 命令、签名凭据或构建目标。Apple 将技能、命令权限和外部 Agent 接入 Xcode 能力分别说明，配置时也应拆开验证。Apple 的 Xcode Agent 扩展文档介绍了这些能力与配置边界。
因此，这次迁移只解决“Codex 能否发现并使用一份技能说明”。你仍要单独确认它能否访问项目目录、是否获准运行必要命令，以及 Xcode 是否能对目标项目完成构建。把三件事合成一个“导入成功”提示，会让技能可见、权限不足和构建失败互相混淆。
截至 2026 年 10 月 10 日，Apple 发布页列出 Xcode 27.1 RC 于 2026 年 10 月 5 日发布。这只能说明发布页记录的版本状态，不能据此推断之后没有更新。
⚠️ Apple 的 Xcode 27 Beta Release Notes 曾把“Apple 编写的 skills 可能无法供 Codex 使用”列为已知问题，并给出 workaround。那是 Beta 阶段的说明，不是 Xcode 27.1 RC 仍存在该问题的证据；应先检查当前安装的帮助和实际导出结果。Xcode 27 Release Notes中的说明不要泛化为所有安装环境的固定故障。
SECTION 02导出前先核对：命令实际会调用哪套 Xcode？
本地装有多个 Xcode 副本时，终端中的 xcrun 会依据当前开发者目录找到工具。若活动目录指向另一份 Xcode，你可能从错误版本导出技能；而单独安装的 Command Line Tools 也不能代替完整 Xcode 提供全部工具，例如 xcodebuild 只随 Xcode 提供。Apple 的命令行工具说明解释了 Xcode 与命令行构建工具的关系。
先记录当前环境：
xcode-select -p
xcodebuild -version
xcrun --find xcodebuild
xcrun agent skills export --help
如果 xcode-select -p 指向的不是预期版本，先按团队约定切换开发者目录，再检查输出；不要仅因 /Applications 中存在目标应用，就默认终端一定正在使用它。安装或选择工具前，也可以对照 Apple 关于安装 Xcode 命令行工具的说明核实当前环境。
| 核对项 | 你要确认的内容 | 不符合时的处理 |
|---|---|---|
| 活动开发者目录 | xcode-select -p 输出对应预期的 Xcode |
先切换目录，再重新检查 |
| Xcode 版本 | xcodebuild -version 与准备导出的版本相符 |
不要从另一份 Xcode 导出后直接复制 |
| 导出子命令 | 本机 xcrun agent skills export --help 能显示该子命令与选项 |
若不可用，核对安装版本和对应发布说明，不要猜参数 |
| Codex 启动环境 | 启动 Codex CLI 的用户与终端环境明确 | 确认写入的是该用户的技能目录 |
SECTION 03第一步：从当前 Xcode 导出，并保留检查证据
Apple 的 Xcode 27 Beta Release Notes 曾给出以下命令形式，包含 --replace-existing 选项和 Xcode 的 Codex 配置目录：
xcrun agent skills export \
--replace-existing \
"$HOME/Library/Developer/Xcode/CodingAssistant/codex/skills/__xcode"
不要把这条 Beta workaround 当作所有 RC 环境必须照抄的唯一命令。 先对照当前安装中的 xcrun agent skills export --help；只有帮助输出确认选项有效、目标符合你要导出的内容时，才使用对应参数。若你希望先检查文件而不覆盖既有内容，应选择本机帮助明确支持的非覆盖方式或临时目标目录。Apple 的公开说明将配置文件目录描述为 Xcode 使用的专属目录，并指出这些配置只影响从 Xcode 启动的 Agent。
导出后先检查目录是否生成、技能清单是否存在、文件内容是否可读。保留导出路径与清单内容，作为“Xcode 已导出”的证据；它并不能证明 Codex CLI 已经发现技能。导出内容若带有资源或引用文件，复制时要保留相对目录结构，不能只挑出一个 Markdown 文件。
| 导出后观察到的结果 | 能证明什么 | 还不能证明什么 |
|---|---|---|
| 命令成功退出且目标目录出现文件 | 导出命令生成了输出 | Codex CLI 已发现或调用技能 |
| 找到技能清单与说明 | 导出文件有可检查的技能内容 | 项目权限与命令权限可用 |
| Codex 会话中能选择或调用技能 | 技能发现与调用流程可工作 | Xcode 构建或测试成功 |
SECTION 04第二步：按 Codex CLI 的目录规则放置技能
Codex 的技能结构以含有 SKILL.md 的技能目录为单位。Codex 官方示例给出了用户级目录 ~/.codex/skills/技能名/SKILL.md，以及仓库级目录 .codex/skills/技能名/SKILL.md；选择用户级目录可供该用户的多个仓库使用，选择仓库级目录则便于将技能与项目一起管理。Codex 技能结构与发现说明介绍了清单文件和仓库范围的用法。
Xcode 的 ~/Library/Developer/Xcode/CodingAssistant/codex 路径属于 Apple 文档描述的 Xcode 配置区域，不应因为目录名中有 codex，就推断独立启动的 Codex CLI 会自动扫描它。将导出的技能整理到 Codex CLI 的发现位置，再核对是否多嵌套了一层目录：
~/.codex/skills/<skill-name>/SKILL.md
若导出得到一个包含多项技能的父目录，应把每项技能目录分别放到 skills 下，而不是把父目录整体改名成单一技能。检查 SKILL.md 中的名称、用途说明及引用文件；若导出格式与 Codex 的技能目录结构不匹配，应按 Codex 文档整理目录，不要假定文件扩展名相同就代表格式兼容。OpenAI 对技能的说明也将 SKILL.md、可选资源文件和执行工具分别列为技能包组成部分。OpenAI 的 Skills 文档说明了技能清单及资源文件的基本结构。
| 放置方案 | 适合的情形 | 验收重点 |
|---|---|---|
~/.codex/skills/ 用户级技能 |
希望同一用户在不同仓库复用 | Codex CLI 以目标用户启动，并在新会话发现 |
仓库内 .codex/skills/ |
技能只服务于当前项目，需随仓库维护 | 仓库路径正确，团队成员能获得同一份文件 |
| Xcode 的 CodingAssistant 配置目录 | 配置从 Xcode 内启动的 Agent | 不将它误认为 Codex CLI 的通用扫描目录 |
SECTION 05第三步：先做只读调用测试，再收紧权限
技能放好后，开启新的 Codex CLI 会话，先运行不修改文件、不执行构建的测试任务。例如，让它说明是否发现目标技能、技能要求的工作步骤是什么，以及它会检查哪些项目事实。OpenAI 的技能评估指南建议先用明确的调用请求观察技能是否触发，再根据实际行为验证；仅凭文件存在不能判断 Agent 是否会选择它。
若 Codex 能看到技能却不调用，按顺序检查：当前会话是否重新加载、目录中是否存在正确的 SKILL.md、清单中的技能名称与描述是否对应你给出的任务，以及技能目录是否放置在当前项目或用户实际使用的目录下。你也可以在测试提示里明确指定技能名，用来区分“发现失败”和“自动触发不稳定”。
接着单独确认项目访问和命令授权。Apple 的文档说明，Agent 对命令与工具的访问由权限设置控制；因此，不要为了技能导入就开启宽泛命令权限。优先只授权当前任务必需的工具，并从只读检查开始。
SECTION 06第四步：在可回退项目中验收构建结果
技能调用确认后，再进入真实项目验收。先切到可回退分支或专用测试项目，让 Codex 按技能指引执行有限任务；在允许修改前审阅计划，在修改后检查差异，再由你独立核对实际构建命令与日志。不要把 Agent 的文字回答当成构建证据。
若目标是 iOS 项目，至少记录实际使用的 Xcode 版本、构建目标、命令退出状态、日志中的错误，以及预期产物是否存在。若工作流还包含测试或归档，就分别检查测试结果和归档产物；技能只提供操作指引，不会自动证明这些结果合格。Apple 的 Xcode 文档将项目访问、Agent 能力与构建和测试功能联系起来，但外部 Agent 能使用哪些能力，仍需按实际集成和授权状态确认。
场景案例：你在 Windows 或 Linux 上维护 Swift 代码，Codex CLI 能按导入的技能给出修改建议，却没有 macOS 与 Xcode 可供执行构建。此时，代码审阅可以继续，但无法在当前环境完成依赖 Apple 工具链的真实验收；把这两类结果分开记录，才不会把“技能工作正常”误报成“iOS 构建已通过”。
没有本地 Mac 时，可以评估远程 Mac 是否适合承载导出、Codex CLI 配置和项目构建。部署前先确认访问方式、账号与项目文件如何交付、构建期间如何保存日志和产物；这些条件应以你所选环境的实际说明为准。关于配置与成本，可以先查看 MACNOX 的方案与计费说明，不要用未经核实的性能、价格或节点信息替代自己的验收记录。
SECTION 07导入完成前逐项勾选
- [ ]
xcode-select -p与版本检查结果指向预期 Xcode。 - [ ]
xcrun agent skills export --help已确认当前机器支持所用命令与选项。 - [ ] 导出目录及技能文件已检查，原始文件结构有记录。
- [ ] 技能已放入 Codex CLI 的用户级或仓库级目录，而非仅留在 Xcode 专属目录。
- [ ] 新会话中的只读任务确认 Codex 能发现并调用目标技能。
- [ ] 项目读取权限、命令授权和 Xcode 构建能力分别检查。
- [ ] 在可回退项目中核对构建日志、退出状态与目标产物；技能调用不计作构建通过。
SECTION 08常见问题
从 Xcode 27 导出技能时，先检查什么？
先确认活动开发者目录和当前版本，再查看本机 xcrun agent skills export --help。Beta Release Notes 曾记录带 --replace-existing 的导出 workaround，但你应先验证当前 RC 的帮助输出与选项，再将结果检查后放入 Codex CLI 的技能目录。
Codex CLI 通常从哪里读取技能？
独立使用 Codex CLI 时，优先将每项技能放在用户级 ~/.codex/skills/技能名/SKILL.md，或放在项目内 .codex/skills/技能名/SKILL.md。Xcode 的 CodingAssistant 目录是另一种配置场景；不要仅凭目录名称认定 Codex CLI 会自动扫描它。
技能文件已经存在，但任务中没有触发，怎么排查？
先重新开启会话，再用只读任务明确点名技能，检查清单文件、目录层级和技能说明是否匹配任务。若明确指定后可调用、自动任务却不触发，问题更可能在触发描述或会话发现流程；项目文件和命令权限仍需另行验收。
怎样判断导入后已经具备 iOS 构建能力？
在可回退分支中执行真实构建，并检查实际 Xcode 版本、构建命令、日志、退出状态和预期产物。技能进入上下文只证明指引可用；编译、测试与发布是不同验收项，必须分别看结果。
把 Xcode skills 接入 Codex CLI，最容易出错的不是复制文件，而是把技能发现、权限配置和项目构建混成一个判断。若你已有可用 Mac，先按本地工具链完成上述验收；若你缺少 macOS 环境，或需要一台独立环境执行 Xcode 配置与构建，再根据使用周期比较自购设备、本地运行和远程 Mac。自购适合长期固定负载，本地运行适合已有设备且不需隔离环境；远程方案则需额外确认远程访问、文件交付与凭据管理。若你决定评估远程环境，可查看 MACNOX 的 Mac 租赁选项；是否租用，应由项目持续时间和实际验收需求决定。