Codex全局Skills设计从项目内规则到跨目录高优先级触发
jerry2 CTO
  2026-05-25 22:15:59 2026-05-25 22:15    1.6k 字  5 分钟  

这次记录的是一次很典型的 Codex Skills 设计调整：一开始规则只放在某个项目里，换到其他目录后就不稳定；后来又发现如果什么都塞进全局 SKILL.md，文件会越来越大。最终比较舒服的方案是：全局只放轻量触发器，具体细则按需放到 references/，真正复杂的流程继续留在项目内 skill 里。

这篇不是讲某个 API，而是整理一次“怎么设计长期可维护的 Codex 技能”的过程。

背景：项目内 skill 换目录后不稳定

最开始，博客项目里有一个谨慎编码规则：

1
/Users/diruipu/jerry2/blogs/diruipu/skills/cautious-coding-guardrails/SKILL.md

它的作用是约束编码行为：

  • 不要瞎猜，先澄清
  • 简单优先，不要过度设计
  • 精准改动，不要顺手重构
  • 明确成功标准，验证后再结束

这些规则在 blogs 项目里很好用，但问题是：如果当前工作目录换成别的项目，比如微信小程序项目 wechat-web，项目内 skill 就不一定会被新对话自动读取。

这就导致一个尴尬的问题：明明是一条全局工作习惯，却被放在了某个项目里。

问题一：不能每次靠人工提醒

如果每次新对话都要手动说一遍：

1
使用 blogs 里的 cautious-coding-guardrails 技能

那这个技能其实没有真正变成工作习惯，只是变成了一段可复制的提示词。

同样的问题也出现在博客沉淀流程上。解决完 GitHub token、403、SSH、Hexo 部署这类问题后，如果每次都要人工提醒“把这个写成文章”，那知识沉淀就很容易断掉。

所以这里拆出了两个全局 skill：

1
2
/Users/diruipu/.codex/skills/cautious-coding-guardrails/SKILL.md
/Users/diruipu/.codex/skills/post-resolution-blog-capture/SKILL.md

前者约束编码行为，后者在解决完有复用价值的问题后主动提醒写博客。

问题二：全局 skill 不能越写越大

把规则放到全局以后，很容易出现另一个反方向的问题：什么都想塞进 SKILL.md。

例如：

  • GitHub token 怎么生成
  • SSH 认证怎么排查
  • Hexo 怎么构建
  • 文章怎么写 front matter
  • 哪些问题值得沉淀
  • 哪些问题不值得沉淀

这些如果全放在一个全局入口里，短期看很完整，长期看会变成一个巨大的“总提示词”。

这样会带来几个问题：

  • 入口文件太长，每次触发都会占用更多上下文
  • 不同职责混在一起，后续维护容易冲突
  • 具体经验和长期规则混在一起，越改越乱
  • 想复用某一部分能力时，很难判断该读哪段

所以全局 skill 的设计原则应该是：入口要轻，细节按需读。

最终结构：轻入口 + references + 项目内重流程

最终采用了三层结构。

第一层是全局轻入口：

1
/Users/diruipu/.codex/skills/cautious-coding-guardrails/SKILL.md

这个文件只保留高优先级触发说明和四条摘要：

1
2
3
4
1. Think before coding
2. Simplicity first
3. Surgical changes
4. Goal-driven execution

它的作用不是塞满所有细节，而是让新对话在任意项目目录下，都能知道：只要涉及编码、文件修改、Git、构建、部署、调试或项目维护，就应该先应用这套规矩。

第二层是按需细则：

1
/Users/diruipu/.codex/skills/cautious-coding-guardrails/references/guardrails.md

当任务有歧义、要扩大改动、要重构、要删代码，或者验证策略不清楚时，再读取这个细则文件。

这样既保留了完整规则，又避免每次都把细节灌进上下文。

第三层是项目内重流程：

1
/Users/diruipu/jerry2/blogs/diruipu/skills/hexo-blog-publisher/SKILL.md

真正写博客、生成 Hexo front matter、构建、预览、等待确认、提交、部署，这些都属于博客项目的重流程，不应该放到全局 skill 里。

全局的 post-resolution-blog-capture 只负责提醒：

1
这个问题值得沉淀成博客，要不要写进 blogs？

用户确认后，才切到 blogs 项目读取 hexo-blog-publisher。

关键经验：什么该进 skill，什么该写成文章

这次调整后，我觉得可以用一个简单标准判断：

长期行为规则进 skill，具体踩坑经验写文章。

适合进全局 skill 的内容：

  • 每次编码都应该遵守的习惯
  • 任意项目都适用的行为边界
  • 高优先级、低变化的原则
  • 用来决定是否读取更详细规则的入口

适合进项目 skill 的内容：

  • 某个项目的目录结构
  • 某个项目的构建和发布流程
  • 某个项目的资源放置习惯
  • 需要和项目配置保持一致的步骤

适合写成博客的内容：

  • 某次 GitHub token 报错怎么排查
  • 403 是权限问题还是仓库问题
  • Hexo 部署为什么源仓库和 Pages 仓库要分开
  • Codex skill 为什么要做成轻入口和 references

不适合写进 skill 的内容：

  • 单次问题的完整流水账
  • 临时命令
  • 已经过期的排查细节
  • 只对某次上下文有效的结论

一个可复用的目录设计

最终，一个比较舒服的全局 skill 结构大概是这样：

1
2
3
4
5
6
~/.codex/skills/cautious-coding-guardrails/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── references/
    └── guardrails.md

SKILL.md 负责回答三个问题：

  • 什么时候触发？
  • 核心原则是什么？
  • 什么时候读 references？

references/guardrails.md 负责放完整细则。

这个结构的好处是：入口始终短，细则仍然完整，未来要扩展也有地方放，不会把主文件撑爆。

结论

这次真正解决的不是“怎么写一个 skill”，而是“怎么避免 skill 变成另一个越来越大的提示词”。

我的结论是：

  • 全局 skill 适合放高优先级、跨项目、长期稳定的行为规则
  • 项目内 skill 适合放项目流程和本地约定
  • references 适合放按需读取的细节
  • 具体踩坑经验应该沉淀成文章，而不是继续塞进 skill

这样设计后，新对话在其他目录下也能获得关键行为约束，同时不会让每个全局 SKILL.md 越来越大。

 评论