用途:该技能为创建有效的 Codex 技能提供指导,并帮助与 Codex CLI 现行约定保持一致,适用于需要编写、优化或整理 Codex 技能的用户。
技能机制:技能是模块化包,为 Codex 提供可复用工作流、领域知识和工具。Codex 有两种使用技能的方式:隐式调用,由 Codex 在用户请求匹配技能描述时自动选择;显式调用,用户提及 $skill-name,或在支持的客户端中使用 /skills 选择器。
保存位置与优先级:Codex 从以下位置按优先级从高到低加载技能:$CWD/.codex/skills;$CWD/../.codex/skills(在 git 仓库内时);$REPO_ROOT/.codex/skills(git 仓库根目录);$CODEX_HOME/skills(默认 ~/.codex/skills);/etc/codex/skills。高优先级技能会覆盖同名的低优先级技能,且 Codex 会忽略符号链接的技能目录。
结构:技能目录包含必需的 SKILL.md,以及可选的 scripts/、references/、assets/ 目录。SKILL.md 必须含 YAML frontmatter:name(非空、不超过 100 字符、单行);description(非空、不超过 500 字符、单行)。额外键会被忽略。
创建流程:明确触发条件,定义应激活该技能的具体用户表述,保持描述具体;规划可复用资源,决定哪些脚本、参考资料或资产能节省时间,确定性步骤优先用脚本;在有合法路径中创建技能文件夹;编写精简的 SKILL.md,使用祈使式指令,细节外链到 references;添加 references 或 scripts,长文档放入 references/,可复用代码放入 scripts/;重启 Codex 以加载技能,技能在启动时加载。
最佳实践:描述要明确以便正确触发;采用渐进披露,保持 SKILL.md 简短、把细节移入 references;避免描述重叠以防触发歧义;校验 frontmatter 长度和单行字段,以免启动时校验错误。相关资源:references/skill-creator-original.md 提供更深入的结构与渐进披露指导。