OpenAI Codex uses the open Agent Skills format across the ChatGPT desktop app, Codex CLI, and the IDE extension. A standalone skill is a directory with SKILL.md plus optional scripts, references, and assets. Codex advertises the name and description first, then reads the full instructions when the skill is selected.
Place a skill where its work lives
For repository work, Codex scans .agents/skills from the current working directory up toward the repository root. A team can keep a shared skill at the root or put a narrower one beside a service or module. Personal skills live under ~/.agents/skills. Admin and system locations support managed or bundled behavior.
This scope model is useful when two workflows share a name but apply to different parts of a monorepo. Codex lists the skill paths rather than silently merging them. Give each description enough context for the agent to select the right one.
Write for progressive disclosure
Codex budgets the initial list of skill names and descriptions so a large library does not crowd out the task. Long descriptions may be shortened. Put the job and trigger terms first, followed by the boundary. When the skill activates, Codex still reads the full SKILL.md, so detailed procedure belongs in the body or in linked resources.
---
name: api-contract-review
description: Review changed HTTP endpoints for request validation, stable errors, authentication, and backward compatibility. Use for API diffs and route changes.
---
Read the changed routes and their callers. Report contract breaks before style issues. Cite each finding to current code and include the request that triggers it.Invoke and inspect
Codex can activate a skill implicitly when the task matches its description. Users can also open /skills or type $ to mention one directly. The built-in $skill-creator helps draft a new package, and $skill-installer can add curated or repository-hosted skills for local use.
Use OpenAI-specific metadata only when needed
An optional agents/openai.yaml file can configure display details, invocation policy, and dependencies such as MCP tools. That file improves the ChatGPT and Codex experience but is not the portable core. Keep the workflow in SKILL.md and treat presentation or tool dependencies as an added layer.
Know the distribution boundary
Direct folders work well for local and repository authoring. OpenAI recommends plugins when a reusable product should bundle multiple skills, connectors, MCP configuration, or presentation assets. The skills.sh CLI is another cross-agent route for public Git repositories. Choose the channel based on what the package needs, not on the largest possible audience claim.
Test the result Codex receives
Test implicit matching, explicit invocation, missing input, and a nearby request that should not load the skill. Then inspect the artifact or code path a user receives. A green unit test does not prove a visual workflow, deployed endpoint, or packaged desktop application. Put the real acceptance action in the skill so future Codex sessions verify the same surface.