Codex skills: where OpenAI's agent finds SKILL.md files, and which ones to install

Codex skills are folders containing a SKILL.md file that OpenAI’s Codex CLI and IDE extension discover in .agents/skills directories and load when a task calls for them. At the start of a session Codex sees only each skill’s name, description and file path; it reads the full instructions when the user mentions the skill with $, picks it from /skills, or when the task matches the description closely enough that Codex selects it on its own. The format is the open Agent Skills standard, so the same folder works in Cursor, Claude Code and other agents. This guide covers where Codex looks, how selection and the context budget work, how to write a skill that triggers, how to install shared skills with npx skills add ... -a codex, and which skills earn a place in a team’s Codex setup.

TL;DR

• Codex scans .agents/skills from the working directory up to the repository root, then $HOME/.agents/skills, /etc/codex/skills and its bundled system skills. ~/.codex/skills is not in OpenAI’s current list.
• Selection is explicit ($skill-name or /skills) or implicit (the description matches the task). The initial skill list gets at most 2% of the context window, and Codex shortens descriptions first when it overflows, so trigger words belong at the front.
• npx skills add <owner/repo> -a codex writes to .agents/skills, which Codex reads directly. In a test install on October 28, 2026, six skills landed there with no Codex-specific copy needed.
• For teams building LLM apps, the most useful additions are a governance skill for rolling Codex out through a gateway with per-developer budgets, a cost skill and a security skill. All three are open source under MIT.

How Codex loads a skill

Codex loads skills in three steps: a short index at session start, the full SKILL.md when a skill is selected, and bundled files only when the instructions point to them. A skill therefore costs almost nothing until it is used, but every installed skill competes for a fixed slice of the context window.

OpenAI’s skills documentation calls this progressive disclosure. Codex “start[s] with each skill’s name and description, then load[s] the full SKILL.md instructions when they decide to use that skill.” In Codex specifically, that initial list also carries the skill’s file path, so the agent knows where to read from.

The index has a budget. By default it “uses at most 2% of the model’s context window, or 8,000 characters when the context window is unknown.” When too many skills are installed, Codex “shortens skill descriptions first,” and for large sets it “may omit some skills from the initial list and show a warning.” The skills.max_context_tokens setting in config.toml raises or lowers the budget, up to 10,000 tokens. The budget applies only to the index; a selected skill’s full instructions are read regardless.

That budget is easy to underestimate. The six build-with-ai-hq skills covered below have descriptions of 904 to 1,021 characters each, 5,905 characters in total when counted from the installed files. Against the 8,000-character fallback, those six alone take roughly three quarters of the index before a single team-specific skill is added. On models with large context windows, 2% leaves more room, but the lesson holds: install the skills a repository needs, not every skill a team has heard of.

The tiers come from the Agent Skills specification: about 100 tokens of metadata per skill, a body under 5,000 tokens recommended, and resources loaded “only when required.”

Where Codex looks for skills

Codex reads skills from four kinds of location: repository folders, the user’s home directory, a machine-wide admin path and skills bundled by OpenAI. Inside a Git repository it scans .agents/skills in every directory from where Codex was launched up to the repository root, so a monorepo can keep skills next to the code they describe.

OpenAI’s location table lists these scopes:

Two behaviours matter in practice. Codex “supports symlinked skill folders and follows the symlink target,” which is how the skills CLI can share one copy between agents. And if two skills share a name, Codex “doesn’t merge them; both can appear in skill selectors,” so a personal copy and a team copy sit side by side rather than one overriding the other.

~/.codex/skills is not among the locations OpenAI documents today; personal skills belong in $HOME/.agents/skills. Cursor still reads ~/.codex/skills for compatibility, a detail covered in the companion guide to Cursor skills.

Skills versus AGENTS.md

Codex has a second instruction mechanism, and the two are often confused. AGENTS.md is read “before doing any work”: Codex takes the global file from ~/.codex, walks from the project root to the working directory picking up at most one AGENTS.md (or AGENTS.override.md) per directory, and concatenates them, stopping at project_doc_max_bytes, 32 KiB by default. Everything in AGENTS.md is paid for in every session. A skill costs a line in the index until it is selected. The practical split: AGENTS.md for rules that always apply (test command, package manager, review expectations), skills for procedures that only some tasks need (a release runbook, a gateway rollout, a security audit).

Invoking skills in Codex CLI and the IDE extension

Codex activates a skill in one of two ways. Explicit invocation means the user names it: run /skills to browse, or type $ and the skill name in a prompt. Implicit invocation means Codex picks the skill itself because the request matches the skill’s description. Both work in the CLI and in the IDE extension; standalone skills are also available in the ChatGPT desktop app.

