Codex Skills Explained: SKILL.md, Invocation, and Scope

A Codex Skill is not a switch that changes the model's reasoning depth. It packages instructions, references, and optional scripts or assets so a task-specific workflow can be reused.

Minimum structure

OpenAI's official Skills documentation defines a Skill as a directory with a required SKILL.md.

my-skill/
├── SKILL.md
├── scripts/       # optional
├── references/    # optional
└── assets/        # optional

The SKILL.md Front Matter requires at least name and description.

---
name: release-note-checker
description: Use when checking product release notes against primary sources.
---

Read the target sources and verify dates, product names, and availability.
Report unverified fields instead of guessing them.

Two invocation paths

1. Explicit: In Codex CLI or the IDE extension, use /skills or mention $skill-name in the prompt.
2. Implicit: Codex may select a Skill when the request matches its description.

For implicit selection, describe both the intended task and its boundary. “A useful Skill” does not provide a reliable trigger.

Discovery scope

The official documentation distinguishes repository .agents/skills locations, the user $HOME/.agents/skills location, administrator locations, and system-bundled Skills. Put team-specific workflows in the repository scope and cross-repository personal workflows in the user scope.

Do not confuse three controls

• Not a model setting: Selecting a Skill does not necessarily change the model or reasoning setting.
• Not a permission grant: Filesystem and network boundaries come from sandbox and approval configuration.
• Not a correctness guarantee: An inaccurate workflow can still produce an inaccurate result; review outputs and tests.

Verify after use

Do not stop at seeing the Skill name. Confirm that required references were read, required checks ran, and the output matches the requested format. For a Skill with scripts, inspect the execution target and write scope.

Conclusion

A Skill is a reusable workflow package, not an intelligence switch. Define the purpose and limits in SKILL.md, invoke it explicitly or through a clear description, and verify that its steps were actually followed.