Guides / Codex

Codex skills: find one, install it, verify the result.

A source-linked directory and file template for repeatable coding tasks. Start with your workflow, then check its prerequisites before installing.

Updated November 20, 2026 · Verify each skill on your own task.

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 documentation

Choose 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 options

Where 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.

UseFolder
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 locations

Windows 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

  1. Installed: confirm the destination and required YAML name and description.
  2. 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.
  3. 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.

SKILL.md
---
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 specification

Codex skills vs Claude Code skills

DetailCodex CLIClaude Code
Project folder.agents/skills/.claude/skills/
Manual personal folder~/.agents/skills/~/.claude/skills/
Explicit invocation$skill-name/skill-name
Automatic selectionMatches the descriptionMatches 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 documentation

Should 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?

  1. Confirm the filename is exactly SKILL.md (on Windows, verify File Explorer did not save SKILL.md.txt).
  2. Check that the top YAML frontmatter includes valid name and description fields between --- markers.
  3. Verify the directory depth is .agents/skills/<skill-name>/SKILL.md rather than nested inside an extra subfolder.
  4. 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