How to Configure Codex CLI Skills: Directory Layout, Agent Tool Calling, and Terminal Automation

To configure Codex CLI skills, organize modular skill packages inside ~/.codex/skills/<skill-name>/ or repository .codex/skills/, define progressive disclosure YAML frontmatter with a 1,024-character semantic description ceiling, and register callable shell or script tools. This directory layout keeps idle agent context under 50 tokens while providing deterministic terminal automation across your repositories.

What Are Codex CLI Skills and Where Are They Stored?

Codex CLI skills are self-contained directory packages containing a SKILL.md file and optional tool scripts that teach OpenAI's command-line agent how to perform specialized development workflows. Instead of re-typing multi-paragraph instructions or pasting monolithic markdown runbooks into every terminal session, a skill exposes structured procedures that OpenAI Codex CLI activates dynamically upon recognizing semantic trigger conditions.

OpenAI Codex CLI discovers custom skills from two canonical filesystem locations:

• Global User Skills (~/.codex/skills/): Installed in your user home directory, these skills are indexed across every terminal tab, interactive session, and repository on that machine. They are ideal for machine-wide developer habits, such as git commit styling, security auditing, and performance profiling.
• Repository Project Skills (.codex/skills/): Located at the root of a specific git repository, these skills apply exclusively when Codex CLI is launched within that project directory tree. They encode repo-specific workflows, such as Docker orchestration, database schema migrations, and localized test runners.

According to official OpenAI Developer Documentation: “Break complex tasks into simpler subtasks... Specify the steps required to complete a task, and provide examples of successful execution to guide model reasoning.” Codex CLI skills implement this fundamental principle at the filesystem level. Rather than polluting every prompt turn with 2,500 to 4,000 tokens of static instructions, Codex CLI parses only the skill's name and short description at startup, loading the full procedural body only when the developer requests that task.

Codex CLI Skill Directory Layout and File Hierarchy

The standard Codex CLI skill architecture requires an isolated directory for each capability containing a primary SKILL.md entrypoint, an optional tools/ folder for executable scripts, and reference schemas. Placing multiple skills into a single flat directory breaks discovery parsers and prevents the agent from isolating individual tool dependencies.

Below is the production filesystem layout for a robust Codex CLI setup containing both global and repository-scoped skills:

~/.codex/skills/
├── git-worktree-rebase/
│   ├── SKILL.md                       # Manifest: frontmatter + rebase instructions
│   └── tools/
│       └── audit-clean-worktree.sh    # Executable shell validation tool
└── pg-migration-verifier/
    ├── SKILL.md                       # Manifest: schema safety rubrics
    └── schemas/
        └── migration-rules.json       # Structural validation reference rules

my-project/ (Repository Root)
├── .codex/
│   └── skills/
│       └── docker-preview-env/
│           ├── SKILL.md               # Scoped container orchestration instructions
│           └── tools/
│               └── launch-containers.sh
├── AGENTS.md                          # Universal repository architecture runbook
└── src/

In this architecture, SKILL.md serves as the deterministic contract. The root of each skill folder must contain this exact file. When Codex CLI initializes in a repository, it merges the global skills found in ~/.codex/skills/ with the local project skills found in .codex/skills/. If a local skill shares the exact name of a global skill, the project-level skill takes precedence, ensuring that codebase-specific rubrics override generic defaults. For a broader comparison of how this compares to other agents, consult our guide on Codex skills architecture and prompt libraries.

How Do You Author YAML Frontmatter for Codex CLI Skills?

You author YAML frontmatter for Codex CLI skills by placing a YAML 1.2 block between triple-dash delimiters at the very top of SKILL.md, specifying the skill name, semantic description, invocation triggers, and allowed CLI tools. Codex CLI parses this metadata at startup to index the skill in memory, consuming only 35 to 50 tokens of context until the skill is activated.

