Codex CLI & Agent Skills Guide: Install, Usage & Cross-Platform Resources (2026)

A skill created for OpenAI's Codex can run unchanged inside Claude Code, Google Antigravity, Cursor, GitHub Copilot, and over thirty other agent platforms. That sentence would have been absurd twelve months ago. Today it describes a cross-platform open standard that is quietly reshaping how development teams extend, share, and govern their AI coding assistants.

Agent Skills are not plugins in the traditional sense. They carry no compiled binaries, no runtime dependencies, and no vendor lock-in. A skill is a folder containing a Markdown file and, optionally, some scripts. The agent reads the metadata at startup, loads the full instructions only when the task at hand matches the skill's description, and discards the context once the job is complete. This progressive disclosure architecture keeps context windows lean, reduces hallucination, and lets organizations codify institutional knowledge in a format that any compliant agent can consume.

This guide walks through the entire ecosystem, from installing Codex CLI and authoring your first skill to discovering community skill registries, running autonomous development loops with the Ralph Wiggum technique, and deploying skills across Claude Code and Google Antigravity. Whether you are an individual developer looking to accelerate repetitive workflows or an enterprise team evaluating agentic development platforms for production adoption, the information here will help you make informed decisions about where skills fit in your stack.

What Are Agent Skills and Why They Matter

The concept originated with Anthropic in late 2025 when Claude Code introduced a mechanism for packaging reusable instructions into modular directories. The idea was deliberately simple: instead of stuffing every conceivable instruction into a monolithic system prompt, break capabilities into discrete units that the agent can discover and load on demand. Within weeks, OpenAI adopted the same format for Codex CLI. By January 2026, Google had formally integrated the standard into Antigravity, and Vercel launched skills.sh as the ecosystem's first dedicated package manager and directory [Vercel].

A skill consists of a directory containing a required SKILL.md file with YAML frontmatter (specifying a name and description) followed by natural-language instructions. Optional subdirectories can include scripts for deterministic operations, reference documentation for long-form context, and asset templates. The agent parses only the frontmatter at startup, adding roughly 50 to 100 tokens per skill to the initial context. When a user's prompt matches a skill's description, the agent loads the full instructions and any supporting files. Once the task completes, that context is released [OpenAI Codex Skills Documentation].

This architecture solves a fundamental problem in agentic development. General-purpose models like GPT-5.2-Codex, Claude Opus, and Gemini 3 Pro are powerful reasoners, but they do not inherently understand your deployment pipeline, your database migration standards, or your team's code review conventions. Skills bridge that gap without fine-tuning, without API integrations, and without persistent infrastructure. They are, as one developer described it, the difference between an agent that writes code and an agent that writes your code.

Installing Codex CLI

Codex CLI is OpenAI's local coding agent, built in Rust and open-sourced on GitHub. It runs directly in the terminal, reads and modifies files in your working directory, executes shell commands, and integrates with the GPT-5.2-Codex model, which is currently the most advanced agentic coding model available from OpenAI. Codex CLI is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans [OpenAI].

Prerequisites

You need Node.js 18 or later installed on your system. Codex CLI is available on macOS and Linux, with experimental Windows support. If you are running Windows as your primary development environment, consider using WSL2 for the most stable experience.

Installation via npm

npm install -g @openai/codex

You can also install via Homebrew on macOS:

brew install openai-codex

Authentication

After installation, authenticate with your OpenAI account:

codex login

This opens a browser-based authentication flow. You can also authenticate using an API key stored in your environment if you prefer headless operation. For CI/CD environments, device-code authentication is available as a standalone fallback.

Verifying the Installation

Run Codex in interactive mode to confirm everything is working:

# Start interactive session
codex

# Or run a one-shot command
codex "List all TypeScript files in this project and summarize their purpose"

Codex CLI ships with regular updates. To upgrade to the latest version:

npm update -g @openai/codex

Understanding the SKILL.md Format

