Know Your Codex — The Complete Guide

A developer's guide to understanding OpenAI, ChatGPT, Codex, the Codex CLI, startup flags like --yolo, slash commands, profiles, approval modes, AGENTS.md, spec.md, installation, context windows, and how to get better results from the AI coding agent working in your terminal.

---

1. OpenAI — The Name & A Brief History

Why "OpenAI"?

The name OpenAI originally signaled an ambition to make advanced AI research broadly beneficial, widely shared, and aligned with the public good. The word "Open" reflected openness in research and access, while "AI" was the direct statement of the field: artificial intelligence.

Over time, the company evolved in structure, products, and deployment strategy, but the mission has remained centered on building AI that benefits humanity.

Timeline

• December 11, 2015: OpenAI was introduced as a nonprofit AI research company with the goal of advancing digital intelligence in a way that benefits humanity.
• 2019: OpenAI created a capped-profit structure to raise the capital needed for large-scale AI research and deployment.
• November 30, 2022: ChatGPT launched publicly and became the product that put conversational AI into mainstream daily use.
• 2021 to 2024: The original Codex model helped establish OpenAI's push into coding assistance, while ChatGPT kept expanding from chat into a broader work platform.
• May 16, 2025: OpenAI introduced the new Codex coding agent experience for software engineering tasks.
• September 15, 2025: OpenAI announced upgrades to Codex, including stronger real-time collaboration, IDE support, and cloud task workflows.

OpenAI's story is really two stories at once: a research lab building frontier models, and a product company turning those models into tools people actually use every day.

---

2. ChatGPT — Why It Changed Everything

Before ChatGPT, many people saw large language models as something for demos, benchmarks, or developer APIs. ChatGPT changed that by making AI feel conversational, practical, and immediate.

You could ask a question, iterate, refine, paste code, request a rewrite, compare options, and keep going in one threaded conversation. That interaction model turned AI from a one-shot tool into a working partner.

What ChatGPT Made Normal

• Asking follow-up questions instead of rewriting the prompt from scratch
• Uploading text or code and iterating on it in context
• Using one model for writing, research, coding, analysis, and planning
• Treating AI as an everyday assistant instead of a rare specialist tool

Why this matters for Codex

Codex inherits the conversational and iterative workflow people learned from ChatGPT, but applies it directly to software projects, files, shells, tests, and code review.

---

3. What Is Codex?

Codex is OpenAI's coding agent for software engineering work. In practice, that means it can read your repository, inspect files, run terminal commands, edit code, execute tests, explain changes, and help you move from "idea" to "working implementation" much faster.

Codex Then vs Codex Now

The name "Codex" has two important phases:

• Original Codex (2021): a code-specialized OpenAI model that powered early developer workflows and helped popularize AI code completion.
• Modern Codex (2025+): a full coding agent experience available through the CLI, IDE integrations, and cloud task workflows.

So when people say "Codex" today, they usually mean more than just a model. They mean a working coding system.

What Codex Can Do

• Explore a codebase and explain how it works
• Implement features from a prompt or specification
• Fix bugs and regressions
• Run tests, linters, and local tooling
• Review pull requests and suggest improvements
• Help with refactors, documentation, and migration work

---

4. Why the Name "Codex" Fits

A codex was the historical ancestor of the modern book: bound pages that made knowledge easier to organize, reference, and navigate.

That name fits unusually well for an AI coding tool.

Why?

• A codebase is a kind of living book
• Source files are pages of system knowledge
• Good engineering depends on navigating, understanding, and revising that knowledge safely

In short: Codex is a tool for reading and rewriting the "book" of your software.

---

5. Installing Codex

Codex is available as a CLI and can also be used through supported editor integrations and ChatGPT plans.

macOS

If you use Homebrew:

brew install --cask codex
codex --version
codex --login

If you prefer npm:

npm install -g @openai/codex
codex --version
codex --login

Linux

npm install -g @openai/codex
codex --version
codex --login

Make sure node and npm are already installed. A modern Node.js setup is the safest path before installing the CLI globally.

Windows

The most reliable setup is to run Codex through WSL rather than plain Command Prompt, especially for repo tooling, Unix-style commands, and smoother local development workflows.

