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，然後開新會話