Understand progressive disclosure

Understand the approach

Progressive disclosure separates finding a workflow from reading all of its details. Codex first receives skill metadata such as the name, description and location; it reads the full SKILL.md when the task calls for that skill. Supporting references can then be opened when needed. Think of a library catalogue, a book and an appendix: each has a different purpose. A catalogue entry must communicate relevance without requiring someone to read the whole book first.

This architecture creates two different failure modes. A good procedure with an unclear description may never be selected. A clear description can select a procedure whose body is incomplete or contradictory. Diagnose the correct layer before changing it. If readme-evidence-review is chosen for button styling, revise its trigger description. If it is chosen for a README but reports invented run commands, revise its instructions and evidence requirements. Adding more prose everywhere usually makes both problems harder to locate.

Arrange the practice skill around those layers. Keep the description focused on checking README readiness. Put the normal workflow and final response contract in SKILL.md. Put a longer reporting rubric or several worked examples in references, with explicit relative links from the main file. Do not move essential boundaries into an obscure appendix that the workflow never asks Codex to read. Supporting files are available context, not a guarantee that all of their contents are loaded or that scripts have executed.

Codex currently budgets its initial skill list separately from loaded instructions: the official guide states a default maximum of 2% of context, with an 8,000-character fallback when the window is unknown. Descriptions can be shortened and a large catalog can omit entries with a warning; this is not unlimited free context. For this package, metadata names README evidence review. A selected run reads SKILL.md, then references/rubric.md; it consults reference-outputs.md for calibration and runs scripts/review.cjs only when the deterministic check helps. Record the files actually read in a real client trace rather than treating a package tree as an observed loading trace.

Practice and acceptance

A package can keep its discovery entry short while explicitly linking the detailed material needed for the task.

Try it step by step

1. Read the linked lab guide, inputs and expected outputs before running the exercise.
2. Draft a short discovery description for readme-evidence-review that includes the task and a meaningful exclusion, such as no code changes.
3. Divide the proposed guidance into metadata, core instructions and optional references. Explain why each item belongs in its layer.
4. Create a scratch reporting rubric with sections for evidence, missing information and unverified commands. Link to it from the procedure rather than pasting it everywhere.
5. Test a direct request and a paraphrase in separate conversations. Inspect which instructions were actually read where the client exposes that evidence.
6. Change only the layer responsible for an observed failure, then rerun the affected request and one contrasting request.

A useful starting example

Illustration · adapt before use.

---
name: readme-evidence-review
description: Check whether a project README gives newcomers usable setup and verification instructions. Do not use for code changes or visual styling.
---
Read the specified README and relevant project configuration.
Use references/rubric.md for the report structure.
Cite evidence. Mark instructions that exist but have not been tested.
Do not edit the project.

Metadata: name + description + discovered SKILL.md path
Selected procedure: skill/SKILL.md
Report rubric: skill/references/rubric.md
Optional calibration: skill/references/reference-outputs.md
Optional check: node skill/scripts/review.cjs fixtures/broken

Check your result

• The description can distinguish the target task from neighboring tasks without reading supporting files.
• SKILL.md links to any reference needed for the promised output.
• You identify activation errors separately from execution errors and preserve the essential task boundaries.
• Helper results, actual host activation and unexecuted application commands remain distinguishable.

Common mistakes

• Assuming every bundled file is read as soon as the skill is listed.
• Hiding mandatory constraints in a reference without a reason for the agent to open it.