The invocation section draws the consequence for authors: “Because implicit matching depends on description, write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened.” The second sentence ties back to the index budget. A description that opens with background and saves its trigger phrases for the end is the one that loses them when Codex trims.

Codex adds controls on top of the spec:

• agents/openai.yaml. An optional file inside the skill folder sets display metadata, declares tool dependencies such as an MCP server, and carries an invocation policy. allow_implicit_invocation: false stops Codex from choosing the skill on its own; $skill still works. This suits skills with side effects, such as a deploy runbook, that should only run on request.
• [[skills.config]] entries in ~/.codex/config.toml disable a skill by path without deleting it (enabled = false), followed by a restart.
• Granular approvals. Codex’s advanced configuration documents a granular approval_policy whose categories include skill_approval, so prompts raised by skill scripts can be routed to normal approval or set to fail closed.

Writing a Codex skill that triggers

A Codex skill needs only a folder and a SKILL.md with name and description in YAML frontmatter, followed by Markdown instructions. The name must be lowercase letters, digits and single hyphens, match the folder name and stay under 64 characters; the description must be under 1,024 characters. Optional scripts/, references/ and assets/ folders hold anything the body tells Codex to run or read.

The bundled $skill-creator asks what the skill does, when it should trigger and whether it needs scripts. Writing one by hand is as quick:

---
name: release-packages
description: Cut, tag and publish a release of this monorepo's packages, including
  changelog generation and version bumps. Use when the user wants to release, ship,
  publish or bump a version, or asks why the release CI job failed. Not for deploying
  the web app.
metadata:
  version: "1.0.0"
---

# Release packages

1. Run `pnpm changeset status` and stop if nothing is pending.
2. Read references/ci-failures.md only if the release job failed.
3. ...

The description follows a pattern that the agent-skills-for-teams skill spells out: concrete capability first, then situations, then the phrases users actually type, then a “Not for…” boundary when a sibling skill overlaps. Its reference file warns that “agents tend to skip skills for tasks they believe are simple,” so triggering matters most where the skill carries knowledge the model lacks: the repository’s own commands, internal APIs, a fragile sequence.

Keep the body lean. Codex reads the whole SKILL.md on selection, so anything the model already knows is paid for on every activation. The spec recommends under 500 lines; move long material into references/ with an explicit load condition, as in step 2 above. OpenAI’s own advice is one job per skill, and instructions over scripts unless a step must be deterministic.

Installing shared skills with npx skills

The open-source skills CLI installs any GitHub-hosted skill into Codex with one command. With -a codex, it writes the skill to .agents/skills/<name> in the project, the same path Codex scans, so no Codex-specific copy or symlink is needed. A global install with -g goes to ~/.agents/skills, which Codex reads as user scope.

# Preview what a repository offers without installing
npx skills add build-with-ai-hq/ai-coding-agent-governance --list

# Install into the current project for Codex
npx skills add build-with-ai-hq/ai-coding-agent-governance -a codex

# Same skill for Codex, Cursor and Claude Code, no prompts
npx skills add build-with-ai-hq/ai-coding-agent-governance -a codex -a cursor -a claude-code -y

# Install for every repository on this machine
npx skills add build-with-ai-hq/ai-coding-agent-governance -a codex -g

npx skills list      # what is installed, for which agents
npx skills update    # pull newer versions deliberately

The CLI’s agent table lists Codex with a project path of .agents/skills/ and a global path of ~/.agents/skills/, matching OpenAI’s documentation. Codex’s own $skill-installer is a second route for curated skills, and OpenAI recommends plugins for distributing skills to other people.

What the test install showed

In a test install on October 28, 2026, The Frontier Wire ran npx -y skills@1.7.4 add build-with-ai-hq/<name> -a claude-code -a codex -a cursor -y once for each of the six skills below, in an empty Git repository on macOS with Node 26. Each run reported “Installed 1 skill,” placed the files at ./.agents/skills/<name>, and reported them as “universal: Codex, Cursor” and “symlinked: Claude Code.” No .codex folder was created; Codex needs none. The CLI wrote a skills-lock.json recording each skill’s source, path and a computed hash, and printed one warning worth repeating: “Review skills before use; they run with full agent permissions.”

npx skills list then showed all six as project skills available to Codex, Cursor, Claude Code and other agents. Running the lint_skills.py linter that ships inside agent-skills-for-teams over the six returned “0 error(s), 0 warning(s),” which means every body sits within the spec’s 5,000-token recommendation. Nothing was run against a production application.