wsl --install

Then inside your WSL terminal:

npm install -g @openai/codex
codex --version
codex --login

First Login

codex --login

This connects the CLI to your OpenAI account. Depending on your setup, Codex can be used through supported ChatGPT plans or through API-based workflows.

---

6. Codex Highlights

Codex is useful because it is not limited to generating code snippets. It can operate on a real project with real files, real commands, and real constraints.

Core Strengths

• Repo-aware: it works against the code you actually have, not an imaginary greenfield project
• Terminal-native: it can inspect, run, and verify work in the same environment you use
• Iterative: you can refine a task over multiple prompts instead of starting over each time
• Agentic: it can carry a task through analysis, edits, and validation
• Review-friendly: it can explain why a change was made, not just produce one

Typical Use Cases

Task	Where Codex Helps Most
Bug fixing	Reproducing, tracing, patching, verifying
Feature work	Turning specs into implementation
Refactoring	Preserving behavior while improving structure
Onboarding	Explaining architecture and file responsibilities
Reviews	Finding regressions, risky assumptions, and missing tests

---

7. Running Codex in the Terminal

The terminal is where Codex feels most natural because software work already happens there.

Common Patterns

codex

Launch an interactive coding session inside the current project.

codex "explain the auth flow in this repo"

Use a direct prompt to start from a concrete task.

codex "fix failing tests in the payments module"

Start with an outcome, not implementation details. Let Codex inspect the code first.

Point Codex at the Exact File

If you already know the file you want Codex to focus on, attach it instead of describing it vaguely.

Documented CLI flow:

/mention docs/ai/know-your-codex.mdx

That tells Codex to pull the file directly into the conversation context for the next turn.

In current CLI builds, many developers also use inline file mentions such as @SPEC.md or @docs/api/auth.md. The stable, documented workflow in the official CLI docs is still /mention, so that is the safest thing to teach first.

What the CLI Workflow Feels Like

1. You describe the task
2. Codex reads the repo and gathers context
3. It proposes or performs edits
4. It runs checks where possible
5. It reports what changed and what still needs attention

That loop is what makes Codex feel closer to an engineering assistant than a chat bot.

Queueing and Steering While a Prompt Is Running

One useful Codex CLI habit is steering a live run instead of waiting for the whole turn to finish.

• If Codex is already working, you can type a follow-up instruction and press Enter to queue it for the same conversation
• Use this for mid-flight steering such as "after the tests finish, also check the lint errors" or "focus only on the auth module"
• Tab is for completion and selection, especially for slash commands and file mentions, not for sending the message

So the practical mental model is simple: Enter submits or queues, while Tab helps complete.

---

8. Useful CLI Flags, Modes & Shortcuts

Before you even use a slash command, Codex gives you a few important startup modes.

codex --yolo

--yolo is the speed-first flag. It tells Codex to stop interrupting you for routine approvals and to move faster through local engineering work.

Why the name "yolo"?

• it is shorthand for "you only live once"
• in CLI culture, it implies "accept the risk and move fast"
• in Codex, it means you are intentionally trading more caution for more autonomy

Use it when:

• you know the repository well
• the task is scoped and reversible
• you want fewer approval interruptions during implementation

Example:

codex --yolo

codex --dangerously-bypass-approvals-and-sandbox

This is the strongest autonomy flag. It disables the usual approval flow and sandbox protections.

codex --dangerously-bypass-approvals-and-sandbox

This is not the same as normal convenience mode. It is the "I understand the risks, let the agent operate with very few barriers" option.

Use it only when:

• you fully trust the environment
• the repo is local and disposable or well backed up
• you understand that Codex may run broader commands and make broader edits

When to Use Which Mode

Mode	Best For	Tradeoff
Default approvals	unfamiliar repos, risky work, production-adjacent changes	slower, safer
--yolo	everyday local coding in repos you understand	faster, less friction
--dangerously-bypass-approvals-and-sandbox	highly trusted environments and power-user workflows	maximum speed, minimum guardrails

---

9. Slash Commands — The Fast Way to Drive Codex

