codex skill 的 description 必须精准定义触发条件：明确场景、对象、边界与约束，避免功能概括、操作细节或宽泛动词，确保 codex 能准确判断是否加载该技能。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
写 Codex Skill 的 description，是为了让 Codex 在任务匹配时准确判断“该不该触发这个技能”，而不是让人读着顺口——写得模糊、笼统或只讲功能，就会导致误触发或根本没被识别。
description 的核心作用
它不是介绍技能有多好用，而是告诉 Codex：“当用户说哪类话、提哪种需求、处在什么上下文里，你就该加载我。”
这个字段会被 Codex 首先扫描，决定是否加载整个 SKILL.md 文件。一旦描述不匹配，后续再详细的步骤也完全不会执行。
必须避开的三类错误写法
❌ 只写功能概括：“代码检查工具”“生成测试用例”“导出 Git 变更”——Codex 无法据此区分你和别的同类技能。
❌ 混入操作细节：“先运行 git diff，再检查 AGENTS.md，最后输出风险清单”——这些属于正文流程，不是 description 的职责。
❌ 使用宽泛动词：“帮助”“支持”“优化”“提升”——没有触发锚点，模型无法建立语义关联。
合格 description 的四个要素
✅ 触发场景明确：限定在什么动作、什么阶段、什么输入条件下激活。
✅ 主体对象清晰：说明针对的是哪类文件、哪类提交、哪类接口、哪类文档。
✅ 行为边界具体：指出“包含/不包含哪些内容”“基于哪个规范”“按谁的标准”。
✅ 风险或约束可感知：比如“不执行删除操作”“不修改生产配置”“仅分析未提交改动”——这是 Codex 判断安全边界的依据。
正确写法示例与解析
方法一：聚焦交付前动作 + 范围约束 + 安全前提
description: 在提交、发布或交付代码前，检查本次改动是否超出任务范围、是否符合当前仓库 AGENTS.md 规范、是否通过全部已定义测试，且不执行任何破坏性 Git 操作。
→ 这句里，“提交/发布/交付前”是时间锚点；“本次改动”绑定 git status 上下文；“超出任务范围”“符合 AGENTS.md”是判断依据；“不执行破坏性 Git 操作”是硬性安全护栏。Codex 能据此排除日常开发中的普通调试请求。
方法二：绑定输入特征 + 输出用途 + 触发关键词
description: 当用户提供 PR 描述或 commit message，并要求“按团队规范生成评审要点”时，自动提取变更影响模块、检查高频风险点（如支付/库存/权限）、输出带引用链接的 Review 清单。
→ “提供 PR 描述或 commit message”是输入信号；“要求按团队规范生成评审要点”是典型用户话术；“提取…检查…输出…”隐含结构化输出预期。这比单纯写“做代码评审”精准十倍。
方法三：否定式限定强化识别精度
description: 仅当用户明确提到“交付前检查”“preflight”“上线前核对”，且当前目录存在 .agents/skills/preflight-review/SKILL.md 时触发；不响应“帮我看看这段代码”“怎么测这个函数”等泛化请求。
→ 直接用关键词白名单 + 文件存在性校验 + 黑名单排除，把误触发概率压到最低。适用于团队内已有统一术语的场景。
检查清单：写完 description 后立刻验证
① 把这句话单独丢给 Codex：“我需要做交付前检查”，它能匹配上吗？
② 把这句话丢给 Codex：“帮我修复这个 bug”，它会错加载你的 skill 吗？
③ 【不要在 description 里写脚本路径、文件名或 YAML 键名】——Codex 不解析这些，写了反而干扰语义匹配。
④ 如果你的 skill 只在某类仓库中生效（如只用于 Spring Boot 项目），description 中必须体现“Spring Boot 项目”或“使用 JPA 的后端服务”，不能靠正文说明。
