Skill prompt step 1 should instruct model to read SKILL.md fully before loading additional resources
The skill prompt generated by render_skills_section() in codex-rs/core-skills/src/render.rs tells the model to open SKILL.md and "read only enough to follow the workflow." In practice this makes the main workflow definition ambiguous because the model has to guess what counts as "enough" before it has finished reading the workflow it is supposed to follow.
The surrounding progressive-disclosure guidance (load only specific files from references/, prefer running scripts/ instead of retyping, reuse assets/ and templates) is well suited to secondary resources, not the primary workflow definition in SKILL.md.
Step 1 of the "How to use a skill" section should explicitly instruct the model to read SKILL.md fully before loading any additional resources. This keeps progressive disclosure focused on additional resources while removing ambiguity from the core skill workflow instructions.
Current wording (step 1):
After deciding to use a skill, open its SKILL.md. Read only enough to follow the workflow.
Suggested wording:
After deciding to use a skill, open and read itsSKILL.mdin full. This is the primary workflow definition. Then load additional resources (e.g.references/,scripts/,assets/) progressively as needed.
Update: Here is a proposed change to correct this https://github.com/openai/codex/commit/b46f632d725a1bed282837a8e75d880654840bf3
6 Comments
I took a quick pass at the suggested wording here, and it seems like the right fix to me.
I prepared a narrow patch that follows the direction described in the issue:
codex-rs/core-skills/src/render.rsso step 1 explicitly tells the model to readSKILL.mdin full before progressively loading secondary resourcescodex-rs/core-skills/src/render_tests.rsso this wording does not regressLocal validation:
just fmtcargo test -p codex-core-skillsBranch:
Compare:
I have not opened a PR because the repo accepts external code contributions by invitation only.
If this wording and scope look right to the team, I’d be happy to open an invited PR.
Yeah I also was unable to prepare a PR for this same reason :(
Thanks for looking. Are you just another contributor like myself?
Yes, just another external contributor. I don’t have PR access either, so I only prepared the branch/compare link in case the team wants to invite a PR.
Ahh yes. I should have included this in my initial issue https://github.com/openai/codex/commit/b46f632d725a1bed282837a8e75d880654840bf3
External runtime confirmation, in case it helps prioritize.
The "Read only enough" wording is still present in
main(codex-rs/core-skills/src/render.rs, lines 31 and 48) and unchanged betweenrust-v0.128.0andrust-v0.134.0— the only diff isplugin_id: None,for skill analytics.In a corpus of 71
~/.codex/sessions/*.jsonlfiles producing 143 sed reads onSKILL.md, gpt-5.5 lands onsed -n '1,220p'for 76% of reads and gpt-5.4 lands onsed -n '1,260p'for 71%. Same harness, same prompt — only the model changes, and the cap follows the model. Lines up with "the model has to guess what counts as 'enough'".Full data and control conditions (other harnesses; same model with the harness swapped via claudex; a probe skill that tells the agent to re-read past its own cap):
https://gist.github.com/haru0416-dev/4fd584e8616698cc1cc34c04b03f70ee
Confirmed fixed on
main.Commit
56554904ba(#27044, June 8, 2026) updates both skill-prompt variants incodex-rs/core-skills/src/render.rsso the main agent must read the selectedSKILL.mdcompletely, continue truncated or paginated reads through EOF, and treat progressive disclosure as applying to additional resources rather than partial reads of the primary workflow.The commit also adds regression coverage that rejects the old “Read only enough to follow the workflow” wording. I verified the current checkout at
a57b268d61withjust test -p codex-core-skillspassing.Closing this as completed. This is a prompt-level fix with regression coverage; it is not a separate runtime enforcement mechanism.