Terms in this guide: Evaluation · Prompt · Skill
Inspect a skill package, choose the correct project or personal scope, install it, and verify that Codex can discover it.
1. Download and inspect the package
Extract the ZIP into a temporary location and read SKILL.md before copying anything into a discovery directory. Confirm that the frontmatter name matches the folder, the description identifies a clear task, and the instructions do not claim access the skill will not have.
Review scripts with extra care. A skill can include executable helpers, but a download badge or valid folder structure does not establish their safety. Check the source, license, dependencies, network behavior, and files they may change.
2. Choose repository or personal scope
Put a project-specific skill in an .agents/skills directory inside the repository. Codex searches relevant repository locations from the working directory toward the repository root, so a skill can be scoped to a component or shared across the project.
Use the personal skills directory for a workflow that should be available across projects. Keep client and administrator locations separate from repository-owned packages so another contributor can understand what travels with the code.
3. Copy the complete folder
Keep the top-level folder intact. SKILL.md is required; references, assets, scripts, and agent metadata may be part of the procedure. Copying only the manifest can silently remove evidence, templates, or deterministic helpers the instructions expect.
your-project/
└── .agents/
└── skills/
└── example-skill/
├── SKILL.md
└── references/4. Start a session in the intended project
Open the repository or working directory where the skill should be available. In Codex CLI or the IDE extension, use the supported skill selector or mention the skill by name. In the desktop application, use the skills interface available to the project. If a new or changed skill does not appear, start a fresh session or restart the client.
Plugin installation is a different route. Plugins can distribute skills together with other capabilities and have their own supported interfaces. Follow the plugin directory workflow when the download is a plugin package rather than a standalone skill folder.
5. Run a small discovery check
Use a focused request that clearly matches the description. Observe whether Codex loads the procedure, asks only for material missing information, and produces the expected kind of result. Then try a nearby request that should not use the skill. This checks both discovery and scope.
Record the client, date, request, observed result, and any limitation. A successful discovery check is narrower than a complete workflow evaluation, but it gives you a reproducible installation result.
Continue with evaluation
Use the existing evaluation worksheet to test normal, ambiguous, and unsuitable cases. If the skill belongs to your team, keep its source under version control and review updates before replacing the installed version.
Primary source
OpenAI skill documentation. Source checked September 10, 2026.
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.