Xcode 27 Agent Skills 在 Codex 不可用？2026 修复指南

截至 2026 年 10 月 10 日，Apple 的 Xcode 27 发布说明已记录 Agent Skills 可能未出现在 Codex 中，并给出了导出处理方式；先确认当前命令行工具指向 Xcode 27，再按 Apple 指引导出到 Codex 目录。命令成功只证明导出步骤执行过，不代表 Codex 已读取或会遵循这些技能。(Apple Xcode 27 发布说明)

适合你阅读：使用 Codex 编写 Swift 或 SwiftUI 项目、想复用 Xcode 27 随附 Apple 指导的开发者。
通过 SSH 管理远程 Mac、同时维护多套 Xcode 工具链的 DevOps 工程师。
需要评估个人技能目录与团队共享方式的研发平台维护者。

本周建议动作：先记录当前活动工具链与导出目录，再做一次备份后导出；如果结果仍不符合预期，停止重复覆盖，转而检查 Codex 当前版本对该目录的读取情况。

SECTION 01 先确认 Xcode 27 是当前工具链

Xcode 27 的系统要求页面列出 macOS Tahoe 26.6 或更高版本。这不是说满足系统要求就一定能导出技能，而是先排除一个常见前置问题：机器上装有 Xcode 27，不等于终端中的 xcrun 正在使用它。可对照 Apple 的 Xcode 系统要求表确认环境，再看 Apple 关于命令行工具的说明了解 Xcode 与命令行工具的关系。

在你通过 SSH 登录的同一个用户会话中运行：

xcode-select -p
xcodebuild -version

xcode-select -p 显示当前活动开发者目录；xcodebuild -version 则用于核对该会话能调用到的 Xcode 版本。把两项输出放在一起看：如果目录仍是 /Library/Developer/CommandLineTools，或版本输出不是你预期的 Xcode 27，就不要先尝试导出，先修正选择状态。xcrun 会依据当前开发者目录查找工具，相关机制可参阅 Apple 的命令行工具技术说明。

如果机器安装了多个 Xcode，使用已安装版本的实际路径切换，例如：

sudo xcode-select --switch "/Applications/你的Xcode27.app/Contents/Developer"

将示例路径替换成机器上的真实路径；不要照抄占位文字。切换后重新执行前面的核验命令。远程环境若由多人共用，先确认切换影响的是预期主机与维护窗口；否则，你可能修好了当前 SSH 会话，却改变了其他构建任务使用的默认工具链。Apple 的 Xcode 27 发布说明将选择 Xcode 27 作为默认 Xcode 列为导出前置步骤。

SECTION 02 命令无法运行时，先分辨是工具链还是安装问题

如果终端提示找不到 agent 子命令，或 xcrun agent skills export 无法执行，先不要把它直接归因为 Codex 加载故障：命令尚未成功运行，Codex 还没有机会读取导出结果。

按这个顺序核对：

1. 记录 xcode-select -p 输出，确认活动目录属于预期的 Xcode 27 安装。
2. 核对 xcodebuild -version 输出，避免只凭应用程序名称判断版本。
3. 回看目标 Xcode 安装是否完整、是否确实包含 Apple 发布说明中所述的命令。
4. 若问题仍在，将完整命令、终端原始报错与两项核验输出保留下来，再对照当前 Xcode 27 发布说明确认适用的版本状态与处理方式。

Apple 的 WWDC26 演示说明，可用 xcrun agent skills export 将 Xcode 使用的技能导出为 Markdown 文件，供其他工作流使用；但发布说明对 Codex 不可用问题给出的具体处理方式还包含目标目录和替换参数。因此，演示中的一般导出命令与发布说明中的针对性修复不能互相替代，尤其不要推断任意目标目录都会自动被 Codex 发现。(Apple WWDC26 开发者活动演示)

SECTION 03 按官方目录导出，并把覆盖风险控制在可回退范围内

Apple 给出的 Codex 目标目录是当前用户主目录下的：

~/Library/Developer/Xcode/CodingAssistant/codex/skills/__xcode

确认活动工具链后，按发布说明运行：

xcrun agent skills export --replace-existing ~/Library/Developer/Xcode/CodingAssistant/codex/skills/__xcode

