[Codex][Skill] agent setup 仍使用旧的 ~/.codex/skills 路径，当前 Codex 从 ~/.agents/skills 发现用户 Skill

[CL-SC552]

标题：[Codex][Skill] agent setup 仍使用旧的 ~/.codex/skills 路径，当前 Codex 从 ~/.agents/skills 发现用户 Skill

环境

• ReadAny Desktop：v1.3.5
• ReadAny CLI：v0.1.0
• Windows：Windows 11 x64
• 客户端：当前版本 Codex Desktop
• ReadAny Skill 受管理源目录：

C:\Users\<USER>\.agent\skills\readany

问题描述

执行以下命令为 Codex 安装 ReadAny Skill：

readany agent setup --user --client codex --profile readonly --json

ReadAny CLI 会尝试为 Codex 创建旧式客户端链接：

C:\Users\<USER>\.codex\skills\readany

但是，当前 OpenAI Codex 官方文档规定的用户级 Skill 发现目录是：

C:\Users\<USER>\.agents\skills

即：

$HOME/.agents/skills

因此，ReadAny CLI 显示 Skill 已安装或客户端链接已管理，并不代表当前 Codex 能够实际发现该 Skill。

官方文档：

https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills

复现步骤

1. 确保以下目录中不存在 ReadAny Skill：

C:\Users\<USER>\.agents\skills\readany

2. 执行：

readany agent setup --user --client codex --profile readonly --json

3. 确认 ReadAny CLI 创建或管理了：

C:\Users\<USER>\.codex\skills\readany

4. 完全重启 Codex Desktop。
5. 检查 Codex 当前可用 Skill。

实际结果

• ReadAny doctor 可以把旧式 .codex\skills\readany 判断为 installed / managed；
• ReadAny 设置界面可以显示 AI 助手已经安装；
• 当前 Codex 重启后仍不能发现 ReadAny Skill；
• ReadAny 设置界面的“客户端链接”可能继续显示需要修复。

预期结果

当客户端为 Codex 时，ReadAny CLI 应按照当前 OpenAI 官方约定，将用户级 Skill 链接安装到：

C:\Users\<USER>\.agents\skills\readany

doctor 和 ReadAny 设置界面也应检查当前 Codex 实际使用的 .agents\skills 路径，而不是仅检查旧的 .codex\skills 路径。

已验证的临时解决办法

保留 ReadAny 管理的 Skill 源目录：

C:\Users\<USER>\.agent\skills\readany

然后手动创建指向该目录的目录联接：

C:\Users\<USER>\.agents\skills\readany
    → C:\Users\<USER>\.agent\skills\readany

重启 Codex 后，ReadAny Skill 可以被正常发现和读取。

该联接可以单独删除，不会删除受管理的 Skill 源目录。

建议修复

建议更新 Codex 客户端适配：

1. 将用户级 Codex Skill 目标改为 $HOME/.agents/skills/<skill>；
2. agent setup、repair、doctor 和桌面端状态检查使用同一套路径定义；
3. 将旧的 $HOME/.codex/skills 只作为历史兼容路径，而非当前主要目标；
4. 已检测到旧路径时，提供迁移到 .agents/skills 的修复操作；
5. Windows 创建普通符号链接失败时，可以明确提示权限问题，并考虑使用目录联接作为兼容方案；
6. 状态界面应区分：
   • Skill 源文件已安装；
   • 当前客户端链接已建立；
   • 当前客户端已实际发现 Skill。

补充说明

这与 MCP 配置是否写入 Codex 的 config.toml 是两个不同问题：

• .agents/skills 负责 ReadAny Skill 的发现；
• config.toml 负责 ReadAny MCP Server 的连接。

不应因为其中一项正常，就把另一项也判断为已经配置成功。