The short answer
For repository skills, create .agents/skills/<name>/SKILL.md. Current Codex documentation uses ~/.agents/skills for user skills. Add name and description frontmatter, then verify the skill in the client's selector and run a small task. Check existing manager targets separately: older paths may differ from the current shared convention.
Where Codex looks for skills
Codex uses the Agent Skills format and discovers repository skills under .agents/skills/. Its current documentation describes discovery from the working directory up to the repository root. This makes it possible to keep a skill near the part of the codebase it serves.
User-level skills live under ~/.agents/skills/ in the current official documentation. Existing installations can also have legacy or client-managed locations. Skiller's Codex configuration includes ~/.codex/skills as a global target and reads the shared user directory. Treat that as a manager compatibility detail; follow the documentation for your installed Codex when choosing a new location.
| Scope | Location | Reason |
|---|---|---|
| Repository | .agents/skills/<name>/SKILL.md | Keep the procedure with its project |
| User | ~/.agents/skills/<name>/SKILL.md | Use it across local projects |
| Existing Skiller target | ~/.codex/skills/ | Inspect existing installations and verify client discovery |
Do not install into every directory at once. If two skills share a name, the current Codex documentation says they are not merged. Duplicate installations can make the selector and troubleshooting less clear.
Create a repository skill
From the repository root, create a skill directory. The command below uses a Unix-like shell; the same layout can be created in an editor on Windows.
mkdir -p .agents/skills/review-change
# Create .agents/skills/review-change/SKILL.md in your editor.Add a small procedure you can verify:
---
name: review-change
description: Review a local code diff for correctness and regressions. Use when asked to review uncommitted changes.
---
# Review a change
1. Read repository instructions and the local diff.
2. Trace changed behavior through relevant callers.
3. Inspect error handling and compatibility.
4. Report actionable findings with file locations.
5. State the checks performed and any remaining uncertainty.
Do not commit, push or deploy.The shared format requires a name and description in YAML frontmatter. A useful description explains when to load the skill, rather than making broad claims about its quality. Read how to write SKILL.md for a more complete authoring workflow.
Select the skill and test it
Open Codex in the repository. In supported Codex interfaces, use /skills to inspect available skills or type $ to mention one. Invocation details can differ across the CLI and other clients, so check the current Codex skills documentation for your interface.
Ask Codex to use the review skill against a small known change. Confirm that it loads the instructions and produces a result grounded in the diff. If it cannot run a check or read a required reference, that limitation should appear in the response.
Automatic selection is a separate test. Ask for the same workflow without mentioning the skill and observe whether the description gives Codex enough information to choose it. If discovery works but automatic selection does not, improve the description before adding duplicate installations.
Optional metadata and dependencies
Codex supports optional metadata in agents/openai.yaml, including interface details and invocation policy. It can also declare dependencies for a better client experience. A basic shared skill does not need this file.
Keep the core instructions portable when you also use Claude Code or Cursor. A Codex metadata file does not turn a client-specific command into a universal command. A skill that requires an MCP server still needs that server configured and authorized in the target client.
Before installing community content, inspect scripts and supporting files, identify the source version and make sure referenced tools are available. Copy the full skill directory so relative references continue to work.
Manage the library with Skiller
Skiller helps make the filesystem side visible: installed skills, their contents and the agents that consume them. You can edit a skill with Markdown preview and inspect its target paths before synchronizing copies.
For Codex, pay particular attention to the shared and existing global paths described above. Installing into a manager's configured location and observing the skill inside Codex are different checks. If your current Codex does not discover that target, use its documented shared directory and confirm the installation there.
Validate the client, not just the copy. Check the skill in Codex after every meaningful installation or path change. A file appearing on disk is useful evidence, but it does not establish discovery, selection or correct execution.
Troubleshoot discovery
- Wrong scope: make sure the repository skill is reachable from the working directory Codex uses.
- Wrong layout: keep
SKILL.mdinside a named directory under the skills root. - Invalid frontmatter: check the YAML and the shared name and description fields.
- Disabled skill: inspect any relevant
[[skills.config]]entry in your Codex configuration. - Stale session: restart the client when required after installation or configuration changes.
- Duplicate names: identify the actual file selected before editing or removing a copy.
Once one installation works, extend it deliberately. The multi-agent synchronization guide covers how to keep a source of truth while respecting different target paths.
FAQ
Where should Codex project skills live?
Codex project skills use .agents/skills/. Put each skill in its own directory with SKILL.md and confirm the discovery rules for your installed Codex version.
Does installing a skill make Codex use it automatically?
No. Discovery, selection and execution are separate checks. A clear description helps selection; explicitly invoke the skill for a small test before relying on automatic use.
Can I inspect and edit Codex skills in Skiller?
Yes. Use Skills Manager to inspect installed content, edit instructions and choose agent targets. Verify the result in Codex after synchronization.
Your skills. One place.
Inspect, edit and sync your skill library across coding agents.
Download Skiller
