What a skill adds
A skill supplies task-specific instructions and supporting files. Codex can select it from its description, or you can mention it explicitly. Keep repository-wide instructions in AGENTS.md and use a skill for a repeatable task.
OpenAI skills documentationChoose a skill by the job
These entries link directly to OpenAI’s catalog. Read the current instructions and scripts; inclusion here is not a guarantee of successful execution.
Work through PR feedback
gh-address-comments
Finds comments on the current branch’s GitHub PR, summarizes them, and asks which to address before making the selected fixes.
Before use: GitHub CLI authentication and repository access.
Read the source →Investigate failing CI
gh-fix-ci
Inspects GitHub Actions checks and logs, explains the failure, then proposes a fix for approval. Other CI providers are outside its scope.
Before use: GitHub CLI authentication and readable Actions logs.
Read the source →Inspect a browser workflow
playwright
Uses Playwright CLI to navigate, fill forms, capture screenshots and debug UI flows. It does not promise a complete test suite.
Before use: Node.js/npm with npx; browser and wrapper setup described in the source.
Read the source →Install inside Codex, then check discovery
Use the bundled installer in an interactive Codex prompt. This is not a shell command:
$skill-installer gh-address-comments
Open /skills inside Codex CLI, then try $gh-address-comments on a repository you can access. If missing, restart Codex. The installer defaults to ~/.codex/skills via CODEX_HOME; that differs from the documented personal folder for manually authored skills.
Installer source and destination optionsWhere are Codex skills stored?
For a skill you write yourself, choose a project folder or your personal folder. Keep the complete skill directory, with SKILL.md immediately inside it.
| Use | Folder |
|---|
| This repository | .agents/skills/review-export-change/SKILL.md |
| Your projects | ~/.agents/skills/review-export-change/SKILL.md |
| Bundled installer | $CODEX_HOME/skills/gh-address-comments/SKILL.md Default CODEX_HOME: ~/.codex. Check the installer's reported destination. |
Inside a Git repository, Codex searches .agents/skills from the working directory up to the repository root. Identically named skills are not merged; check the path of the one you select.
Official local skill locationsWindows skill folder examples
In PowerShell, $HOME resolves to your user directory. These checks read paths without creating or moving files. Run the project check from your repository root:
# A manually written project skill
Test-Path '.agents\skills\review-export-change\SKILL.md'
# A manually written personal skill
Test-Path (Join-Path $HOME '.agents\skills\review-export-change\SKILL.md')
# A skill installed by the bundled installer
$skillHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
Test-Path (Join-Path $skillHome 'skills\gh-address-comments\SKILL.md')
A True result confirms the file exists, not that Codex loaded or ran it. Windows and WSL have separate home directories; check the environment where you run Codex. In File Explorer, show file extensions so you can spot an accidental SKILL.md.txt.
Installed, discovered, then verified
- Installed: confirm the destination and required YAML
name and description. - Discovered: open
/skills in Codex CLI or use its $ picker. Changes are detected automatically; restart if the skill remains missing. Check disabled [[skills.config]] entries in your config before reinstalling. - Verified: invoke one skill on a disposable example and inspect its output. Discovery does not prove permissions, dependencies or task success.
If a skill is visible but not selected automatically, make the description specific and try an explicit mention. For a large installed collection, check any warning about skills omitted from the initial context list.
Create a small SKILL.md
Create .agents/skills/review-export-change/SKILL.md in your repository, or ~/.agents/skills/review-export-change/SKILL.md for personal use. On Windows, ~ means your user home directory.
This original review-only template includes the required YAML name and description. Its body defines the task and output boundary.
---
name: review-export-change
description: Review a CSV export change for selected-row behavior and access-control regressions. Use when asked to review an export diff; do not use for unrelated changes.
---
1. Read the requested diff and the existing export behavior.
2. Check selected rows, empty selection, and permission boundaries.
3. Report concrete findings with file references and expected behavior.
4. State which checks were run and which remain unverified.
Do not edit files or claim a check passed without evidence.
Try a disposable example diff containing an empty-selection defect. The review should identify the defect and say what was checked. Try an unrelated request to see whether the description is too broad.
Agent Skills format specificationCodex skills vs Claude Code skills
| Detail | Codex CLI | Claude Code |
|---|
| Project folder | .agents/skills/ | .claude/skills/ |
| Manual personal folder | ~/.agents/skills/ | ~/.claude/skills/ |
| Explicit invocation | $skill-name | /skill-name |
| Automatic selection | Matches the description | Matches the description |
Both use SKILL.md with YAML metadata. Shared instructions may transfer, but paths, tools and host-specific settings need checking. This is a format comparison, not a model-quality ranking.
Claude Code skills documentationShould you put a Codex skill in a project folder or personal folder?
Put a skill in .agents/skills/<name>/SKILL.md when the workflow belongs to one repository and teammates should inherit the same steps through Git. Put it in ~/.agents/skills/<name>/SKILL.md when it is a personal helper you reuse across multiple repositories. Leave $CODEX_HOME/skills for packages managed by the bundled $skill-installer so manual edits and installer updates do not collide.
How do you fix a Codex skill that does not show up in /skills?
- Confirm the filename is exactly
SKILL.md (on Windows, verify File Explorer did not save SKILL.md.txt). - Check that the top YAML frontmatter includes valid
name and description fields between --- markers. - Verify the directory depth is
.agents/skills/<skill-name>/SKILL.md rather than nested inside an extra subfolder. - Inspect your config for disabled
[[skills.config]] entries, then restart Codex CLI and re-open /skills.
When should you use AGENTS.md instead of a Codex SKILL.md?
Use AGENTS.md for always-on repository rules that apply to every session, such as test commands, directory layout, and release guardrails. Use a SKILL.md file for repeatable, on-demand tasks (for example PR comment triage, release preflight, or browser checks) that should only load when the task matches its description or when you explicitly invoke $skill-name.
Installation and discovery questions
What are Codex skills?
Reusable instructions in SKILL.md, with optional scripts and references. They describe a workflow; they do not grant accounts, permissions or tools by themselves.
Where do I put a custom Codex skill?
Use .agents/skills/<name>/SKILL.md in a repository or ~/.agents/skills/<name>/SKILL.md for a personal skill. The bundled installer has its own destination; inspect its output.
Where is the personal skills folder on Windows?
For a manually authored skill, use .agents/skills inside your user home directory. In PowerShell, Join-Path $HOME gets that home path. The bundled installer can use CODEX_HOME/skills instead; check the destination it reports.
Why is my skill not showing up?
Check the filename, YAML name and description, and repository location. Open /skills inside Codex CLI. If it remains absent, restart Codex and check again.
Does installation prove a skill works?
No. Discovery only confirms Codex can find it. Try one bounded task and inspect the actual output, permissions and verification evidence.
AE
AgentSkillsHub Editorial TeamAI Agent Infrastructure Reviewers
The AgentSkillsHub editorial team evaluates MCP servers, Claude skills, and AI agent integrations for security, reliability, and practical deployment readiness. Every listing undergoes permission audit, README analysis, and operational risk triage before publication.
- Reviewed 450+ MCP server repositories
- Developed security grading methodology (A-F)
- Published agent deployment safety guidelines
Updated: 2026-11-20github