Every agent skill follows the same structural convention. At its core, a skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown instructions. Here is the anatomy of a well-structured skill:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable automation
│   └── migrate.sh
├── references/       # Optional: long-form documentation
│   └── api-schema.md
└── assets/           # Optional: templates, config files
    └── template.yaml

The SKILL.md file must include at minimum a name and description in its YAML frontmatter:

---
name: database-migration
description: "Run and validate database migrations using Prisma. 
  Trigger when the user mentions migrations, schema changes, 
  or database updates. Do NOT trigger for general SQL queries."
---

# Database Migration Skill

## When to Use
- User requests a database migration
- Schema changes need to be applied
- Migration history needs review

## Steps
1. Check current migration status with `npx prisma migrate status`
2. Generate migration from schema changes
3. Apply migration to development database
4. Validate migration with `npx prisma validate`
5. Run seed scripts if applicable

## Important
- Always create a backup before applying migrations to staging/production
- Review generated SQL before applying
- Update seed data if schema changes affect existing fixtures

The description field is critically important. It controls when the agent decides to invoke the skill. Write descriptions with clear scope and explicit boundaries about what should and should not trigger the skill. A vague description like "helps with databases" will fire on irrelevant prompts and pollute the agent's context window.

Installing Skills: Three Approaches

There are three primary methods for getting skills into your agent's environment, each suited to different workflows and team structures.

Method 1: Skills.sh CLI (Recommended)

The skills.sh CLI, maintained by Vercel, is the fastest path from discovery to installation. Launched on January 20, 2026, it has rapidly become the central hub for the agent skills ecosystem, with the top skills accumulating over 26,000 installs within weeks of launch. The CLI automatically detects which agents you have installed and routes skills to the correct directories [Vercel].

# Install a skill package from GitHub
npx skills add vercel-labs/agent-skills

# Install a specific skill from a multi-skill package
npx skills add vercel-labs/agent-skills --skill frontend-design

# Install to specific agents only
npx skills add vercel-labs/agent-skills -a claude-code -a codex

# List available skills in a repository before installing
npx skills add vercel-labs/agent-skills --list

# Search for skills by keyword
npx skills find "react testing"

# Check for updates on installed skills
npx skills check

# Update all installed skills
npx skills update

The CLI supports multiple source formats beyond GitHub shorthand. You can provide full GitHub URLs, GitLab URLs, direct paths to specific directories within a repository, or even local filesystem paths. This flexibility makes it straightforward to install skills from private repositories or internal registries.

Method 2: Manual Installation

For teams that need tighter control over what enters their agent environment, or for skills developed internally that should not be published to a public registry, manual installation is simple.

Create your skill directory in the appropriate location for your agent:

# For Codex CLI (user-level)
mkdir -p ~/.codex/skills/my-custom-skill

# For Codex CLI (project-level, committed to repo)
mkdir -p .agents/skills/my-custom-skill

# Create the SKILL.md file
cat > ~/.codex/skills/my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: "Description of when this skill should trigger"
---

# My Custom Skill
Instructions for the agent to follow...
EOF

Codex detects newly installed skills automatically. If a skill does not appear, restart Codex to force a rescan of skill directories.

Method 3: Codex Built-in Skill Installer

Codex ships with a built-in $skill-installer skill that can install skills from within an active session:

# Within a Codex session, invoke the installer
$skill-installer install the linear skill from the .experimental folder

# Or use the skill creator to build a new skill interactively
$skill-creator

The $skill-creator skill walks you through authoring a new skill by asking what the skill does, when it should trigger, and whether it should include scripts or remain instruction-only. This is the fastest way to bootstrap a skill without leaving your terminal.

Using Skills in Practice

Once installed, skills integrate into your workflow through two invocation patterns.

Implicit invocation happens automatically when your prompt matches a skill's description. If you have a "database-migration" skill installed and you type "apply the latest schema changes," Codex will recognize the match, load the skill's full instructions, and follow them. No special syntax required. This is the default behavior and the reason well-written skill descriptions are essential.

