Codex skills glossary

An open format for packaging expertise an AI agent loads on demand: a folder with a SKILL.md file plus optional scripts, references and assets. Codex follows it, and so do many other agents, so one skill folder can work across tools.

The Agent Skills standard explained See also Skill, SKILL.md

A Markdown file of instructions Codex reads before any work, from ~/.codex and from each directory between the repository root and the working directory. It holds rules that apply to every task, such as build commands and conventions, up to 32 KiB combined by default.

AGENTS.md guide See also AGENTS.override.md, Skill

A file Codex reads instead of AGENTS.md in the same directory, or instead of the global ~/.codex/AGENTS.md. It is used for a temporary or team-specific override without editing the base file.

Nested AGENTS.md skill See also AGENTS.md

An optional file inside a skill folder with Codex-specific settings: UI metadata such as display name, short description, icons and default prompt, the invocation policy, and tool dependencies such as an MCP server. The portable SKILL.md stays unchanged.

agents/openai.yaml fields See also allow_implicit_invocation

A policy setting in agents/openai.yaml that defaults to true. Set it to false and Codex loads the skill only when someone mentions it explicitly, which suits skills with side effects like deploys.

Invocation policy See also Implicit invocation, agents/openai.yaml

The setting that decides when Codex stops to ask before acting: on-request, never, or a granular policy per prompt category. It works with the sandbox mode, which decides what is technically allowed.

Sandbox and approvals in the CLI See also Sandbox mode

The non-interactive Codex command for scripts and CI. It prints the final message to stdout, runs read-only by default, and supports JSON event output and schema-constrained results.

codex exec in CI skill See also Sandbox mode

The Codex configuration file. User settings live in ~/.codex/config.toml and trusted projects can add .codex/config.toml; it sets the model, sandbox, approvals, MCP servers and skill overrides, and is shared by the CLI and IDE extension.

config.toml skill See also Profile, Sandbox mode, Approval policy

An integration that connects ChatGPT and Codex to an external service such as Google Drive or Slack, typically backed by an MCP server. In the Codex CLI, /apps lists connectors, and a plugin can bundle one with the skills that use it.

Plugins, skills and connectors See also Plugin, MCP server

Everything the model can see at once, measured in tokens: instructions, AGENTS.md, conversation, file contents and tool output. Codex caps its list of available skills at about 2% of it by default, adjustable with skills.max_context_tokens up to 10,000 tokens.

Context budget skill See also Progressive disclosure

One or two sentences saying what a skill does and when to use it. It is the only text Codex considers when choosing a skill on its own, so it decides whether the skill ever triggers implicitly.

Skill description tuning skill See also Implicit invocation, Context window

Asking for a skill by name, by typing $ followed by the skill name or picking it from the /skills list in the Codex CLI or IDE extension. It loads the skill regardless of how the request is worded.

Using a skill See also Implicit invocation

The YAML block between two lines of three dashes at the very top of SKILL.md. It holds the metadata Codex reads before deciding to use a skill; name and description are required, and the open spec also allows license, compatibility and metadata.

Every frontmatter field See also name (frontmatter field), description (frontmatter field)

Codex choosing a skill by itself because your request matches the skill's description. A skill author can turn it off with allow_implicit_invocation: false in agents/openai.yaml.

Skill not triggering? Fixes See also Explicit invocation ($ mention), allow_implicit_invocation, description (frontmatter field)

An open protocol that lets an agent call tools and read data from other systems through MCP servers. In Codex it adds capabilities such as reading tickets or driving a browser, while skills add knowledge about how to work.

Codex MCP guide See also MCP server, Skill

A local process or remote service that exposes tools over MCP. Codex connects to servers listed under [mcp_servers] in config.toml, added by hand or with codex mcp add.

MCP server builder skill See also MCP (Model Context Protocol), Connector (app)

The skill identifier: up to 64 lowercase letters, digits and hyphens, matching the folder name. It is what you type after $ to invoke the skill, and Codex does not merge two skills that share one.

Naming rules See also Explicit invocation ($ mention)

An installable bundle that can contain skills, MCP servers, hooks and assets, shared through one directory used by ChatGPT and Codex. Skills are the authoring format; plugins are how you distribute them, especially alongside a connector.

Codex plugins guide See also Plugin marketplace, Connector (app), Skill

A JSON catalog of plugins, such as .agents/plugins/marketplace.json in a repository, that Codex can browse and install from. Add one with codex plugin marketplace add.

Share skills with your team See also Plugin

A named set of config overrides stored as its own file, ~/.codex/<name>.config.toml, and selected with codex --profile <name>. Profiles no longer live in [profiles] tables inside config.toml.

Codex profiles skill See also config.toml

Loading a skill in stages: first only its name, description and path, then the full SKILL.md when the skill is selected, then reference files or scripts only when the instructions call for them. It lets Codex keep many skills available at a small fixed cost.

How Codex loads skills See also Context window, references/ folder

An optional folder in a skill for documentation Codex reads only when needed, such as a detailed lookup table or an edge-case guide. Linking it from SKILL.md with a condition keeps the main file short.

Annotated skill examples See also Progressive disclosure, scripts/ folder

The OS-enforced boundary for commands Codex runs: read-only, workspace-write or danger-full-access. In workspace-write, edits stay inside the workspace, network is off unless enabled, and .git, .agents and .codex remain read-only.

Sandbox and approvals skill See also Approval policy

An optional folder in a skill for code Codex can run, used when a step must be deterministic. Scripts run like any other command, inside the sandbox and approval policy you configured.

Review scripts before installing See also Sandbox mode, references/ folder

A folder that teaches Codex one kind of task, built around a SKILL.md file. Codex keeps only its name, description and path in context until a task needs it, then reads the full instructions.

What are Codex skills? See also Progressive disclosure, SKILL.md, Skill scope (repo, user, admin, system)

Where a skill comes from. Repo skills live in .agents/skills from the working directory up to the repository root, user skills in ~/.agents/skills, admin skills in /etc/codex/skills, and system skills ship with Codex.

Install skills in the right scope See also Skill

A system skill bundled with Codex that drafts new skills. Invoke it with $skill-creator; it asks what the skill does, when it should trigger and whether it needs scripts.

Write your first skill See also skill-installer

A system skill bundled with Codex that installs skills from OpenAI's curated list by name, for example $skill-installer linear, or from a GitHub repository path. It is meant for local setup; plugins are the recommended way to distribute skills.

Every way to install skills See also skill-creator, Plugin

The required file at the root of every skill: YAML frontmatter with a name and a description, followed by Markdown instructions. Everything else in a skill folder is optional.

SKILL.md format reference See also Frontmatter, name (frontmatter field), description (frontmatter field)