Codex 源码解析 · 第 31 讲
Codex 源码解析系列 第 31 讲：Skills 技能系统 基于 OpenAI Codex 源码 · 2026-10-25 💡 本讲一句话： Codex 的"技能"就是一堆带 YAML frontmatter 的 Markdown。本讲跟着一个 SKILL.md 走完全链路：从 $CODEX_HOME/skills 被发现、frontmatter 被解析校验、按 token 预算裁进系统提示词，到模型读它干活、shell 命令里被"偷偷"识别为隐式调用——重点拆两个巧思：目录渲染的四级预算分配，和纯名字匹配的歧义拒绝策略。 一、技能是什么：一个结构体 + 一份 Markdown 先说结论：Codex 的技能（Skill）不是可执行插件，而是"指令包"——一个目录里放一份 SKILL.md （带 YAML frontmatter），可以附带 scripts/、references/、assets/。模型看到目录里的名字和描述后，自己决定要不要读全文再干活，这就是所谓的 progressive disclosure（渐进披露）。整个技能系统的核心数据结构只有 12 个字段： 📄 codex-rs/skills/src/model.rs (第 6-28 行) /// Metadata for one skill materialized on the host filesystem. // 注释：一个技能在宿主文件系统上的完整元数据 #[derive(Debug, Clone, PartialEq)] // derive 三件套：可调试、可克隆、可比——元数据要频繁传递和去重 pub struct SkillMetadata { // 每个 SKILL.md 对应一个实例，是技能系统的核心数据结构 pub name: String, // 技能名，来自 frontmatter，上限 64 字符 pub description: String, // 必填描述——模型靠它判断"该不该用这个技能" pub short_description: Option<String>, // 可选短描述：预算紧张时目录渲染优先用它 pub interface: Option<SkillInterface>, // UI 展示信息：图标、品牌色、默认 prompt pub dependencies: Option<SkillDependencies>, // 依赖声明（如 MCP server），注入前可触发安装询问 pub policy: Option<SkillPolicy>, // 策略开关：是否允许隐式调用、限定产品 /// Path to the SKILL.md file that declares this skill. // 注释：声明该技能的 SKILL.md 文件路径 pub path_to_skills_md: AbsolutePathBuf, // 技能身份 = SKILL.md 绝对路径，去重/匹配全靠它 pub scope: SkillScope, // user/repo/system/admin——决定目录排序与权限语义 pub plugin_id: Option<String>, // 归属插件 id，用于遥测归因；没有则记 unattributed pub remote_plugin_id: Option<String>, // 远端插件 id（marketplace 场景） } impl SkillMetadata { // 行为扩展：策略判断方法挂在这里 pub fn allows_implicit_invocation(&self) -> bool { // 问一句：这个技能允许被"隐式调用"吗？ self.policy // 先取策略（可能没声明） .as_ref() // Option 引用化，避免移动 .and_then(|policy| policy.allow_implicit_invocation) // 策略里再取开关——两层 Option 拍平 .unwrap_or(true) // 默认允许隐式调用——不声明就放行，显式 opt-out 才关闭 } } 为什么这样设计： 注意 path_to_s…
阅读全文：Codex 源码解析 第 31 讲