Explicit invocation uses a prefix to force a specific skill. In Codex CLI, type $skill-name or use the /skills command to browse installed skills. In Claude Code, skills are loaded by referencing the skill directory path. Explicit invocation is useful when multiple skills might match a prompt and you want to ensure the right one fires.

# Implicit - Codex selects the skill based on prompt matching
codex "Draft a contract using standard legal templates"

# Explicit - Force a specific skill in Codex
codex "$legal-templates Draft a non-disclosure agreement"

# One-shot with skill context
codex "Refactor this file using the clean-code skill"

For enterprise teams, the agents/openai.yaml configuration file provides additional control over skill behavior, including the ability to disable implicit invocation for sensitive skills that should only fire when explicitly requested, declare MCP tool dependencies, and customize the skill's display name and icon in the Codex app.

The Ralph Wiggum Loop: Autonomous Agent Execution

Named after the Simpsons character and created by Geoffrey Huntley, the Ralph Wiggum technique is a deceptively simple idea with significant implications for how teams deploy coding agents at scale. At its core, Ralph is a bash loop that repeatedly feeds an agent the same prompt, allowing it to iterate on a task until completion criteria are met. Each iteration, the agent sees its previous work in modified files and git history, enabling self-correction and incremental progress [Geoffrey Huntley].

The basic structure is almost trivially simple:

# The original Ralph Wiggum loop - 5 lines of bash
while :; do
  cat PROMPT.md | codex
done

But the philosophy behind it is what makes it powerful. Instead of carefully directing an agent through each step, you define success criteria upfront, create robust verification mechanisms (test suites, linters, build checks), and let the agent fail its way to a correct solution. Failures become data. Each iteration refines the approach based on what broke. The skill shifts from "directing the agent step by step" to "writing prompts that converge toward correct solutions."

The Official Claude Code Plugin

Anthropic has published an official Ralph Wiggum plugin for Claude Code that wraps the core pattern with safety controls and better ergonomics:

# Install the plugin from Anthropic's marketplace
/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-plugins-official

# Start an autonomous loop with completion criteria
/ralph-loop "Migrate all tests from Jest to Vitest. \
  Output DONE when all tests pass." \
  --max-iterations 50 \
  --completion-promise "DONE"

# Cancel an active loop
/cancel-ralph

The plugin implements Ralph using a Stop hook that intercepts Claude's exit attempts. When Claude thinks it is finished, the hook re-feeds the original prompt, and Claude sees its own modifications from the previous iteration. The loop continues until the completion promise is output or the iteration limit is reached.

Cross-Agent Ralph Implementations

The technique is not limited to Claude Code. Community implementations support multiple agents:

# Using Open Ralph Wiggum (supports Claude Code, Codex, OpenCode, Copilot)
npm install -g open-ralph-wiggum

# Run with Codex
ralph "Generate unit tests for all utility functions" \
  --agent codex \
  --max-iterations 10

# Run with Claude Code
ralph "Refactor the auth module and ensure tests pass" \
  --agent claude-code \
  --model claude-sonnet-4 \
  --max-iterations 15

Real-world results have been striking. Huntley himself ran a three-month continuous loop that produced a complete programming language. YC hackathon teams shipped six or more repositories overnight for approximately $297 in API costs. One developer used the technique to refactor integration tests, reducing runtime from four minutes to two seconds. The common thread across all successful deployments: well-defined tasks with automatic verification running for extended periods.

Cross-Platform Skill Compatibility

One of the most significant aspects of the Agent Skills standard is its cross-platform portability. A skill authored for Codex can typically run unchanged in Claude Code, Google Antigravity, Cursor, GitHub Copilot, and dozens of other platforms. The reason is architectural: skills are filesystem-based, not API-based. Any agent that can read a directory structure and parse Markdown can consume a skill.

The skill directory locations vary by platform, but the format is identical:

Claude Code Integration

Anthropic's Claude Code was the originator of the agent skills concept. Skills in Claude Code follow the same SKILL.md format and are documented in the official Claude Code skills documentation. Claude Code uses progressive disclosure identically to Codex: metadata is parsed at startup, full instructions load on demand, and the agent can execute bundled scripts when the task requires deterministic behavior.

