Codex Skills 存储路径、软链接与升级指南

Codex CLI 的 skills 存储路径有两个层级，理解这两个位置的区别，是高效使用 skills 的前提。

两个存储路径

用户全局路径（对所有项目生效）：

~/.codex/skills/**/SKILL.md

项目级路径（仅对当前仓库生效）：

.agents/skills/**/SKILL.md

项目级路径的工作方式是：Codex 从当前工作目录向上扫描到仓库根目录，逐层查找 .agents/skills 目录。如果两个 skill 同名，两个都会出现在 skill 选择器中，不会合并。

手动创建 skill 的目录结构很简单：

text

~/.codex/skills/my-skill/
└── SKILL.md

SKILL.md 的基本格式：

yaml

---
name: skill-name
description: 说明何时应该触发此 skill。
---

具体的指令内容...

Codex 启动时会扫描 $CODEX_HOME/skills 目录来注册可用的能力。默认情况下 $CODEX_HOME 就是 ~/.codex，可以通过该环境变量自定义路径。

Codex 支持软链接的 skill 文件夹，扫描时会跟随软链接目标路径。

不过旧版本（v0.79.0 之前）有个 bug：软链接指向目录时会跟随，但 SKILL.md 本身是软链接时会被跳过，因为 loader 的 follow_symlinks 为 false。这个问题在新版本（0.86+）中已修复。

一个实用的场景是：把 Claude Code 和 Codex 的 skills 目录共享同一套文件：

bash

# 以 Claude Code 的 skills 目录为主，Codex 软链接过去
ln -s ~/.claude/skills ~/.codex/skills

根据安装方式不同，升级命令也不同。

内置命令（推荐，新版本支持）：

bash

codex update

独立安装包（macOS / Linux）：

bash

curl -fsSL https://openai.com/codex/install.sh | sh

npm 安装：

bash

npm install -g @openai/codex@latest

Homebrew 安装：

bash

brew upgrade --cask codex

注意要加 --cask，Codex 是 Homebrew cask 而非 formula，直接运行 brew upgrade codex 会报错。

版本检查：

bash

codex --version

Codex 在启动时如果检测到有新版本，会在 TUI 界面提示更新并显示对应的升级命令。