这正是 Apple 针对“Apple-authored Agent Skills 可能未出现在 Codex 中”列出的处理方式。注意，--replace-existing 表示导出时允许替换目标中已有内容；运行前先检查目标目录是否已有团队手工维护的文件，必要时复制备份。若要查看参数含义，以你当前安装版本的命令帮助及 Apple 发布说明为准，不要把某次机器上的输出当成所有版本都必然一致的结果。

导出后先检查文件是否生成，而非立即判断 Codex 已加载：

find "$HOME/Library/Developer/Xcode/CodingAssistant/codex/skills/__xcode" -name 'SKILL.md' -print

如果路径不存在或没有预期文件，保存命令输出，检查导出目标是否写错、当前用户是否与运行 Codex 的用户相同，以及命令是否明确报告错误。远程 Mac 通过 SSH 操作时，尤其要避免用管理员账户导出、却在另一个普通用户账户中启动 Codex：两个账户的 ~ 指向不同位置。

SECTION 04 文件已生成，Codex 仍未识别时该查什么

排障时把状态拆成三层：命令已执行、技能文件已写入目标、Codex 已识别并在任务中遵循。前两层可以通过终端记录与文件清单确认；第三层必须用当前 Codex 版本实际验证，不能仅凭目录存在就下结论。

Apple 发布说明指定的路径是面向 Codex 的导出位置；不过，Codex 是否在你的当前版本、当前运行方式和当前用户上下文中读取该目录，需要按实际环境确认。OpenAI 对技能的说明指出，技能通常以含 SKILL.md 的目录组织；可参照 OpenAI 的技能概念说明，但不要把其他产品接口或插件的加载规则直接套用成桌面 Codex 的本地发现规则。

检查目录层级和文件内容时，重点确认 SKILL.md 不只是存在于某个子目录中，还包含可识别的技能名称、用途说明与指导文本。团队如果还要共享技能，不要未经验证就把个人导出目录当成仓库内共享目录；先查清当前 Codex 版本实际支持的项目级技能位置，再另行纳入版本管理。技能、项目指令和插件包属于不同的工作流组成部分，不能假定它们可以随意互换目录配置。

SECTION 05 用 Swift 任务验收整条链路

最后用一个小而真实的 Swift 或 SwiftUI 修改验证，而不是只看终端输出。选择一个能触发已导出技能指导的任务，例如让 Codex 检查一个 SwiftUI 视图的无障碍标签，并按技能指导提出必要修改；先要求它指出将使用的指导，再检查建议与改动是否确实符合文件内容。

按以下里程碑逐项记录：

1. 环境：记录 macOS 版本、xcode-select -p 与 xcodebuild -version 的输出；Xcode 27 的系统条件以 Apple 系统要求页面为准。
2. 导出：保留运行的完整命令、时间、退出状态和终端输出。
3. 目录：保存目标路径与 SKILL.md 文件清单；必要时检查技能名称和说明是否正确。
4. 行为：在 Codex 中执行同一 Swift 任务，记录它是否识别并遵循该技能，而不是只记录回答“已加载”。
5. 回退：若任务没有体现指导，保留证据，停止重复覆盖；再核对运行 Codex 的用户、当前 Codex 版本说明以及该目录是否为其支持的发现位置。

上表中的“文件存在”与“行为通过”是不同验收项，任何一个都不能替代另一个。

SECTION 06 远程 Mac 是否适合这次修复

如果你手头已经有符合条件的 Mac，先在现有环境核验即可；单纯为一次目录排障购买设备通常不必要。相反，如果当前方案是临时借用开发机或反复切换不受你管理的机器，常见代价是工具链版本不可控、用户目录权限不一致、复测证据难以留存。你可以先对比远程 Mac 方案与费用，判断是否值得为这次 Xcode 27 与 Codex 联调准备独立环境。

因此，先确定问题是否真来自环境缺失：如果只是活动工具链选错，修正选择并重新导出比增加一台机器更直接；如果你没有可用的 Xcode 27 环境，或需要隔离验证而不想改动现有构建节点，临时远程 Mac 才有明确价值。VPSNIX 的远程 Mac 方案可作为本次验证环境的候选；长期稳定重负载、必须使用本地物理接口或已有可控设备时，则先评估自有 Mac 是否更合适。