Installing a skill from a GitHub repository into Claude Code using skills.sh is a single command:

# Install directly to Claude Code
npx skills add vercel-labs/agent-skills -a claude-code

# Install all skills from a repo to all detected agents
npx skills add vercel-labs/agent-skills --all

Google Antigravity Integration

Google Antigravity is Google's agent-first IDE, released in public preview in late 2025. Unlike conventional code editors with AI sidebars, Antigravity was designed from the ground up for autonomous agent workflows. Its "Manager Surface" allows developers to spawn, orchestrate, and observe multiple agents working asynchronously across different workspaces, powered by Gemini 3 Pro with support for Claude Sonnet and OpenAI models [Google Developers Blog].

Antigravity formally adopted the Agent Skills open standard in January 2026. Skills in Antigravity function identically to their Codex and Claude Code counterparts, with workspace-scoped skills in .agent/skills/ and global skills in ~/.gemini/antigravity/skills/. The platform treats skills as specialized training modules that bridge the gap between the generalist Gemini model and project-specific requirements.

Skill Registries and Community Resources

The agent skills ecosystem has grown rapidly, with several registries and curated lists emerging as primary discovery surfaces. Each serves a different audience and use case.

Skills.sh — The Primary Registry

Skills.sh is Vercel's official directory and leaderboard for agent skill packages. It serves as the central hub for discovering skills, with telemetry-based popularity rankings, category filtering, and one-command installation. The CLI has been used with over 40 different agent platforms including Codex, Claude Code, Antigravity, Cursor, GitHub Copilot, Goose, Kiro CLI, and Windsurf [Vercel].

The registry uses a three-tier search strategy for skill discovery: direct check against known repositories, priority directory scanning, and recursive fallback. It supports source types including GitHub shorthand, full GitHub and GitLab URLs, direct URLs, well-known endpoints, and local paths. A skill lock file tracks installed skills with GitHub tree SHAs for precise update detection.

# Discover skills interactively
npx skills find "security auditing"

# Install Vercel's official skill collection
npx skills add vercel-labs/agent-skills

# Install from a full GitHub URL
npx skills add https://github.com/vercel-labs/agent-skills

# Non-interactive CI/CD installation
npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y

Awesome Codex Skills (ComposioHQ)

The ComposioHQ awesome-codex-skills repository focuses on practical Codex skills for automating workflows. What distinguishes this collection is its emphasis on external integrations. While most skill repositories focus on code generation and review, ComposioHQ's skills connect Codex to over 1,000 external applications through the Composio platform, enabling actions like sending emails, creating Linear issues, posting to Slack, and managing Notion databases directly from a Codex session.

Notable skills in the collection include:

• create-plan: Drafts concise execution plans for coding tasks before implementation begins
• gh-address-comments: Automatically addresses review or issue comments on open GitHub pull requests
• gh-fix-ci: Inspects failing GitHub Actions checks, summarizes failures, and proposes fixes
• mcp-builder: Builds and evaluates MCP servers with best practices and an evaluation harness
• connect: Connects Codex to 1,000+ applications via Composio for real-world actions

# Clone and install ComposioHQ skills
git clone https://github.com/ComposioHQ/awesome-codex-skills.git
cd awesome-codex-skills/awesome-codex-skills

# Use the included Python installer
python skill-installer/scripts/install-skill-from-github.py \
  --repo ComposioHQ/awesome-codex-skills \
  --path meeting-notes-and-actions

Awesome Agent Skills (VoltAgent)

The VoltAgent awesome-agent-skills repository is the most comprehensive cross-compatible skills collection, featuring over 300 agent skills from official development teams and the community. With 6,900+ stars on GitHub, it has become the de facto community standard for discovering skills that work across Codex, Claude Code, Antigravity, Gemini CLI, Cursor, GitHub Copilot, and other platforms.

The repository is distinguished by its inclusion of official skills from major technology companies and open-source projects:

• Cloudflare: Skills for building AI agents on Cloudflare Workers, MCP servers with OAuth, and CLI commands reference
• Google Labs (Stitch): Design-to-code workflows, React components conversion, UI/UX prompt enhancement, and iterative design feedback loops
• Hugging Face: ML workflows including HF Hub CLI operations, dataset management, model evaluation, and inference API integration
• Sentry, Trail of Bits, Stripe, Expo: Domain-specific skills for error monitoring, security auditing, payment integration, and mobile development
• Community contributions: Test-driven development, systematic debugging, platform design rules (Apple HIG, Material Design 3, WCAG 2.2), and deep research automation

Awesome Agent Skills (Heilcheng)

The Heilcheng awesome-agent-skills repository takes a more educational approach, providing tutorials and capability packages alongside the skills themselves. It serves as a good starting point for teams that are new to the agent skills standard and want to understand not just what skills are available but how to build their own effectively. The repository includes step-by-step authoring guides, platform compatibility matrices, and security best practices for evaluating community-submitted skills.

Authoring Your Own Skills: A Practical Walkthrough

Building a custom skill is one of the highest-leverage activities an engineering team can invest in. A well-crafted skill codifies tribal knowledge that would otherwise live in scattered documentation, Slack threads, or individual developers' heads. Here is a structured approach to authoring skills that work reliably across platforms.

Step 1: Identify the Right Candidates

Not every workflow benefits from being packaged as a skill. The best candidates share three characteristics: they are performed repeatedly with minor variations, they follow a predictable sequence of steps, and they produce a verifiable outcome. Database migrations, code review checklists, deployment procedures, documentation generation, and CI/CD debugging are all strong candidates. Design decisions, UX critiques, and strategic planning are not, because they require judgment that resists standardization.

Step 2: Write the SKILL.md

Start with the description. This is the single most important line in your skill because it controls when the agent decides to invoke it. Be explicit about both positive triggers (when to use) and negative boundaries (when not to use).

---
name: security-review
description: "Perform a security-focused code review. Trigger when the 
  user mentions security review, vulnerability check, or audit. Also 
  trigger for PRs touching auth, encryption, or API key handling. Do NOT 
  trigger for general code reviews, style reviews, or performance reviews."
---

# Security Review Skill

## Checklist
1. Check for hardcoded secrets (API keys, tokens, passwords)
2. Validate input sanitization on all user-facing endpoints
3. Review authentication and authorization logic
4. Check for SQL injection, XSS, and CSRF vulnerabilities
5. Verify TLS configuration and certificate handling
6. Review dependency versions against known CVE databases
7. Check for proper error handling (no stack traces in responses)

## Output Format
Provide findings as a structured list with severity levels:
- CRITICAL: Immediate security risk
- HIGH: Significant vulnerability  
- MEDIUM: Best practice violation
- LOW: Informational finding

## Scripts
Run `scripts/scan.sh` for automated SAST before manual review.

Step 3: Add Scripts for Deterministic Operations

Instruction-only skills work well for guiding agent behavior, but when you need deterministic outcomes, such as running a specific linter configuration, executing a migration script, or formatting output in a precise structure, add scripts to the scripts/ directory. The agent will execute these scripts as part of the skill workflow rather than generating equivalent commands from scratch each time.

Step 4: Test Across Platforms

Install the skill in at least two different agents (for example, Codex and Claude Code) and test it with the same prompts. Pay attention to edge cases where the description might trigger incorrectly. Refine the description until the skill fires reliably on relevant prompts and stays dormant on irrelevant ones.

Enterprise Considerations

For organizations evaluating agent skills for production environments, several considerations go beyond individual developer productivity.

Version control and auditing. Skills are just files in directories. They belong in Git alongside your application code. This means every change to a skill is tracked, reviewable, and revertable. Teams should treat skill authoring with the same rigor as infrastructure-as-code: pull requests, code review, and CI validation before merging changes to shared skills.