Six skills for teams building LLM apps on Codex

Six MIT-licensed skills published in October 2026 by the build-with-ai-hq GitHub organization cover the infrastructure work that tends to land on whoever uses Codex most: rolling agents out, cutting model spend, hardening LLM features, observability, MCP and managing skills themselves. Each one uses Bifrost, Maxim AI’s open-source AI gateway, as its default control point and includes the vendor-neutral practice alongside it.

Prompts starting with $ force the skill; the rest test implicit matching against each description.

ai-coding-agent-governance for Codex rollouts

ai-coding-agent-governance is the most Codex-specific of the six. It turns “everyone installed Codex and shares one OpenAI key” into a rollout where each developer and CI job has its own revocable credential, a budget, a model allowlist and a log trail. Its description triggers on phrases such as “we got a surprise AI bill,” “developers share one Anthropic/OpenAI key” and “roll out Claude Code / Codex / Cursor to the team.”

The skill starts with a quick diagnosis: shell commands that find raw provider keys in environment variables and shell profiles, git grep for committed keys, and a loop over agent config files including ~/.codex/config.toml. Then it works through an ordered plan: a one-page policy (a template is in references/rollout-checklist.md), one gateway in front of every agent, one credential per developer and pipeline, per-agent configuration, enforced settings, central MCP control, data handling and log retention.

The Codex section of references/per-tool-setup.md is where most self-built rollouts go wrong, and it is precise:

# ~/.codex/config.toml
model = "openai/gpt-5"
model_provider = "bifrost"

[model_providers.bifrost]
name = "Bifrost"
base_url = "https://bifrost.internal.example.com/openai/v1"
wire_api = "responses"
env_key = "BIFROST_API_KEY"
requires_openai_auth = false
supports_websockets = false

The accompanying notes explain each line: run /logout first, because an existing OpenAI sign-in “takes precedence over custom credentials”; keep the trailing /v1, because Codex appends /responses; use a named provider, because “setting only OPENAI_BASE_URL can leave Codex on its built-in provider”; turn off websockets so the gateway can translate requests to non-OpenAI models; and give env_key a dedicated variable so a developer’s personal OPENAI_API_KEY is not overwritten. The same configuration is documented in Bifrost’s Codex CLI guide.

One Codex detail makes the skill’s insistence on device management sensible rather than optional. OpenAI’s project config rules say Codex ignores model_provider, model_providers and openai_base_url in a repository’s .codex/config.toml and prints a warning. Provider settings live only in the user-level file, so the skill tells teams to ship ~/.codex/config.toml through the same MDM channel used for other agents and to treat local edits as drift.

The credential is a Bifrost virtual key, created per developer with a daily and a monthly budget, a request rate limit and an explicit model list. A key with no provider configuration denies every provider, so the allowlist is the default. For CI, the skill prescribes one key per pipeline with a small daily budget and an expiry date, codex exec "<task>" with the key from a CI secret, and a rule to “fail the job, not the budget” when the gateway rejects a request. Its verify step for Codex is /status, which should show the bifrost provider and the intended model.

It also suggests setting per-developer limits “around the 90th percentile of observed daily spend, not a guess.” The Frontier Wire’s guide to AI gateways for Claude Code, Codex and Cursor compares the gateway options in more depth, and the Bifrost CLI piece covers the launcher the skill mentions as a shortcut (bifrost run codex --model openai/gpt-5).

llm-cost-reduction and secure-llm-apps

These two skills target the application Codex is helping to build, not Codex itself. Their descriptions match how developers phrase problems (“surprise LLM bill,” “my OpenAI key leaked”), which is the text implicit selection matches against.

llm-cost-reduction frames cost as requests multiplied by input and output tokens multiplied by price, and attacks each factor in order: measure first, then fix the biggest line item, then verify quality did not drop. Its first step is a seven-part grep that finds every LLM call site and the models they use, calls with no output limit, agent loops without a cap, retry wrappers, missing usage logging, prompt-cache killers such as timestamps in system prompts, and embeddings recomputed on every run. Fixes come with Python and TypeScript code: a usage-logging wrapper, a model right-sizing table backed by an eval set, loop caps on steps and total tokens, prompt trimming, provider prompt caching, response caching, batch APIs and embedding reuse. One gateway detail is directly relevant to Codex users who route Claude models through a gateway: the caching reference notes that clients sending no cache markers, Codex among them, “never get Anthropic-style prompt caching,” and shows how the gateway can inject a breakpoint and keep a session on the same key so the cache it writes is the one it reads. The Frontier Wire’s prompt caching guide covers the provider side.

