读懂 Codex（4.12）：Skills 的发现、元数据注入和按需全文加载

Codex 初始 Prompt 通常只注入可用 Skill 的目录元数据，不把所有 SKILL.md 全文塞进上下文。目录告诉模型“名称、用途、入口在哪里以及何时必须读取”；命中具体任务后，Agent 再通过文件或资源接口加载完整说明。这是典型的两阶段上下文设计。

发现结果先被压成目录

Skill 发现器返回 snapshot/outcome，随后 build_available_skills 按模型上下文窗口计算元数据预算。渲染器生成 skill root 映射和逐项说明；模型支持时再附加“How to use skills”协议。

def render_skill_catalog(discovery, model_window):
    budget = skill_metadata_budget(model_window)
    catalog = select_and_render_metadata(discovery.skills, budget)
    if not catalog:
        return None
    return AvailableSkillsFragment(
        roots=catalog.root_aliases,
        entries=catalog.lines,
        include_usage=discovery.model_requests_usage_rules,
    )

AvailableSkillsInstructions 使用 developer 角色和专用 markers。若 Host Extension 已把 Skill catalog 作为 World State 提供，Core 不再重复注入本地版本。

命中后才加载全文

目录项描述触发条件和 SKILL.md locator。模型决定使用某 Skill 后，通过文件读取或资源读取拿到完整说明；正文引用的相关文件再按 Skill 协议逐步加载。这样未命中的 Skill 只消耗一行左右元数据。

async def activate_skill(skill_meta, resource_loader):
    instructions = await resource_loader.read(skill_meta.main_resource)
    if instructions.truncated:
        instructions += await resource_loader.read_remaining(skill_meta.main_resource)
    return ContextMessage.developer(instructions.text)

预算和失败行为

目录超预算时会裁剪元数据并生成 warning event；这与读取 Skill 全文失败不同。前者意味着某些能力未进入模型可见目录，后者意味着模型已选择能力但资源不可用，应向用户说明并继续采用可行后备方案。

测试需检查根别名渲染、usage instructions 开关、空目录省略、Host catalog 去重和预算警告。

源码与测试锚点

• codex-rs/core/src/skills.rs：发现结果到可用目录。
• codex-rs/core/src/context/available_skills_instructions.rs：角色、标记和渲染。
• codex-rs/core/src/session/mod.rs：初始注入及 Host 去重。
• codex-rs/core-skills：元数据预算和目录格式。