Security boundaries. Skills that include scripts introduce execution risks. The cybersecurity posture of your development environment should account for the fact that a skill script runs with the same permissions as the agent. Sandboxed execution environments, restricted shell access, and skill provenance verification are essential guardrails for teams deploying skills at scale.

Standardization across teams. When multiple teams adopt agent skills, coordination becomes important. Establish naming conventions, description standards, and a shared internal skill registry. The skills.sh CLI supports private repositories, making it straightforward to build an internal skills marketplace that mirrors the public ecosystem's discovery and installation experience.

Compliance and governance. For organizations in regulated industries, skills can encode compliance requirements directly into agent workflows. A HIPAA compliance skill could ensure that every code change touching patient data follows required access controls. A CMMC compliance skill could enforce security standards for defense contractors. This transforms compliance from a checkpoint to a continuous, agent-enforced discipline.

Advanced: Codex as an MCP Server

Skills are not the only mechanism for extending Codex's capabilities. Codex CLI can run as a Model Context Protocol (MCP) server, exposing two tools, codex() to start a conversation and codex-reply() to continue one, that other MCP clients can invoke. This enables multi-agent architectures where a parent agent (built with the OpenAI Agents SDK, for example) orchestrates multiple Codex instances working on different aspects of a larger task.

# Start Codex as an MCP server
codex mcp-server

# Launch with the MCP Inspector for debugging
npx @modelcontextprotocol/inspector codex mcp-server

This capability extends the concept of skills into orchestrated workflows. A parent agent could invoke one Codex instance with a "security-review" skill and another with a "performance-optimization" skill, then synthesize both results into a unified pull request. The AI consulting implications for enterprise teams are significant, as this pattern enables scalable, parallelized code quality workflows that were previously impractical.

Skills vs. MCP vs. System Prompts: Choosing the Right Tool

Agent Skills occupy a specific niche in the broader landscape of agent extensibility. Understanding when to use skills versus other mechanisms helps teams make better architectural decisions.

Skills are best for ephemeral, task-specific workflows. They are serverless and file-based. When a skill is invoked, the agent reads the instructions, potentially executes a script, and releases the context. They require no persistent infrastructure and can be version-controlled alongside the code they operate on. Use skills for code review standards, deployment procedures, documentation generation, and project-specific conventions.

MCP (Model Context Protocol) is best for persistent connections to external systems. It involves a client-server architecture where the agent connects to a running server process that maintains authentication state and exposes a dynamic set of tools and resources. Use MCP for database connections, GitHub API access, Slack integration, and any workflow that requires maintaining state across multiple agent interactions.

System prompts are best for global behavioral rules that should always be active. They are loaded at startup and persist throughout the session. Use system prompts for coding style preferences, language conventions, and organizational policies that apply to every interaction, not just specific tasks.

The relationship between these mechanisms is complementary, not competitive. A security skill (methodology) might instruct the agent to use a Postgres MCP server (function) to run specific validation queries. System prompts set the baseline behavior; skills provide task-specific expertise; MCP provides tool access. The most effective development environments layer all three.

Sources

• OpenAI Codex Skills Documentation — Official reference for skill format, discovery, and configuration
• Skills.sh — Vercel's agent skills directory and CLI package manager
• Vercel Changelog: Introducing Skills — Launch announcement (January 20, 2026)
• Geoffrey Huntley: Ralph Wiggum — Original autonomous loop methodology and documentation
• Anthropic Claude Code Ralph Wiggum Plugin — Official plugin implementation
• Claude Code Skills Documentation — Anthropic's skills reference
• Google Antigravity — Google's agentic IDE with skills support
• ComposioHQ/awesome-codex-skills — Curated Codex skills with external integrations
• VoltAgent/awesome-agent-skills — 300+ cross-compatible agent skills from official teams
• Heilcheng/awesome-agent-skills — Tutorials and capability packages for agent skills
• Codex CLI Documentation — Installation, authentication, and CLI reference
• OpenAI: Introducing GPT-5.2-Codex — Latest agentic coding model details