Slash commands are the keyboard-first control layer for Codex CLI. Instead of restarting the CLI or rewriting your prompt, you can change models, reset context, inspect status, review diffs, or switch behavior directly inside the session.

The Most Useful Slash Commands

Command	What It Does	When to Use It
/model	Change the active model and, when supported, reasoning effort	Switch between faster and deeper thinking mid-session
/new	Start a fresh conversation in the same CLI session	Change tasks without leaving the terminal
/clear	Clear the terminal and start a fresh chat	Reset both the screen and conversation
/status	Show session configuration and token usage	Check model, approvals, writable roots, and context usage
/diff	Show the Git diff, including untracked files	Review edits before committing
/compact	Summarize the conversation to save context	Keep long sessions from bloating the context window
/review	Ask Codex to review the working tree	Get a second-pass check for regressions and missing tests
/permissions	Change approval behavior mid-session	Move between stricter and faster execution modes
/plan	Switch into planning mode	Get a plan before letting Codex edit anything
/init	Generate an AGENTS.md scaffold	Bootstrap project-specific instructions
/mention	Attach a file or path to the conversation	Point Codex directly at the code you care about
/resume	Reopen a previous saved conversation	Continue earlier work without losing context
/fork	Branch the current conversation into a new thread	Explore an alternative approach safely
/mcp	Show configured MCP tools	Check which external tools are available
/copy	Copy the latest completed output	Reuse a plan, explanation, or review quickly
/ps	Show background terminals and recent output	Inspect long-running processes from inside the CLI

A Few Practical Examples

/model

Use /model when the task changes shape.

• Start with a faster model for repo exploration or simple edits
• Switch to a stronger coding model for architecture, large refactors, or tricky debugging
• Use /status right after if you want to verify the active model and session settings

/new

/new is the clean way to switch tasks without quitting Codex.

Example flow:

/new
Now help me review the caching changes in the API layer.

This is useful when the current chat is about one problem and you do not want stale context leaking into the next one.

/diff and /review

These are the commands that make Codex safer in real repos.

• /diff lets you inspect exactly what changed
• /review asks Codex to evaluate the working tree like a reviewer, not like the original implementer

That combination is one of the easiest ways to catch subtle regressions before you commit.

---

10. How to Check Usage Stats in the CLI

People often ask how to see "usage statistics" in Codex. In the CLI, the most useful answer is /status.

What /status Shows

• active model
• approval policy
• writable roots
• current token usage
• remaining context capacity

That gives you a session-level view of how the current conversation is configured and how much room you have left before the context gets crowded.

Related Commands for Session Hygiene

• /compact: summarize the conversation so you keep the important context while freeing space
• /statusline: customize the footer so model, context stats, limits, git info, token counters, session ID, and other indicators stay visible
• /ps: inspect background terminals if a long-running command is still working

Important Distinction

/status is about the current Codex session, not your account billing dashboard.

If you are using Codex through a ChatGPT plan, your overall usage limits depend on the plan. When you hit those limits, Codex access pauses until the window resets. For local CLI work, /status helps you manage the session you are in right now, not your full subscription consumption.

---

11. Profiles, Global Config & One-Off Overrides

One of the best Codex habits is learning the difference between permanent configuration and temporary overrides.

Global Config

The long-term place to tune Codex is:

~/.codex/config.toml

This is where you define default behavior, provider settings, and reusable profiles.

Useful shell commands:

cat ~/.codex/config.toml
vim ~/.codex/config.toml

Codex also supports project-scoped configuration in a local .codex/config.toml, which is useful when a repository needs its own MCP servers, approval defaults, or project-specific behavior without affecting every other repo on your machine.

Reusable Profiles

Profiles are ideal when you want different Codex personalities for different kinds of work.

# ==============================================================================
# PROFILE 1: "Deep Work"
# For complex refactors requiring high reasoning and full autonomy.
# ==============================================================================
[profiles.deep-work]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

# ==============================================================================
# PROFILE 2: "Quick Fix"
# For fast, low-cost tasks like fixing typos or simple bugs.
# ==============================================================================
[profiles.quick-fix]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "low"
web_search = "disabled"

Then launch Codex with a profile:

codex --profile deep-work

