下面按“AGENTS.md 与 SKILL.md 怎么分工 → 如何创建 → 如何维护 → 如何有效使用”来讲。
1. 先分清：AGENTS.md 和 SKILL.md 不是一回事
在 Codex 里，AGENTS.md 更像项目级长期规则，例如：项目结构、构建命令、测试命令、代码风格、禁止事项、目录说明。Codex 启动时会读取这些指导文件，并按全局、项目、子目录层级合并；越靠近当前工作目录的指导越靠后出现，因而更容易覆盖前面的规则。官方文档还说明，AGENTS.md 默认读取大小上限是 32 KiB，可通过配置项调整。(OpenAI 开发者)
而 SKILL.md 更像一个可复用的“专项工作流”，适合封装某一类重复任务，例如：
- “Qt6/CMake 构建错误诊断”
- “模型发布包检查”
- “代码审查流程”
- “Vue + Three.js shader 调试流程”
- “SQLite 数据库迁移检查”
- “Python 特征提取脚本生成与验证”
官方文档说，一个 skill 是一个目录，里面必须有 SKILL.md，也可以附带 scripts/、references/、assets/ 等资源；Codex 只在决定使用某个 skill 时才读取完整的 SKILL.md，平时只把 skill 的名称、描述和路径放入上下文中，用这种“渐进披露”方式节省上下文。(OpenAI 开发者)
所以我的建议是：
AGENTS.md 放“这个仓库一直有效的规则”；SKILL.md 放“某类任务的固定操作流程”。
2. 推荐目录结构
在项目仓库内，建议这样放：
your-project/
├── AGENTS.md
├── .agents/
│ └── skills/
│ ├── qt6-cmake-diagnosis/
│ │ ├── SKILL.md
│ │ ├── references/
│ │ │ └── qt6-build-notes.md
│ │ └── scripts/
│ │ └── collect_build_info.sh
│ │
│ ├── model-release-check/
│ │ ├── SKILL.md
│ │ └── scripts/
│ │ └── validate_model_release.py
│ │
│ └── sqlite-migration-review/
│ └── SKILL.md
Codex 官方文档说明，仓库内 skill 通常放在 .agents/skills 中，Codex 会从当前工作目录向上扫描到仓库根目录；用户级 skill 可以放在 $HOME/.agents/skills，机器或容器级 skill 可以放在 /etc/codex/skills。(OpenAI 开发者)
使用原则：
- 项目专用 skill：放在仓库
.agents/skills/ - 个人长期复用 skill：放在
$HOME/.agents/skills/ - 团队/服务器/容器通用 skill：放在
/etc/codex/skills/ - 特别复杂、多人分发的 skill：后续可以考虑打包成 Codex plugin；官方文档也建议，可复用分发时优先考虑 plugin。(OpenAI 开发者)
3. SKILL.md 的最小可用模板
每个 SKILL.md 至少需要 name 和 description。官方给出的基础格式就是 YAML front matter 加正文说明。(OpenAI 开发者)
---
name: qt6-cmake-diagnosis
description: Diagnose and fix Qt6/CMake build errors in C++/Qt projects, especially missing Qt modules, wrong include paths, linker errors, and Linux/WSL/aarch64 dependency issues. Do not use for non-Qt projects.
---
# Purpose
Use this skill when the task is to diagnose, fix, or explain Qt6/CMake build failures.
# Inputs Codex should inspect
- CMakeLists.txt
- build logs
- compiler errors
- linker errors
- package names and OS version
- source files mentioned in the error
- AGENTS.md project rules
# Workflow
1. Identify the exact failing phase:
- dependency discovery
- compilation
- linking
- runtime dynamic library loading
- QML/module loading
2. Extract the first real error.
Do not focus on later cascading errors until the first root error is understood.
3. Check Qt module usage:
- Widgets
- Charts
- SerialPort
- Sql
- Quick/QML
- VirtualKeyboard
4. Check CMake configuration:
- find_package(Qt6 REQUIRED COMPONENTS ...)
- target_link_libraries(...)
- include usage
- AUTOMOC/AUTORCC/AUTOUIC settings
5. For Linux dependency problems, distinguish:
- development package missing
- runtime library missing
- QML module missing
- architecture mismatch
- distribution package unavailable
6. Propose the smallest safe patch first.
7. After patching, run the relevant build command.
# Output format
Return:
- Root cause
- Files changed
- Exact patch summary
- Commands run
- Remaining risks
- Next recommended check
# Constraints
- Do not rewrite unrelated project structure.
- Do not introduce new dependencies unless necessary.
- Prefer minimal, reviewable patches.
- Preserve existing CMake style unless it is clearly wrong.
4. description 很关键：它决定 Codex 会不会自动用这个 skill
Codex 可以通过两种方式启用 skill：一种是显式调用，比如在 CLI/IDE 里通过 /skills 或 $skill-name 指定；另一种是隐式调用，也就是 Codex 根据任务和 description 判断是否该用这个 skill。官方特别强调，隐式匹配依赖 description，所以描述要简洁、范围明确，并把关键触发词放前面。(OpenAI 开发者)
不好的 description：
description: Help with this project.
太泛，Codex 不知道什么时候用。
较好的 description：
description: Diagnose and fix Qt6/CMake build errors in C++/Qt projects, especially missing Qt modules, wrong include paths, linker errors, and Linux/WSL/aarch64 dependency issues. Do not use for Python-only or frontend-only projects.
更好，因为它说明了：
- 适用任务：Qt6/CMake 构建错误
- 典型触发词：Qt6、CMake、missing Qt modules、linker errors、WSL、aarch64
- 不适用场景：Python-only、frontend-only
5. 一个好的 SKILL.md 应包含哪些部分？
建议采用这个结构：
---
name: short-kebab-case-name
description: Clear trigger condition, core task, key keywords, and when not to use this skill.
---
# Purpose
这个 skill 解决什么问题。
# When to use
明确适用场景。
# When not to use
明确不适用场景。
# Inputs to inspect
Codex 应该优先读取哪些文件、日志、目录、配置。
# Workflow
按步骤描述操作流程。
# Validation
修改后必须运行哪些检查。
# Output format
最终回复应该包含哪些内容。
# Constraints
禁止事项、边界条件、安全要求。
# Common mistakes
常见误判、历史踩坑。
# References
需要时让 Codex 阅读 references/ 下的文档。
尤其建议加上 When not to use。很多人只写“什么时候用”，但不写“什么时候不用”，结果 Codex 可能在不相关任务里误触发 skill。
6. 什么时候该写 skill？什么时候不该写？
适合写成 skill 的任务有三个特征：
第一，重复出现。例如构建诊断、发布检查、代码审查、数据处理、模型训练验证。
第二，流程相对固定。比如“先看日志，再看 CMakeLists，再检查包名，再运行构建”。
第三，需要项目经验沉淀。例如在项目开发过程中踩过的坑，或者项目中的一致性要求。
不适合写成 skill 的内容：
- 一次性任务
- 临时偏好
- 太泛的规则
- 大段项目背景
- 敏感密钥、账号、token
- 可以放在 AGENTS.md 的长期项目规范
7. AGENTS.md 与 SKILL.md 的推荐配合方式
AGENTS.md 可以写：
# Project instructions
## Build
- Main build command: ./scripts/dev-run.sh
- Use CMake.
- Target runtime includes Ubuntu/Debian Linux and arm64 devices.
- Development may happen in WSL.
## Skills
Use the following skills when appropriate:
- $qt6-cmake-diagnosis for Qt6/CMake build failures.
- $model-release-check for checking model-release-* directories.
- $sqlite-migration-review for SQLite schema migration or data compatibility changes.
## General rules
- Prefer minimal patches.
- Do not change database schema without migration notes.
- After changing data analysis code, check Python/C++ consistency.
官方文档中也给过类似思路：复杂任务可以通过 AGENTS.md 指向额外的规划文档，例如 PLANS.md，让 Codex 在需要时按固定计划文件执行。(OpenAI 开发者)
也就是说：
AGENTS.md负责告诉 Codex：“这个项目有哪些长期规则，以及有哪些 skill 可用。”SKILL.md负责告诉 Codex：“遇到某类具体任务时，按什么流程做。”
8. 如何维护 SKILL.md？
建议把 skill 当成代码资产维护，而不是随便写的提示词。
版本化
在 SKILL.md 里加版本记录：
# Version
- v0.3, 2026-05-23: Added aarch64 Ubuntu package diagnosis.
- v0.2, 2026-05-10: Added QtCharts and QtSerialPort checks.
- v0.1, 2026-04-30: Initial version.
每次踩坑后补充
例如：
qt6-charts-dev在某些 Ubuntu/aarch64 源里找不到QtCharts does not name a typelibQt6Charts.so.6runtime missingQML module QtQuick.VirtualKeyboard missing- CMake cache path mismatch
这些都可以逐步加入对应 skill 的 Common mistakes 或 Known project issues。
保持 skill 单一职责
官方最佳实践明确建议：每个 skill 聚焦一个工作；除非需要确定性行为或外部工具，否则优先用指令而不是脚本；步骤要用祈使句，并明确输入输出；还要用测试 prompt 检查触发是否准确。(OpenAI 开发者)
所以不要写一个叫：
my-project-helper
然后什么都往里塞。
更好的拆分是：
qt6-cmake-diagnosis
sqlite-migration-review
model-release-check
butterworth-filter-implementation
threejs-shader-debug
大量确定性检查用 scripts/
如果流程里有“必须精确判断”的部分，建议放脚本，而不是只靠自然语言。
例如：
model-release-check/
├── SKILL.md
└── scripts/
└── validate_model_release.py
然后在 SKILL.md 里写：
# Deterministic checks
If scripts/validate_model_release.py exists, run:
python3 .agents/skills/model-release-check/scripts/validate_model_release.py <release_dir>
Use the script output as the primary source for pass/fail status.
这样 Codex 既有工作流，也有确定性工具。
9. 如何有效调用 skill？
可以显式调用：
使用 $qt6-cmake-diagnosis 分析这次 Qt6 编译错误，并给出最小修复补丁。
或者：
使用 $model-release-check 检查 model-release-A1-1000Hz-20260511-153045 目录，重点确认 feature-schema.json 与 C++ 推理代码是否一致。
或者：
使用 $sqlite-migration-review 审查这次数据库表结构变化，确认旧版本 brake.db 是否能平滑升级。
官方文档说明，在 CLI/IDE 里可以通过 /skills 或输入 $ 来提及 skill；如果没有显式调用，Codex 也可能根据 description 自动选择。(OpenAI 开发者)
10. 如何验证 skill 是否生效？
可以让 Codex 自查：
codex --ask-for-approval never "List available skills relevant to this repository and summarize when each should be used."
也可以在具体目录下测试：
codex --cd . "Use $qt6-cmake-diagnosis to inspect the current build configuration. Do not modify files yet."
官方文档也建议用类似方式验证指导文件是否被加载；如果指导内容看起来陈旧，可以重启 Codex，因为 Codex 会在每次运行或 TUI 会话开始时重建指令链。(OpenAI 开发者)
11. 可禁用某个 skill
如果某个 skill 临时不想用，不一定要删除。官方配置支持在 ~/.codex/config.toml 中禁用指定 skill：(OpenAI 开发者)
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
修改后重启 Codex。
12. 总结一句话
AGENTS.md 是 Codex 的“项目长期记忆和行为准则”；SKILL.md 是 Codex 的“可复用专项作业流程”。
可以这样使用：
AGENTS.md：告诉 Codex 这个项目是什么、怎么构建、怎么测试、有哪些禁忌。
SKILL.md：告诉 Codex 遇到某类任务时，按固定步骤做、看哪些文件、跑哪些命令、输出什么结果。
最重要的实践是：不要把 SKILL.md 写成大而全的项目说明，而要把它写成一个具体、可触发、可执行、可验证的工作流。