Skill prompt step 1 should instruct model to read SKILL.md fully before loading additional resources

[hannesrudolph]

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 its SKILL.md in full. This is the primary workflow definition. Then load additional resources (e.g. references/, scripts/, assets/) progressively as needed.

[cluedesc]

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:

• updates codex-rs/core-skills/src/render.rs so step 1 explicitly tells the model to read SKILL.md in full before progressively loading secondary resources
• adds a unit test in codex-rs/core-skills/src/render_tests.rs so this wording does not regress

Local validation:

• just fmt
• cargo test -p codex-core-skills

Branch:

• https://github.com/cluedesc/codex/tree/fix/skills-read-skill-md-first

Compare:

• main...cluedesc:codex:fix/skills-read-skill-md-first

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.

[hannesrudolph]

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:

• updates codex-rs/core-skills/src/render.rs so step 1 explicitly tells the model to read SKILL.md in full before progressively loading secondary resources
• adds a unit test in codex-rs/core-skills/src/render_tests.rs so this wording does not regress

Local validation:

• just fmt
• cargo test -p codex-core-skills

Branch:

• cluedesc/codex@fix/skills-read-skill-md-first

Compare:

• main...cluedesc:codex:fix/skills-read-skill-md-first

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?

[cluedesc]

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.