or:

codex --profile "deep-work"

This is cleaner than retyping the same model and reasoning flags every day.

One-Off Configuration

For temporary overrides, use --config or -c.

codex --config model="gpt-5.4"

Short form:

codex -c model="gpt-5.4"

You can stack multiple overrides:

codex --config model="gpt-5.4" --config sandbox_mode="read-only"

or:

codex -c model="gpt-5.4" -c sandbox_mode="read-only"

The rule of thumb is simple:

• use config.toml for defaults you want repeatedly
• use profiles for named work modes
• use -c for one-time experiments

Fallback Filenames When AGENTS.md Is Missing

If a project already uses another instructions file, Codex can fall back to that name when AGENTS.md is not present.

Example:

project_doc_fallback_filenames = ["CLAUDE.md"]

That means Codex will look for CLAUDE.md only after checking for AGENTS.override.md and AGENTS.md in the directory chain. This is helpful for mixed-tool repos that already standardized on another filename.

Checking Which MCP Servers Are Enabled

From the terminal:

codex mcp list
codex mcp list --json

Use the plain version for a quick human-readable check, and --json when you want the output for tooling or scripts.

MCP Server Examples

Common examples worth knowing:

• Context7: gives Codex current developer docs and library references
• Playwright MCP: gives Codex browser control for page inspection and testing
• DeepWiki MCP: a third-party MCP server that exposes AI-generated documentation and search over public GitHub repositories

For example, the official Codex MCP docs show Context7 configured in toml file like this:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

---

12. Using OSS Models & Other Providers

Codex is not limited to OpenAI-hosted models. It can also work with local or OpenAI-compatible providers.

Using OSS Models

Example:

codex --oss --model llama3

When using Ollama-backed OSS models, use the exact model name shown by:

ollama list

What Is the Default OSS Model?

There is no single universal OSS default you should rely on. In practice, the default depends on your local provider setup and what model names are available there. For reliable results, set the model explicitly instead of assuming Codex will guess the right local one.

Permanent OSS Setup in config.toml

oss_provider = "ollama"

[model_providers.ollama]
name = "Ollama Local"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

That tells Codex to use your local Ollama server as the default OSS provider.

Other OpenAI-Compatible Providers

You can also define providers like Groq, Mistral, or other OpenAI-compatible endpoints.

model_provider = "groq"
model = "llama-3.1-70b-versatile"

[model_providers.groq]
name = "Groq"
base_url = "https://api.groq.com/openai/v1"
env_key = "GROQ_API_KEY"
wire_api = "chat"

The pattern is the same:

• define a provider key
• point Codex at the provider's compatible base URL
• specify the API key environment variable
• choose a model that provider actually offers

---

13. codex exec, Resume & Fork Workflows

Not every Codex task has to begin in a live interactive chat.

codex vs codex exec

codex "Analyze the project"

This starts a normal interactive session from a direct prompt.

codex exec "Analyze the project"

This is useful for more structured command-style workflows.

And if you want machine-readable output:

codex exec "Analyze the project" --json

That can be useful for scripts, tooling wrappers, or automation layers around Codex.

Resume Earlier Work

codex resume
codex resume --all
codex resume --last

This matters when you do not want to lose the context of an earlier task.

The slash command form works inside the CLI too:

• /resume

Fork a Session

codex fork
codex fork --last

Forking is useful when you want to explore an alternative direction without contaminating the current thread.

Inside the CLI, the equivalent slash command is:

• /fork

This is one of the safest ways to compare two implementation strategies.

New Worktrees in Codex App

In the Codex app, new background threads usually run in a Codex-managed Git worktree rather than your foreground checkout.

• Codex creates these worktrees under $CODEX_HOME/worktrees
• The worktree starts from the selected branch HEAD
• The worktree is usually in a detached HEAD state so Codex can create several worktrees without polluting your local branches
• If you hand the thread back to Local later, Codex moves the thread safely between the worktree and your normal checkout

This is why a "new worktree" in Codex is not just a duplicate folder. It is an isolated Git working environment for that thread.

---

14. Codex Cloud — Run Tasks Remotely, Apply Locally