The frontmatter block must strictly follow standard YAML conventions. Avoid enclosing multi-line descriptions in raw brackets, and ensure string fields do not contain unescaped colons. Below is a production-tested YAML frontmatter specification for a database migration skill:

---
name: pg-migration-verifier
version: 1.2.0
description: Audits PostgreSQL migration scripts for exclusive table locks, concurrent index creation, and reversible rollbacks. Triggers when checking migrations or preparing database schema deployments.
author: Data Platform Team
tools:
  - bash: ./tools/audit-clean-worktree.sh
  - psql: "psql -d test_db --dry-run"
parameters:
  migration_dir:
    type: string
    description: Relative path to the pending SQL migration files.
    default: "migrations/"
---

# PostgreSQL Migration Verifier

## Operational Context
You are a senior database reliability engineer. When reviewing or generating migration files, enforce zero-downtime deployment rubrics.

## Execution Procedure
1. Inspect pending migration SQL files in the target directory:
   - Identify all 'ALTER TABLE' statements.
   - Verify that all new columns are declared 'NULL' or possess instant-add metadata (PostgreSQL 11+).
2. Validate index operations:
   - Reject any 'CREATE INDEX' statement lacking the 'CONCURRENTLY' directive.
3. Validate constraint additions:
   - Ensure foreign keys and check constraints are added using 'NOT VALID' followed by a separate validation phase.
4. Run the local audit validation tool:
   - Execute: `./tools/audit-clean-worktree.sh` to verify that git worktrees are clean before running dry-run DDL statements.

## Verification Checklist
- [ ] No exclusive locks requested on high-volume tables
- [ ] Index creation runs concurrently
- [ ] Non-destructive rollback SQL file exists and was verified

OpenAI Codex CLI skills index metadata at startup, consuming only 35 to 50 tokens of idle context per skill until the full procedure is summoned. To maintain high semantic routing precision, keep the description attribute under 1,024 characters while explicitly stating both what the skill does and when it should trigger. Vague descriptions such as “helps with SQL” force the model to hallucinate triggers or inadvertently invoke the skill during unrelated tasks.

Configuring Agent Tool Calling and Shell Script Execution

Codex CLI skills execute automation by pairing instructional Markdown with declared executable tools, allowing the agent to invoke local shell commands, linters, and test runners safely. When a skill declares tools in its frontmatter, Codex CLI provides those tools to the underlying model as callable function endpoints during the terminal session.

To ensure that shell scripts execute reliably across developer workstations, follow three strict operational guidelines:

1. 1. Enforce POSIX Compatibility: Write helper scripts using standard POSIX shell syntax (#!/usr/bin/env sh or #!/usr/bin/env bash). Avoid Bashisms or Zsh-specific array syntax that fails in minimal Docker containers or remote CI runners. Reference the IEEE POSIX Shell Standard for portable shell constructs.
2. 2. Relative Script Paths: Always specify script paths relative to the skill folder (e.g., ./tools/audit.sh) rather than hardcoding user paths like /Users/dev/skills/.... Hardcoded paths guarantee execution failure on teammates' machines.
3. 3. Deterministic Exit Codes: Ensure helper scripts return clean exit codes (0 for success, non-zero for failure) and print structured JSON or readable error messages to stderr so Codex CLI can diagnose and retry failed tool steps.

Below is an example of a robust helper script (tools/audit-clean-worktree.sh) that verifies git state before allowing destructive operations:

#!/usr/bin/env bash
set -euo pipefail

# audit-clean-worktree.sh
# Verifies clean git status before Codex CLI executes schema changes

if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
    echo "ERROR: Current directory is not a git repository." >&2
    exit 1
fi

UNTRACKED_CHANGES=$(git status --porcelain)

if [ -n "$UNTRACKED_CHANGES" ]; then
    echo "WARN: Uncommitted changes detected in working tree:" >&2
    echo "$UNTRACKED_CHANGES" >&2
    echo "Stash or commit changes before executing database dry-run." >&2
    exit 2
fi

echo "STATUS: Working tree is clean. Proceeding with migration dry-run."
exit 0

Decision Table: Codex CLI Skills vs AGENTS.md vs MCP Server Tools

Selecting between Codex CLI skills, repository AGENTS.md files, and MCP tool endpoints depends on whether instructions are personal or shared, whether they require external tool calling, and how strictly you must budget model context tokens. Developers frequently misplace instructions by stuffing granular task workflows into root documentation files or building heavyweight MCP servers for simple text commands.

The comparison table below details the trade-offs across all three approaches:

To explore how universal repository standards coordinate with individual skills, read our in-depth analysis on AGENTS.md across Codex, Cursor, and Antigravity.

The Sprawl Moment: When Your Terminal Skills Vanish on Another Laptop

You spend Thursday afternoon configuring a high-leverage PostgreSQL migration and verification skill in ~/.codex/skills/pg-migration-verifier/ on your office desktop. You meticulously test the YAML frontmatter, calibrate tool permissions, and verify that Codex CLI flags destructive DDL queries before running them. On Saturday night while on-call, an urgent staging database incident requires your immediate attention. You open your personal MacBook, launch OpenAI Codex CLI in your terminal, and type /pg-migration-verifier to inspect the pending database patch. Codex responds: Unknown skill or command: pg-migration-verifier. The skill was trapped in your office desktop's local filesystem, never committed to a shared repository, and completely absent on your laptop. You spend forty minutes hunting through terminal history logs and guessing parameter schemas while the incident timer ticks.

How Do You Sync Codex CLI Skills Across Machines and Other AI Agents?

You sync Codex CLI skills across multiple machines and agent runtimes by maintaining a centralized, cloud-backed skill library that writes bidirectional changes directly to your local filesystem. Managing symlinks or manual Git submodules between machines introduces operating system path conflicts, whereas an automated skill manager synchronizes ~/.codex/skills/ alongside ~/.claude/skills/ and .cursor/rules/ without manual exports.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

With Prompttly, your terminal skills operate as an integrated system:

• Two-Way Filesystem Sync: Edits made in ~/.codex/skills/ are automatically captured and synchronized to the cloud, immediately populating the corresponding skill folder on your other laptops and cloud dev boxes.
• Sub-200ms Mac Hotkey Palette: Press a global keyboard shortcut anywhere on macOS to open your complete library and insert any prompt or skill into terminal sessions, browser windows, or code editors.
• Cross-Agent Schema Translation: Prompttly bridges the gap between agent runtimes by maintaining your core engineering skills in one place and syncing them as native folders into Claude Code, Codex CLI, Cursor rules, and Google Antigravity. For architectural patterns, see our guide on building a single cross-agent skill library.

When NOT to Use Prompttly (When Simple Local Dotfiles Suffice)

Prompttly is built for engineers and technical teams running multiple AI coding agents across multiple machines, but it is not necessary for every developer. If your workflow is strictly confined to a single machine and a single tool, simpler free options are more than adequate.

You do not need a paid skill manager if:

• Single-Machine Terminal Workflows: If you exclusively run OpenAI Codex CLI on one workstation and never switch between a personal laptop, work laptop, or remote dev container, keeping skills in ~/.codex/skills/ without cloud synchronization works fine.
• Under 5 Skills Total: If you rely on only two or three basic prompts that rarely change, keeping them in a simple text file or GitHub Gist is simpler than setting up an agent manager.
• Single-Agent Teams: If your entire engineering team has standardized 100% on Anthropic Claude Code and never touches OpenAI Codex, Cursor, or ChatGPT web, you can scaffold skills using our free Claude Skill Creator without paid tooling.

Automated POSIX Audit Script for Codex CLI Skills

To ensure your Codex CLI skills maintain valid frontmatter syntax and do not cause agent timeouts, run an automated validation script across your skills directory. Broken YAML frontmatter or unexecutable helper scripts cause Codex CLI to silently ignore custom skills during terminal startup.

Save the following POSIX bash script as audit-codex-skills.sh and execute it whenever you create or update skills:

#!/usr/bin/env bash
# audit-codex-skills.sh
# Validates Codex CLI skill packages in ~/.codex/skills or .codex/skills

set -euo pipefail

SKILLS_DIR="${1:-$HOME/.codex/skills}"

if [ ! -d "$SKILLS_DIR" ]; then
    echo "ERROR: Directory $SKILLS_DIR does not exist." >&2
    exit 1
fi

echo "Auditing Codex CLI skills in: $SKILLS_DIR"
ERRORS=0
WARNINGS=0

for SKILL_PATH in "$SKILLS_DIR"/*; do
    if [ ! -d "$SKILL_PATH" ]; then
        continue
    fi

    SKILL_NAME=$(basename "$SKILL_PATH")
    MANIFEST="$SKILL_PATH/SKILL.md"

    if [ ! -f "$MANIFEST" ]; then
        echo "❌ [$SKILL_NAME] Missing SKILL.md manifest!"
        ERRORS=$((ERRORS + 1))
        continue
    fi

    # Check for YAML frontmatter delimiter
    FIRST_LINE=$(head -n 1 "$MANIFEST")
    if [ "$FIRST_LINE" != "---" ]; then
        echo "❌ [$SKILL_NAME] SKILL.md does not start with '---' YAML delimiter."
        ERRORS=$((ERRORS + 1))
    fi

    # Verify name attribute exists
    if ! grep -q "^name:" "$MANIFEST"; then
        echo "❌ [$SKILL_NAME] Missing 'name:' field in frontmatter."
        ERRORS=$((ERRORS + 1))
    fi

    # Verify description attribute exists
    if ! grep -q "^description:" "$MANIFEST"; then
        echo "❌ [$SKILL_NAME] Missing 'description:' field in frontmatter."
        ERRORS=$((ERRORS + 1))
    else
        # Check description length (<1024 characters)
        DESC_LEN=$(grep "^description:" "$MANIFEST" | awk '{$1=""; print $0}' | wc -c)
        if [ "$DESC_LEN" -gt 1024 ]; then
            echo "⚠️  [$SKILL_NAME] Description is $DESC_LEN chars (exceeds recommended 1024 chars)."
            WARNINGS=$((WARNINGS + 1))
        fi
    fi

    # Verify tool script execution permissions
    if [ -d "$SKILL_PATH/tools" ]; then
        for TOOL in "$SKILL_PATH/tools"/*; do
            if [ -f "$TOOL" ] && [ ! -x "$TOOL" ]; then
                echo "⚠️  [$SKILL_NAME] Tool $TOOL is not executable. Run: chmod +x '$TOOL'"
                WARNINGS=$((WARNINGS + 1))
            fi
        done
    fi

    echo "✅ [$SKILL_NAME] Manifest verified."
done

echo "Audit completed with $ERRORS error(s) and $WARNINGS warning(s)."
if [ "$ERRORS" -gt 0 ]; then
    exit 1
fi
exit 0

This audit script guarantees that every skill folder contains a valid SKILL.md, checks that description strings remain under the 1,024-character token budget ceiling, and verifies that helper scripts have executable permissions.

Frequently Asked Questions About Codex CLI Skills

Next Steps: Streamline Your Terminal AI Agent Workflows

Configuring structured Codex CLI skills transforms your terminal assistant from a reactive chatbot into an autonomous engineering partner that executes complex, multi-step procedures with precision.

To learn more about bridging skills across your development stack, explore our comparisons between Codex Skills vs Claude Code Skills and our architectural guide on AGENTS.md across coding agents. To eliminate prompt loss and access your entire skill library with a single keystroke on macOS, download Prompttly for Mac or visit the Prompttly Resources Hub.