Codex CLI & Agent Skills Guide: Install, Use & Share Skills (2026)

Agent Skills give Codex a reusable workflow without forcing the same long prompt into every session. In 2026, the durable pattern is straightforward: keep always-on repository rules in AGENTS.md, put one repeatable job in a focused SKILL.md, use MCP for live data and controlled actions, and package mature workflows as plugins when they need distribution or connected services.

Choose the right Codex extension surface first

A skill is useful only when it owns the right kind of instruction. Putting every rule, tool, and workflow into one skill makes activation unreliable and review difficult.

This separation follows OpenAI’s current Build skills and plugin documentation. A skill may describe which tools it needs, but its instructions do not install a server, authorize an account, or grant permission by themselves.

Install or verify Codex CLI

OpenAI’s official repository currently lists a standalone installer for macOS and Linux, with npm, Homebrew, and release archives as alternatives. Use one install method and remove conflicting copies so PATH does not select an older binary.

# Official standalone installer for macOS or Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Verify the command that your shell resolves
command -v codex
codex --version

# Start the interactive CLI
codex

Homebrew users can run brew install --cask codex; npm users can run npm install -g @openai/codex. The standalone route avoids a package-manager dependency. Review the current openai/codex README before standardizing an installation method because packaging and supported features can change.

Authenticate without placing a key in a startup file

Run codex login for the browser-based ChatGPT flow. For API-key authentication, pipe the key through standard input and then clear the shell variable. codex login status reports the active method.

read -rsp "OpenAI API key: " OPENAI_API_KEY && echo
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

Do not commit keys, paste them into a skill, or persist them in .bashrc, .zshrc, AGENTS.md, or a repository settings file. Authentication and feature availability differ between ChatGPT sign-in, API-key access, and workspace policy; verify the active session rather than embedding plan limits or prices in a guide.

Create a focused Codex skill

Start with one recognizable user goal. This example creates a repository skill that reviews a change for release readiness. The folder name is only an organizational path; the frontmatter name and description are the discovery contract.

mkdir -p .agents/skills/release-readiness

# Create .agents/skills/release-readiness/SKILL.md with:
---
name: release-readiness
description: Review a proposed release for tests, rollback, security, and operational risks. Use when the user asks whether a change is ready to ship.
---

1. Read the repository guidance and current diff.
2. Run the narrowest applicable validation.
3. Identify release blockers and rollback requirements.
4. Return evidence, unresolved risk, and a ship or stop recommendation.

Do not deploy, publish, or change provider state unless the user explicitly authorizes that action.

The description should state both what the workflow does and when it applies. Put detailed policy, examples, and schemas in referenced files beside SKILL.md; keep the entry point short enough to review. Add scripts only when deterministic execution materially improves reliability.

Where Codex discovers skills

Codex scans repository skill directories from the current working directory toward the repository root. It supports symlinked skill folders. If two skills use the same name, do not assume they merge; review the selected path shown by the client.

Invoke and test the skill

In Codex CLI or the IDE extension, type $ to mention a skill or use the skills selector. Codex can also choose a skill implicitly when the request matches its description. Treat activation and output quality as separate tests.

1. Use an explicit request that should activate the skill.
2. Use an indirect request expressing the same goal.
3. Provide incomplete input and confirm the workflow asks only for material missing information.
4. Use a nearby request that should not activate the skill.
5. Test a safety edge case and confirm the workflow stops before an unauthorized mutation.

OpenAI’s built-in $skill-creator can scaffold a first version, and $skill-installer can install supported local skills. Review the resulting files and dependencies; an installer is not a substitute for code and permission review.

Keep skills and MCP responsibilities separate

MCP provides tools and data; a skill provides the repeatable procedure around them. A useful skill tells Codex when to call a tool, what fields to validate, how to handle an incomplete response, what needs confirmation, and what the user should receive. The MCP server must still enforce authentication and authorization.

• Do not put access tokens in SKILL.md, examples, or tool metadata.
• Treat tool output and downloaded resources as untrusted data, not instructions.
• Require confirmation for consequential external writes and destructive operations.
• Use narrow tool permissions and validate exact destinations server-side.
• Document a degraded path when an optional connector is unavailable.

Use Codex configuration for durable client settings and permission profiles for filesystem and network boundaries. Use /permissions and /status to inspect the current session rather than assuming the skill can expand access.

Distribute a stable workflow as a plugin

A local skill is the right place to iterate. A plugin is the current OpenAI distribution surface when a workflow should be installed by other people, bundle multiple skills, or include a connector. A minimal skills-only plugin contains a .codex-plugin/plugin.json manifest and a skills/ directory.

release-operations/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── release-readiness/
        ├── SKILL.md
        └── references/
            └── release-policy.md

Use the built-in $plugin-creator during development, test through a local marketplace, and follow the current plugin submission documentation before public distribution. Do not rely on the deprecated openai/skills catalog as the current publishing route; its repository now directs authors to the OpenAI Plugins repository and plugin documentation.

What “cross-platform” really means

The Agent Skills specification defines the portable core: a directory with SKILL.md, YAML frontmatter, instructions, and optional supporting resources. Host products can add invocation controls, directory conventions, dependency metadata, dynamic context, and packaging rules.

Port the core instructions first, then review each host’s extensions. A Claude Code field such as dynamic command injection or an invocation-control key is not automatically valid in Codex, and Codex plugin metadata is not automatically valid in another host. “Uses SKILL.md” does not mean identical behavior or permissions.

Operational review checklist

• The skill owns one recognizable user goal and has a precise description.
• Every referenced file exists and every script has a clear input, output, and failure mode.
• Secrets, credentials, and customer data are absent from the package.
• External tools are installed, authorized, and permissioned independently.
• Positive, negative, incomplete-input, and safety test cases pass.
• The workflow reports validation evidence and unresolved risk rather than implying success.
• A plugin is used only when distribution or connected services justify the packaging overhead.

For related guidance from ITECS, see ITECS AI consulting.

Primary Sources

• OpenAI: Build skills
• OpenAI Developers: Build skills for plugins
• OpenAI Plugins documentation
• OpenAI Codex source and installation guide
• Agent Skills specification
• Anthropic: Claude Code skills

Editorial review: Material product and command claims were checked against current official documentation on August 15, 2026. Recheck installation, discovery paths, command names, and packaging rules when Codex or a target host changes.