Codex is not only a local terminal agent. Current CLI builds also expose an experimental codex cloud workflow for browsing remote Codex tasks and pulling their changes back into your local repo.

This is useful when:

• you want a task to run in a remote Codex environment instead of your current shell
• you want to review the result before touching your local working tree
• you want to submit work, come back later, and apply the patch only when it looks right

Prerequisites for Codex Cloud

Before codex cloud is practical, a few pieces usually need to be in place:

• the project should already live in a GitHub-hosted repository
• your ChatGPT or Codex setup should be connected to GitHub
• the specific repository must be authorized so Codex can access it
• you need a cloud environment configured for the repo
• your local checkout should match the repo and branch you expect to apply changes into

The key mental model is simple: Codex Cloud works against a remote GitHub-backed environment, not just whatever random local folder happens to be open on your laptop.

So if a repository only exists locally and is not available through the connected GitHub setup, Codex Cloud is usually the wrong workflow. In that case, local codex is the better fit.

The Main codex cloud Commands

codex cloud
codex cloud list
codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>
codex cloud apply <TASK_ID>
codex cloud exec --env <ENV_ID> "fix the failing auth tests"

What each one does:

Command	Purpose
codex cloud	Opens the cloud-task browser flow from the CLI
codex cloud list	Lists recent Codex Cloud tasks
codex cloud status <TASK_ID>	Shows the current status of one task
codex cloud diff <TASK_ID>	Prints the unified diff for a completed task
codex cloud apply <TASK_ID>	Applies the task's diff to your local checkout
codex cloud exec --env <ENV_ID> "..."	Submits a new remote task without starting the TUI

Notice the --env <ENV_ID> requirement on codex cloud exec. That is your signal that cloud execution depends on a defined remote environment, not only on the local repository path.

How to Use It in Practice

The most practical workflow is:

1. submit a task to a remote environment
2. list or inspect the task until it finishes
3. review the diff
4. apply the patch locally
5. run your own tests before committing

Example flow:

codex cloud exec --env env_123 "update the onboarding form validation and add tests"
codex cloud list
codex cloud status task_abc123
codex cloud diff task_abc123
codex cloud apply task_abc123

That pattern matters because apply should usually come after diff, not before. Review first, then merge the remote work into your local branch intentionally.

Practical Setup Advice

• push the branch you want Codex Cloud to work against
• make sure the repository is visible to the connected GitHub integration
• confirm you are applying the diff into the matching local repo and branch
• treat codex cloud apply like a patch import, then run your own tests locally

That last point matters. Cloud execution can produce a useful patch, but your local verification step is still the engineering control point before commit or PR.

Useful Options

codex cloud list --limit 10 --json
codex cloud diff task_abc123 --attempt 2
codex cloud apply task_abc123 --attempt 2
codex cloud exec --env env_123 --branch feature/auth-fix --attempts 3 "fix flaky auth tests"

These options are especially useful when:

• --json is needed for scripts or tooling wrappers
• --attempt lets you inspect or apply a specific attempt from a task with multiple tries
• --attempts asks Codex Cloud for best-of-N runs
• --branch tells the cloud task which Git branch to run against
• --env selects the remote environment where the task should execute

Local vs Cloud Mental Model

• local codex is best when you want tight iteration inside your current shell
• codex cloud is best when you want remote execution, later review, and a patch-style handoff back to local work

If you teach this workflow, be explicit that codex cloud is currently marked as experimental in the CLI help. That means command shape and behavior may evolve faster than the core local codex flow.

---

15. Context Window — Why It Changes the Way You Work

The context window is the amount of conversation, code, instructions, and file content Codex can actively keep in working memory during a session.

Why it matters:

• long chats consume context
• large pasted files consume context
• repeated edits and diff history consume context
• once the window gets crowded, the model has less room for fresh task details

Practical Ways to Manage Context

• use /status to keep an eye on session usage
• use /compact when a thread gets long
• use /new when you are switching to a genuinely different task
• mention the exact files you care about instead of pasting huge code dumps
• keep prompts focused on one outcome at a time

Context management is not a minor optimization. It directly affects answer quality, consistency, and how well Codex remembers your constraints.

