Codex CLI Guide - Impeccable

Overview

Codex CLI uses a hybrid approach: custom prompts for user-invokable commands and Agent Skills for reference documentation. Impeccable transforms its source format into Codex-compatible prompts with uppercase variable syntax and comprehensive skill files.

Codex CLI is OpenAI’s code-focused CLI tool. Skills and custom prompts are available in recent versions.

Installation

Install Codex CLI

npm install -g openai-codex

Download the bundle

Visit impeccable.style and download the Codex CLI bundle, or copy from the repository:

cp -r dist/codex/.codex/* ~/.codex/

Verify installation

In Codex CLI, type /prompts:audit - the command should be recognized.

Codex CLI installs globally (in ~/.codex/), not per-project. All projects share the same skills and prompts.

File Structure

Codex CLI uses a unique directory structure:

~/.codex/
└── skills/
    ├── audit/
    │   └── SKILL.md
    ├── normalize/
    │   └── SKILL.md
    └── frontend-design/
        ├── SKILL.md
        └── reference/
            ├── typography.md
            ├── color-and-contrast.md
            ├── spatial-design.md
            ├── motion-design.md
            ├── interaction-design.md
            ├── responsive-design.md
            └── ux-writing.md

Key Differences

Global installation: Everything lives in ~/.codex/ (not per-project)
Skills directory: Uses .codex/skills/ (not .codex/commands/)
Prompt prefix: Commands are invoked as /prompts:name (not just /name)

Skill Format

Codex CLI skills use YAML frontmatter with argument hints:

---
name: audit
description: Perform comprehensive audit of interface quality
argument-hint: [AREA=<value>]
---

Run systematic quality checks on $AREA. If AREA is not specified,
audit the entire interface...

How Arguments Work

Codex CLI uses uppercase variable syntax ($ARGNAME) instead of lowercase placeholders:

Argument Syntax

/prompts:audit

Variable Transformation

Codex transforms arguments into uppercase variables:

# Source (during build)
Audit the {{area}} for issues.

# Codex Output
Audit the $AREA for issues.

# User types: /prompts:audit AREA=checkout
# Codex receives: Audit the checkout for issues.

Argument Hints

The argument-hint field in frontmatter shows users the expected syntax:

# Optional argument
argument-hint: [AREA=<value>]

# Required argument  
argument-hint: <component>

# Multiple arguments
argument-hint: <component> [DEVICE=<value>]

Codex displays this hint when users type the command name.

Provider-Specific Transformations

The build system applies these transformations for Codex CLI:

1. Uppercase Variables

Argument placeholders become uppercase variables:

Audit {{area}} for quality issues.
Focus on {{aspect}} if specified.

2. Argument Hints

Codex generates argument hints from the args array:

# Source
args:
  - name: area
    required: false
  - name: aspect
    required: true

# Becomes
argument-hint: <aspect> [AREA=<value>]

Required arguments use <name>, optional use [NAME=<value>].

3. Skill Structure

Codex CLI uses the Agent Skills standard (same as Cursor and Claude Code) for skill files:

name: audit
description: Comprehensive quality checks
argument-hint: [AREA=<value>]
license: Apache 2.0

4. Reference Files

Reference files are copied into reference/ subdirectories, preserving the full content of domain-specific guides.

Usage Examples

Basic Command

/prompts:audit

Runs audit on entire interface.

With Argument

/prompts:audit AREA=checkout

Audits the checkout flow.

Multiple Arguments

/prompts:adapt header DEVICE=mobile

Adapts header component for mobile devices.

Complex Workflow

# Quality pass
/prompts:audit
/prompts:normalize  
/prompts:optimize
/prompts:polish

# Design refinement
/prompts:critique DESIGN=hero
/prompts:bolder SECTION=hero
/prompts:colorize COMPONENT=hero
/prompts:animate ELEMENT=hero

Available Skills

Impeccable includes 17 user-invokable prompts for Codex CLI:

Command	Arguments	Purpose
`/prompts:audit`	`[AREA=<value>]`	Technical quality checks (a11y, performance, responsive)
`/prompts:critique`	`[DESIGN=<value>]`	UX design review (hierarchy, clarity, emotional resonance)
`/prompts:normalize`	`[SCOPE=<value>]`	Align with design system standards
`/prompts:polish`	`[COMPONENT=<value>]`	Final pass before shipping
`/prompts:distill`	`[FEATURE=<value>]`	Strip to essence
`/prompts:clarify`	`[COPY=<value>]`	Improve unclear UX copy
`/prompts:optimize`	`[TARGET=<value>]`	Performance improvements
`/prompts:harden`	`[FLOW=<value>]`	Error handling, i18n, edge cases
`/prompts:animate`	`[ELEMENT=<value>]`	Add purposeful motion
`/prompts:colorize`	`[COMPONENT=<value>]`	Introduce strategic color
`/prompts:bolder`	`[SECTION=<value>]`	Amplify boring designs
`/prompts:quieter`	`[SECTION=<value>]`	Tone down overly bold designs
`/prompts:delight`	`[INTERACTION=<value>]`	Add moments of joy
`/prompts:extract`	`[PATTERN=<value>]`	Pull into reusable components
`/prompts:adapt`	`<component> [DEVICE=<value>]`	Adapt for different devices
`/prompts:onboard`	`[FLOW=<value>]`	Design onboarding flows
`/prompts:teach-impeccable`	-	One-time setup: gather design context

Codex CLI Features

Custom Prompts System

Codex CLI organizes user-invokable commands as custom prompts with the /prompts: prefix:

# List all custom prompts
/prompts:list

# Show prompt details
/prompts:show audit

# Execute prompt
/prompts:audit AREA=checkout

Skills for Reference

Codex treats skills as reference documentation rather than invokable commands. They’re loaded automatically when prompts reference them:

**First**: Use the frontend-design skill for design principles.
**Then**: Apply those principles to the task.

Global Installation

Unlike other providers, Codex skills are global:

# All projects share these skills
~/.codex/skills/

# NOT project-specific
project/.codex/  ❌

This means you install once and all projects benefit.

Argument Validation

Codex validates arguments based on argument-hint:

Required arguments (<name>) must be provided
Optional arguments ([NAME=<value>]) can be omitted
Codex prompts for missing required arguments

Quirks & Limitations

Prompts Prefix Required

Codex commands must use /prompts: prefix. Typing /audit won’t work - use /prompts:audit instead.

Uppercase Variables Only

Codex uses $ARGNAME (uppercase) not {{argname}} or {{args}}:

✅ Correct: Audit $AREA  
❌ Wrong: Audit {{area}}
❌ Wrong: Audit {{args}}

Global Scope

Skills affect all projects. You can’t have different skills per project.

No Per-Project Override

Codex doesn’t support project-specific skills. Everything in ~/.codex/ applies globally.

Argument Syntax

Codex uses KEY=value syntax (not space-separated):

✅ Correct: /prompts:audit AREA=checkout
❌ Wrong: /prompts:audit checkout
❌ Wrong: /prompts:audit area checkout

Troubleshooting

Commands Not Found

Check installation location

Ensure files are in ~/.codex/skills/ (not project directory)

Use correct prefix

Type /prompts:audit (not /audit)

Verify file structure

Check that ~/.codex/skills/audit/SKILL.md exists

Restart Codex CLI

Fully quit and restart to reload skills

Arguments Not Working

If $ARGNAME appears literally in responses:

Verify you’re using KEY=value syntax (not space-separated)
Check argument name matches the hint exactly (case-sensitive)
Ensure the skill body uses uppercase $ARGNAME

Skills Not Loading

If prompts can’t find the frontend-design skill:

Verify ~/.codex/skills/frontend-design/SKILL.md exists
Check YAML frontmatter is valid
Ensure name field matches directory name
Look for file permission issues

Migration from Other Providers

From Cursor or Claude Code

Codex uses uppercase variables:

# Other providers
Audit {{area}} for issues

# Codex CLI  
Audit $AREA for issues

From Gemini CLI

Codex supports named arguments (Gemini only has {{args}}):

# Gemini (single args string)
Adapt {{args}}

# Codex (named variables)
Adapt $COMPONENT for $DEVICE

Invocation Changes

Codex requires the /prompts: prefix:

# Other providers
/audit
/normalize

# Codex CLI
/prompts:audit
/prompts:normalize

Best Practices

1. Use Descriptive Variable Names

✅ Good
argument-hint: <component> [DEVICE=<value>]
Prompt: Adapt $COMPONENT for $DEVICE

❌ Bad
argument-hint: <x> [Y=<value>]  
Prompt: Adapt $X for $Y

2. Make Arguments Optional When Possible

Design prompts that work with or without arguments:

Audit $AREA. If AREA is not specified, audit the entire interface.

3. Leverage Reference Skills

Explicitly invoke comprehensive skills:

**First**: Use the frontend-design skill for anti-patterns.
**Then**: Apply that knowledge to $COMPONENT.

4. Use Argument Hints

Provide clear hints so users know the expected syntax:

# Clear
argument-hint: <component> [DEVICE=mobile|tablet|desktop]

# Unclear
argument-hint: stuff

5. Chain Prompts for Workflows

Codex excels at sequential refinement:

/prompts:audit → /prompts:normalize → /prompts:optimize → /prompts:polish
/prompts:critique → /prompts:bolder → /prompts:colorize → /prompts:animate

6. Remember Global Scope

Since skills are global, design them to work across different projects:

✅ Good: Generic, reusable guidance
"Follow design system tokens for colors"

❌ Bad: Project-specific assumptions  
"Use the primary-blue token from our Figma file"

Get Started

Core Concepts

Integration Guides

Usage

​Overview

​Installation

​File Structure

​Key Differences

​Skill Format

​How Arguments Work

​Argument Syntax

​Variable Transformation

​Argument Hints

​Provider-Specific Transformations

​1. Uppercase Variables

​2. Argument Hints

​3. Skill Structure

​4. Reference Files

​Usage Examples

​Basic Command

​With Argument

​Multiple Arguments

​Complex Workflow

​Available Skills

​Codex CLI Features

​Custom Prompts System

​Skills for Reference

​Global Installation

​Argument Validation

​Quirks & Limitations

​Prompts Prefix Required

​Uppercase Variables Only

​Global Scope

​No Per-Project Override

​Argument Syntax

​Troubleshooting

​Commands Not Found

​Arguments Not Working

​Skills Not Loading

​Migration from Other Providers

​From Cursor or Claude Code

​From Gemini CLI

​Invocation Changes

​Best Practices

​1. Use Descriptive Variable Names

​2. Make Arguments Optional When Possible

​3. Leverage Reference Skills

​4. Use Argument Hints

​5. Chain Prompts for Workflows

​6. Remember Global Scope

​Learn More

Build docs developers (and LLMs) love

Overview

Installation

File Structure

Key Differences

Skill Format

How Arguments Work

Argument Syntax

Variable Transformation

Argument Hints

Provider-Specific Transformations

1. Uppercase Variables

2. Argument Hints

3. Skill Structure

4. Reference Files

Usage Examples

Basic Command

With Argument

Multiple Arguments

Complex Workflow

Available Skills

Codex CLI Features

Custom Prompts System

Skills for Reference

Global Installation

Argument Validation

Quirks & Limitations

Prompts Prefix Required

Uppercase Variables Only

Global Scope

No Per-Project Override

Argument Syntax

Troubleshooting

Commands Not Found

Arguments Not Working

Skills Not Loading

Migration from Other Providers

From Cursor or Claude Code

From Gemini CLI

Invocation Changes

Best Practices

1. Use Descriptive Variable Names

2. Make Arguments Optional When Possible

3. Leverage Reference Skills

4. Use Argument Hints

5. Chain Prompts for Workflows

6. Remember Global Scope

Learn More