Codex Skills 放在哪里：用户级、仓库级与加载失败排查

Codex Skills 的官方共享目录已经统一到 .agents/skills。旧文章把 ~/.codex/skills 和 项目/.codex/skills 当作标准路径，这会让新建的 Skill 放错位置，也混淆了个人配置目录和可共享技能目录。

最短结论是：个人跨项目复用放到 $HOME/.agents/skills，仓库规则放到仓库内的 .agents/skills。每个 Skill 都应有自己的目录和 SKILL.md。

四种加载作用域

Codex 会从当前工作目录向上扫描到仓库根目录，因此大型单体仓库可以在不同子目录放置更具体的 .agents/skills。仓库级 Skill 可以跟随 Git 版本管理；用户级 Skill 不应承载只有当前项目才成立的路径和命令。

某些旧版、本地插件或运行环境仍可能出现 .codex/skills，但它不应再作为新建共享 Skill 的默认写法。判断目录时以当前 Codex 官方文档和本次会话列出的可用 Skills 为准。

一个最小可加载的 Skill

目录结构：

1
2
3
4

.agents/
└── skills/
    └── verify-build/
        └── SKILL.md

SKILL.md 至少应从合法 YAML front matter 开始：

1
2
3
4
5
6
7
8

---
name: verify-build
description: Run the repository build and report reproducible failures.
---

# Verify build

Run the documented build command, preserve logs, and do not publish artifacts.

name 应稳定且具有辨识度，description 要说明什么时候使用。正文再写具体步骤、边界和验证方式。

文件存在却没有加载：按顺序检查

1. 检查实际路径

确认不是多套了一层目录，也不是把文件命名成 SKILL.md.txt：

1

Get-ChildItem -Force -Recurse .agents\skills

个人目录可检查：

1

Get-ChildItem -Force -Recurse (Join-Path $env:USERPROFILE '.agents\skills')

2. 检查 front matter 是否位于第一个字节

肉眼看到文件以 --- 开头仍不够。UTF-8 BOM 的三个字节 EF BB BF 可能位于 --- 前面，使严格解析器报告：

1

missing YAML frontmatter delimited by ---

用 PowerShell 查看前六个字节：

1
2
3

$path = '.agents\skills\verify-build\SKILL.md'
$bytes = [IO.File]::ReadAllBytes((Resolve-Path $path))
($bytes[0..([Math]::Min(5, $bytes.Length - 1))] | ForEach-Object { $_.ToString('X2') }) -join '-'

正常应以 2D-2D-2D 开头；若看到 EF-BB-BF-2D-2D-2D，可在备份后转成无 BOM UTF-8：

1
2
3
4

$resolved = (Resolve-Path $path).Path
$content = [IO.File]::ReadAllText($resolved, [Text.Encoding]::UTF8)
$utf8NoBom = [Text.UTF8Encoding]::new($false)
[IO.File]::WriteAllText($resolved, $content, $utf8NoBom)

3. 检查 YAML 和名称冲突

front matter 必须成对闭合，冒号后的复杂文本需要正确引用。不同作用域中存在同名 Skill 时，不要假设 Codex 会自动合并两份说明；给它们使用不同名称，或只保留真正需要的一份，再重新加载验证。

4. 新开会话验证

Skill 列表通常在会话启动时发现。新增或修改后如果当前线程没有变化，关闭并重新打开 Codex 会话，再检查可用 Skill 列表。不要在尚未确认路径、编码和 YAML 前就删除整个配置目录。

应该放用户级还是仓库级

• 任何项目都能使用、属于个人习惯：放用户级。
• 依赖当前仓库脚本、模板或发布规则：放仓库级。
• 需要团队共同评审和版本控制：放仓库级并提交到 Git。
• 需要组织强制提供：由管理员放到管理员级。

如果一个 Skill 中写满绝对路径和某个站点的私有约定，即使它能被用户级目录加载，也不代表它适合放在那里。作用域决定的是谁能发现它，内容边界决定的是它在哪里能够安全执行。

验收清单

1. 路径使用 .agents/skills/<name>/SKILL.md。
2. 文件第一个字节就是 ---，没有 UTF-8 BOM。
3. YAML front matter 可解析，至少包含稳定名称和清楚描述。
4. 没有与其他作用域中的 Skill 意外重名。
5. 新开会话后能在可用 Skills 中看到它，并能按描述触发。

参考资料

• Codex Skills 官方文档：https://developers.openai.com/codex/skills
• Agent Skills 规范：https://agentskills.io/