---

16. spec.md and Task-Driven Work

For larger features, Codex works better when the request lives in a real spec instead of a loose paragraph in chat.

That spec is often a file like:

spec.md

Why a spec.md Helps

• the requirements are visible and reviewable
• Codex can revisit the file instead of relying on a long conversational memory
• acceptance criteria stay stable across multiple sessions
• it becomes easier to plan, implement, and verify against the same source of truth

Typical Flow

1. Write the problem, scope, and constraints in spec.md
2. Ask Codex to read it and propose a plan
3. Have Codex implement against that spec
4. Ask Codex to verify the work against the spec before finishing

Example prompt:

Read spec.md, propose an implementation plan, then implement it step by step.
Do not add dependencies unless the spec requires it. Run the relevant checks at the end.

This works especially well for migrations, multi-file features, and team handoff work.

spec.md vs AGENTS.md

People often mix these up, but they solve different problems.

File	Purpose	Scope
spec.md	defines the task, acceptance criteria, and implementation target	one feature or one chunk of work
AGENTS.md	defines persistent repo rules, commands, conventions, and guardrails	the project, folder, or team area

Good pattern:

• put stable team rules in AGENTS.md
• put the current feature request in spec.md
• ask Codex to read both when the task is large

Example:

Read @SPEC.md and follow the rules in AGENTS.md.
Propose a plan, implement only what the spec requires, and verify the result.

If you prefer the documented CLI flow, attach the file with /mention SPEC.md first and then give the instruction.

---

17. Approval Modes — Why They Matter

When Codex works locally, permissions matter. A serious coding agent should not blindly modify files or execute commands without clear boundaries.

Typical Modes

• Normal / Ask-first: Codex asks before important actions
• Auto-accept: Codex proceeds faster when you trust the scope
• Read-only / Planning workflows: useful when you want analysis before edits

Practical Rule

• Use ask-first mode for unfamiliar repos, production-adjacent work, and risky migrations
• Use auto-accept mode for scoped tasks in repos you know well
• Use planning mode when the task is large, ambiguous, or architectural

The right approval mode is not about convenience. It is about matching trust to risk.

---

18. AGENTS.md — The Secret to Better Results

If there is one habit that improves Codex output the most, it is giving the agent local project instructions.

AGENTS.md tells Codex how your team works: commands, conventions, constraints, expectations, and "don't do this" rules.

What to Put in AGENTS.md

# Project Rules

## Commands
- `npm run dev`
- `npm test`
- `npm run lint`

## Conventions
- Use TypeScript everywhere
- Prefer named exports
- Keep components under 200 lines where possible
- Add tests for behavior changes

## Guardrails
- Do not modify generated files
- Do not change database schema without a migration
- Ask before introducing new dependencies

Why This Helps

• Codex stops guessing your standards
• It picks better commands on the first try
• It avoids obvious team-specific mistakes
• Outputs become more consistent across sessions

Think of AGENTS.md as the difference between hiring a contractor with no briefing and hiring one with a proper project handbook.

How Codex Actually Loads AGENTS.md

This is an important detail: Codex reads AGENTS.md files before doing work, then builds an instruction chain for that session.

That means:

• it is not truly "lazy loaded on demand" the way skills are
• Codex can combine global guidance from ~/.codex/AGENTS.md with project and subdirectory guidance
• closer files override broader files because they appear later in the merged instruction chain

Codex also has a size cap for this combined project guidance, so treating one giant AGENTS.md as a dump for everything is a bad habit.

Do Not Put Everything in One AGENTS.md

Use AGENTS.md for the rules Codex should carry into every task in that area:

• build and test commands
• coding conventions
• dependency rules
• migration or security guardrails

Do not use it as a giant knowledge base for every workflow, API detail, or long reference note. That bloats the instruction chain and makes every session pay for context that may not matter.

When a repo needs specialized, optional guidance, skills are often a better fit.

Skills vs AGENTS.md

Skills use progressive disclosure. Codex starts with the skill metadata, then loads the full SKILL.md only when the skill is relevant or explicitly invoked.

That makes skills a better fit for:

• optional workflows
• domain-specific playbooks
• reusable task bundles
• instructions that would otherwise make AGENTS.md too large

How Skills Work in Codex

Official Codex docs describe skills as folders built around a required SKILL.md, with optional scripts/, references/, assets/, and agents/openai.yaml.

Short example:

.agents/skills/modern-tailwind/SKILL.md

---
name: modern-tailwind
description: Write clean modern Tailwind CSS. Use when working on or reviewing Tailwind code.
---

Prefer existing design tokens, keep utilities readable, and avoid class churn.

Practical notes:

• run /skills to browse available skills
• type $ to mention a skill in chat
• $skill-creator is the built-in way to scaffold a new skill
• keep the folder name and the name: field aligned as a best practice
• a skill can be instruction-only, or it can include references/ docs and helper scripts

Example invocations:

$skill-creator
$modern-tailwind clean up the card spacing and button hierarchy

Where Skills Live

The current official Codex docs describe these main locations:

• repo-scoped skills under .agents/skills
• user-scoped skills under ~/.agents/skills

You may also see community examples that use .codex/skills/.... Treat that as a community convention unless your own setup explicitly relies on it. The primary documented Codex path today is .agents/skills.

Installing Skills Beyond the Built-ins

Codex has its own built-in skill flow through $skill-installer, and the broader ecosystem also uses the open agent-skills format.

One example is skills.sh, a third-party skill directory and installer. A common install flow there looks like:

npx skills add vercel-labs/agent-skills

That is ecosystem tooling rather than a built-in Codex CLI command, but it is useful to know because many portable skills are now distributed that way.

---

19. How to Use Codex Better

Good results usually come from good task framing, not magical prompting.

Best Practices

• Start with the goal, not the implementation: say "fix the login redirect bug" before saying "change line 42"
• Give constraints early: framework version, coding standards, test command, no-new-dependencies rules
• Ask for a plan on large tasks: especially for migrations, refactors, or cross-cutting changes
• Point to files when you already know the area: this reduces search time and ambiguity
• Have it verify changes: ask it to run or describe the relevant tests, linters, or checks
• Keep tasks scoped: one crisp task beats five loosely related ones in the same prompt
• Use slash commands deliberately: /model, /new, /status, /compact, /resume, /fork, and /mcp are workflow tools, not just convenience features
• Use specs for larger work: a stable spec.md is often better than a long chat thread

Better Prompt Examples

Instead of:

fix this

Use:

Investigate why password reset emails are not being sent in production.
Check the mailer service, env usage, and recent auth changes. Fix the bug,
update tests if needed, and summarize the root cause.

Instead of:

refactor dashboard

Use:

Refactor the dashboard page to reduce duplication across the three summary cards.
Keep behavior identical, do not change styling, and run the relevant tests after editing.

The Core Pattern

Goal + context + constraints + verification

That formula produces consistently better results than vague "please improve this" prompts.

---

20. Where Codex Fits Best

Codex is strongest when the work has concrete artifacts:

• source code
• tests
• logs
• config
• docs
• command output

It is especially good at:

• turning tickets into implementation steps
• making careful, incremental edits in existing repos
• catching missing edge cases during code review
• accelerating boring but necessary engineering work

It is less impressive when the request is vague, context-free, or based on hidden assumptions that are never stated.

---

21. Codex, ChatGPT, and the Bigger Picture

ChatGPT made AI conversation mainstream. Codex applies that same interaction model to engineering work.

If ChatGPT is the general-purpose conversational layer, Codex is the software-delivery layer. It takes the flexibility of chat and adds files, terminals, verification, and action.

That is why Codex matters: not because it writes code in isolation, but because it works inside the real shape of software development.

---

22. Final Take

Codex is most useful when you treat it like a fast, careful engineering collaborator:

• give it repo context
• give it rules
• give it verification steps
• keep tasks well scoped
• use profiles and one-off config deliberately
• use slash commands to manage session state instead of fighting the interface
• reach for --yolo only when the speed-vs-safety tradeoff makes sense

Do that, and it becomes much more than autocomplete. It becomes a practical coding agent that can help you understand systems faster, ship changes with less friction, and spend more of your time on the hard parts that actually need human judgment.