Codex 里的 ~/.codex/skills 和项目/.codex/skills 有什么区别

很多人整理 Codex skills 时，最容易卡住的问题就两个：

~/.codex/skills 和 项目/.codex/skills 有什么区别
为什么 skill 明明在目录里，当前会话里却不一定显示

这篇就直接说结论。

两者的区别

先记最短版本：

~/.codex/skills 是你的全局技能库
项目/.codex/skills 是这个仓库的本地技能库

`~/.codex/skills`

适合放：

你自己跨项目反复会用的 skill
跟具体仓库无关的通用流程
很明显属于你个人习惯的工作流

比如：

post-rewrite
post-translate
git-commit-push
hugo-rsync-deploy
bilibili-speech-transcriber

这类 skill 的特点就是：离开当前项目也还能用。

`项目/.codex/skills`

适合放：

只对这个仓库成立的流程
跟当前项目目录结构、脚本、模板绑定很深的规则
需要让团队一起共享的 skill

比如：

这个仓库特有的发布流程
只能在这个项目里用的生成模板
跟项目私有脚本强绑定的自动化步骤

这类 skill 的特点是：离开这个仓库就没意义。

什么时候放全局，什么时候放项目里

直接这样判断就够了：

跟你个人习惯有关，放 ~/.codex/skills
跟仓库规则有关，放 项目/.codex/skills
能跨项目复用，优先放全局
要多人共享、跟仓库一起演进，优先放项目里

当前这个仓库是什么情况

按我现在看到的实际状态：

你的本机里有 ~/.codex/skills
当前仓库里没有 .codex/skills

所以你现在主要依赖的是全局 skills。
也就是说，像 post-rewrite、post-translate、git-commit-push 这些流程，现在更多是你个人工作流的一部分，不是这个仓库显式自带的一部分。

为什么磁盘里有，当前会话里却不一定显示

这里要分清两件事：

磁盘存在：说明 skill 文件在本地目录里
会话暴露：说明当前会话把它注册进了可用 skill 列表

这两者不是一回事。

所以会出现这种情况：

~/.codex/skills 里已经有 skill
但 / 后面的列表里没有显示

这通常不代表 skill 坏了，更常见的原因是：当前会话没有把它重新索引进去。

怎样让 skill 被当前会话暴露

最实用的步骤就这几条：

1. 目录放对

全局：

1

~/.codex/skills/<skill-name>/SKILL.md

项目级：

1

项目/.codex/skills/<skill-name>/SKILL.md

2. `SKILL.md` 头部可识别

最少要有：

1
2
3
4


---
name: your-skill-name
description: 这个 skill 是干什么的
---

3. 新建或修改后，开新会话

很多时候 skill 没显示，不是文件有问题，而是当前会话启动时就已经把可用 skill 列表定下来了。
所以你中途新建 skill，磁盘里虽然已经有了，这次会话也未必会重新认。

最稳的做法就是：

放好 skill
结束当前会话
重新进入项目
开一个新会话
再看 / 里有没有出现

4. 项目 skill 最好提前放好

如果你想让 项目/.codex/skills 更稳定地被识别，最好在进入仓库、启动会话之前，就把这些 skill 放进项目里。

最后一句

最短结论就是：

~/.codex/skills 是你的个人技能库
项目/.codex/skills 是仓库的本地规则库
skill 在目录里，不等于当前会话一定会显示
想让它显示，最常见的办法就是放对目录、写好 SKILL.md，然后开新会话