secure-llm-apps starts from one premise: “The model is not a security boundary.” Its quick diagnosis greps for provider keys in client bundles (NEXT_PUBLIC_, VITE_, dangerouslyAllowBrowser), model output flowing into innerHTML, eval or f-string SQL, tool definitions, missing token caps and prompts written to logs. Seven practices follow, each with code: keys stay on the server, retrieved and tool content is treated as untrusted, tools are least-privilege with human approval for destructive actions, output is validated with pydantic or zod before it reaches a sink, PII is redacted locally with Microsoft Presidio, consumption is bounded per user and tenant, and logs carry metadata rather than content. references/audit-checklist.md maps each check to the OWASP Top 10 for LLM Applications and ends with a report template, which makes it a reasonable $secure-llm-apps pass before a launch review. Background on the threats is in The Frontier Wire’s explainers on prompt injection and the OWASP LLM Top 10.

The other three, briefly

llm-observability-stack defines a fixed record for every LLM call (identity, routing, usage, timing including time to first token, outcome, attribution, gated content), maps it to the OpenTelemetry GenAI semantic conventions, traces an agent run as one root span with a child per model call and tool, and ships PromQL dashboards and alert rules.

mcp-gateway-best-practices inventories every MCP config on a machine, measures the token cost of tool definitions, classifies tools as read, write, destructive or external side effect, and then cuts the surface to a target of “5 to 20 tools per agent task.” It covers tool naming, approval gates in code, transport choice and per-key allowlists. Codex users who connect several MCP servers will find its topology table useful; the Cursor skills guide covers it in depth.

agent-skills-for-teams is the skill about skills: description formulas, a trigger-eval harness, SemVer for skills, a security review checklist and the lint_skills.py linter used in the test above. For Codex teams it documents one more distribution path: Bifrost’s Skills Repository can serve skills as a plugin marketplace that Codex registers with codex plugin marketplace add <url>/api/skills/serve/codex, with immutable versions and a one-step rollback of the served version.

Install the skills for Codex

All six install the same way. Each repository holds one skill at its root, so the plain add command installs it; --list previews first.

# The three most relevant to Codex users
npx skills add build-with-ai-hq/ai-coding-agent-governance -a codex
npx skills add build-with-ai-hq/llm-cost-reduction -a codex
npx skills add build-with-ai-hq/secure-llm-apps -a codex

# The rest of the set
npx skills add build-with-ai-hq/llm-observability-stack -a codex
npx skills add build-with-ai-hq/mcp-gateway-best-practices -a codex
npx skills add build-with-ai-hq/agent-skills-for-teams -a codex

Add -g for a user-wide install in ~/.agents/skills, -y to skip prompts in a setup script, and -a cursor -a claude-code to share one copy with other agents. Then start a new Codex session, run /skills to confirm they are listed, and try a prompt from the table without the $ prefix to see whether implicit matching picks the right one. The Frontier Wire’s explainer on npx skills and skills.sh covers the CLI’s lockfile and update model, and the agent skills for teams guide covers versioning across a team.

Limits worth knowing

A skill is instructions plus optional code, and Codex runs both with the session’s permissions. The CLI’s warning is literal: skills “run with full agent permissions.” Read every file, not just SKILL.md, before installing a third-party skill, pin it with the lockfile, and re-read it on update. agent-skills-for-teams carries a review checklist for exactly this: no curl | sh, no sudo, no reads of ~/.ssh or ~/.aws, every network call documented.

Skills do not enforce anything. ai-coding-agent-governance describes a policy and a configuration; enforcement comes from the gateway rejecting a request over budget and from device management keeping config.toml in place, not from Codex reading a Markdown file.

The six skills are also new: the organization was created in October 2026 and each skill is at version 1.0.0. The test above confirmed that they install, are listed and pass their own linter; it did not measure how often Codex triggers them implicitly or what they change in a real codebase. Run the trigger eval agent-skills-for-teams describes, about 20 should-trigger and near-miss prompts, before relying on implicit invocation.

The Frontier Wire’s take

Codex’s skill system is small and well specified: a folder, two required fields, a scan path that runs up to the repository root, and an index with a hard budget. The budget is the part most teams will feel. Skills that front-load their trigger words and keep their bodies under the spec’s limits get selected; skills that read like product pages get trimmed. For teams building LLM applications, the build-with-ai-hq set is a practical starting point because it packages the infrastructure work (gateway rollout, cost, security) that Codex users are usually the ones asked to do, with exact Codex configuration where it matters. Start with the governance skill if more than a handful of developers use Codex on a shared key: npx skills add build-with-ai-hq/ai-coding-agent-governance -a codex.