How to Install Skills in Codex CLI

OpenAI's Codex CLI doesn't natively support SKILL.md skills out of the box. The CLI expects you to paste prompts manually or feed them through stdin. But you can wire up skills with some creative file handling.

The cleanest approach involves creating a skills directory and symlinking or copying your SKILL.md files where Codex CLI can find them.

Setting up the skills directory

Create a dedicated folder structure:

mkdir -p ~/.codex/skills
cd ~/.codex/skills

Download skills from the marketplace or create your own following the SKILL.md spec. Each skill should be a single markdown file with the .md extension.

# Example: downloading a skill
curl -o python-refactor.md https://raw.githubusercontent.com/example/python-refactor-skill/main/SKILL.md

Codex CLI reads from files you specify, so you'll reference these paths directly in your commands.

Loading skills into Codex CLI

The CLI accepts file input through the -f flag or by piping content. Point it to your skill files:

codex -f ~/.codex/skills/python-refactor.md "Refactor this function to use list comprehensions"

This concatenates the skill content with your prompt. The skill's instructions become part of the context.

For multiple skills:

cat ~/.codex/skills/python-refactor.md ~/.codex/skills/code-review.md | codex "Review and refactor this Python code"

The order matters. Skills loaded first influence the entire conversation.

Converting from Claude Code skills

If you're migrating from Claude Code's skill system, the file formats translate directly. Claude Code uses CLAUDE.md files, but the content structure matches SKILL.md almost exactly.

Rename your .claude files to .md:

find ~/claude-skills -name "*.claude" -exec bash -c 'mv "$1" "${1%.claude}.md"' _ {} \;

Copy them to your Codex skills directory:

cp ~/claude-skills/*.md ~/.codex/skills/

Most skills transfer without modification. The instruction format and variable syntax work identically across both systems.

Automation with shell scripts

Create wrapper scripts to avoid typing full paths repeatedly. This script loads common skills automatically:

#!/bin/bash
# ~/.local/bin/codex-with-skills

SKILLS_DIR="$HOME/.codex/skills"
TEMP_FILE=$(mktemp)

# Combine selected skills
cat "$SKILLS_DIR/python-refactor.md" \
    "$SKILLS_DIR/code-review.md" \
    "$SKILLS_DIR/documentation.md" > "$TEMP_FILE"

# Run codex with combined skills
codex -f "$TEMP_FILE" "$@"

# Cleanup
rm "$TEMP_FILE"

Make it executable and use like any command:

chmod +x ~/.local/bin/codex-with-skills
codex-with-skills "Optimize this database query"

Configuration via environment variables

Set default skill paths through environment variables. Add to your shell profile:

export CODEX_SKILLS_DIR="$HOME/.codex/skills"
export CODEX_DEFAULT_SKILLS="python-refactor.md:code-review.md:documentation.md"

Reference these in scripts or aliases:

alias cxskill='codex -f $CODEX_SKILLS_DIR/$(echo $CODEX_DEFAULT_SKILLS | tr ":" "\n" | head -1)'

This approach keeps your skills organized and easily accessible.

Differences from MCP integration

Unlike MCP servers which provide live tool connections, skills in Codex CLI work as static prompt injection. The skills don't maintain state between calls or connect to external APIs during execution.

Skills vs MCP covers this distinction in detail, but the key difference affects how you structure complex workflows. Skills provide instructions and patterns. MCP servers provide active capabilities.

For Codex CLI, think of skills as sophisticated prompt templates rather than executable tools.

Managing skill collections

Organize skills by domain or project:

~/.codex/skills/
├── python/
│   ├── refactoring.md
│   ├── testing.md
│   └── optimization.md
├── web/
│   ├── accessibility.md
│   └── performance.md
└── general/
    ├── code-review.md
    └── documentation.md

Load entire categories when needed:

cat ~/.codex/skills/python/*.md | codex "Review this Python module"

This scales better than individual skill management as your collection grows.

Troubleshooting common issues

Codex CLI sometimes truncates long skill files. Keep skills under 4KB for reliable loading. Break complex skills into smaller, focused pieces.

File encoding issues can garble special characters. Save all skills as UTF-8:

file ~/.codex/skills/*.md
# Check encoding, convert if needed
iconv -f ISO-8859-1 -t UTF-8 problem-skill.md > fixed-skill.md

Path resolution varies between systems. Use absolute paths in scripts to avoid "file not found" errors.

The CLI doesn't validate skill syntax before loading. Test new skills with simple prompts first to catch formatting problems early.

Skills work best when they focus on single tasks or domains. Check the best practices guide for guidelines on writing effective skills that work well with Codex CLI's prompt-based approach.