Codex Skills: Teaching the Agent Your Conventions

What Is a Codex Skill

A Codex skill is a folder containing a SKILL.md file, made up of YAML frontmatter and Markdown instructions, plus any scripts, references, or templates the procedure needs. The frontmatter requires two fields, a name and a description, and the description is what decides when the skill fires.

OpenAI's Codex skills documentation describes skills as a way to package "instructions, resources, and optional scripts so either product can follow a workflow reliably," and names the use case directly: skills codify processes and conventions, from company style guides to multi-step workflows. Encoding your team's standards is therefore the headline use case rather than a creative reading of the feature.

Here is the frontmatter from a real production skill, the Playwright skill TestMu AI publishes in its open-source agent skills repository:

---
name: playwright-skill
description: >
  Generates production-grade Playwright automation scripts and E2E tests
  in TypeScript, JavaScript, Python, Java, or C#. Supports local execution
  and TestMu AI cloud across 3000+ browser/OS combinations and real mobile
  devices. Use when the user asks to write Playwright tests, automate
  browsers, run cross-browser tests, test on real devices, debug flaky
  tests, mock APIs, or do visual regression. Triggers on: "Playwright",
  "E2E test", "browser test", "run on cloud", "cross-browser", "TestMu",
  "LambdaTest", "test my app", "test on mobile", "real device".
languages:
  - JavaScript
  - TypeScript
  - Python
  - Java
  - C#
category: e2e-testing
license: MIT
---

Two things in that block are worth copying. The description spends most of its length on when to use the skill rather than what it is, and it ends with a literal list of trigger phrases. Both choices exist because the model has nothing else to go on at selection time. If you have not yet worked with this format, the broader case for it is covered in how agent skills make AI reliable for test automation.

Where Codex Skills Live on Disk

Current Codex builds look for skills in .agents/skills, checked at several scopes in order. A folder placed there is treated as a skill with no registration step and no restart.

This is the detail most existing write-ups get wrong, because the earliest experimental support used a Codex-specific directory before the format converged on a shared one. Per the Codex skills documentation cited above, the search locations are:

The practical consequence sits in the first and third rows. A convention skill committed to the repository is versioned with the code it governs, arrives with every clone, and applies in continuous integration exactly as it does on a laptop. A convention kept at user scope protects only the person who wrote it.

Why Conventions Belong in a Skill Rather Than AGENTS.md

AGENTS.md is always-on context. Everything in it competes for room in every request, whether the task is a database migration or a copy change, which is why long convention files tend to get skimmed rather than followed. Skills invert that arrangement through progressive disclosure, a three-stage model the Agent Skills specification defines as discovery, activation, and execution: agents load only the name and description of each skill, read the full SKILL.md once a task matches, and run bundled code only if the instructions call for it.

The budget is explicit. The Codex skills documentation caps the startup skills listing at 2% of the model's context window, or 8,000 characters when the window is unknown, and lifts that constraint once a specific skill is selected. The economics of that are easier to see against a real skill on disk than in the abstract:

$ find playwright-skill | sort
playwright-skill
  |-- SKILL.md
  |-- reference
    |-- api-mocking-visual.md
    |-- cloud-integration.md
    |-- csharp-patterns.md
    |-- debugging-flaky.md
    |-- java-patterns.md
    |-- mobile-testing.md
    |-- page-object-model.md
    |-- playbook.md
    |-- python-patterns.md
  |-- scripts
    |-- scaffold-project.sh
    |-- validate-config.py
  |-- templates
    |-- lambdatest-setup.ts
    |-- playwright.config.ts

$ find playwright-skill -type f | wc -l
14

$ du -sh playwright-skill playwright-skill/SKILL.md playwright-skill/reference
124K    playwright-skill
12K     playwright-skill/SKILL.md
88K     playwright-skill/reference

That is 124 KB of encoded expertise across 14 files, of which 88 KB sits in reference/ and is read only when the agent needs a specific pattern. The portion competing for the startup budget is the ten-line description shown earlier. Put the same material in AGENTS.md and all 124 KB fights for context on every unrelated request, which is also how teams burn through their usage faster than expected, as covered in checking and stretching your Codex usage limits.

A workable split: keep AGENTS.md for the handful of facts that apply to literally every request, such as the package manager, the test command, and the branch naming rule. Move anything conditional into a skill, because a convention that applies to one subsystem should not tax every prompt about the other nine.

How to Write a Codex Skill for Your Conventions

Start from evidence rather than from an idea of what the agent should know. The convention worth encoding first is whichever one you have corrected most often in review over the past month.

• Pick a repeating correction - search your merged pull requests for the comment you have left more than three times. That is a convention the codebase never wrote down, which is exactly why the agent keeps missing it.
• Create the folder at repository root - a directory under .agents/skills named for the procedure, not for the team that owns it, since the name is part of what the model matches against.
• Write the description before the body - it is the only part read at selection time, so drafting it first keeps the scope honest and stops the skill sprawling into three procedures wearing one name.
• Write the body as a procedure - numbered steps with a concrete example of the correct output beat a list of principles, because "handle errors consistently" is unenforceable and a worked example is copyable.
• Move bulk detail into reference files - language-specific patterns and long tables belong beside SKILL.md rather than inside it, so activation stays cheap and the detail is still one hop away.
• Put deterministic work in a script - if a step can be checked by running something, ship the script and have the skill call it, so the outcome does not depend on the model reasoning correctly that time.

A convention skill for the endpoint problem in the opening looks like this:

---
name: service-endpoint-conventions
description: >
  Adds or modifies HTTP endpoints in the billing service using this team's
  error envelope, HTTP client, and test layout. Use when the request involves
  adding an endpoint, changing a route, editing a controller, or writing
  request tests. Triggers on: "endpoint", "route", "controller", "handler",
  "API method". Does NOT cover database migrations or GraphQL resolvers.
---

# Endpoint conventions

## Steps

1. Read reference/error-envelope.md and match the existing shape exactly.
2. Use the shared http client from lib/http. Do not import axios or fetch.
3. Register the route in routes/index.ts, alphabetically by path.
4. Add a request test beside the handler as <name>.request.test.ts.
5. Run scripts/check-endpoint.sh and fix anything it reports.

## Correct output

See reference/example-endpoint.ts for a handler that satisfies all five
rules. Match its structure rather than paraphrasing it.

Note the negative clause in the description. Stating what the skill does not cover is the cheapest way to stop two skills competing for the same request, and it costs one line. For the broader question of which conventions are worth formalising in the first place, our guide to coding standards and best practices is a useful checklist to draw from.

Conventions worth encoding are not only about source code. Quality teams own a set of written standards that agents break just as readily, and these translate into skills cleanly because each one is already a procedure with a defined output:

• Bug report structure - the reproduction steps, environment fields, and severity wording your tracker expects, so an agent filing an issue produces something triage can act on immediately.
• Severity and priority definitions - the actual rubric your team applies, which stops the agent inventing its own scale every time it classifies a failure.
• Test naming and placement - where a new test belongs and how it is named, which is the convention most often broken when an agent adds coverage to an unfamiliar suite.
• Release readiness checks - the specific gates that must be green before a change is called done, encoded as steps rather than left as a wiki page nobody opens.

How to Make Codex Actually Trigger the Skill

A skill that never fires is worse than no skill, because it creates the belief that the convention is handled. Codex activates skills two ways: explicitly, when a developer names the skill with an @ or $ reference, and implicitly, when the model matches the request against the skill description on its own.

Implicit matching is the one that matters for conventions, because the requests that break your standards are the ones where nobody remembered a standard applied. OpenAI's guidance for making that reliable is to front-load the key use case and trigger words, and to give the skill clear scope and boundaries.

Test selection before you trust it. Open a fresh session, phrase a request the way a teammate naturally would rather than the way the description is written, and confirm the skill is chosen. If it is not, the description needs the words your teammate actually used.

Can Codex Use Claude Skills

Yes. The Agent Skills format was originally developed by Anthropic and released as an open standard, and Codex reads that same format, so a SKILL.md written for Claude Code works in Codex without being rewritten.

What travels is the format: the folder layout, the frontmatter contract of a name and description, and the progressive-disclosure loading model. What does not travel automatically is placement, since each tool searches its own configured locations, and any instruction inside the body that assumes a specific tool's command set. A skill that says "run the repository test command" is portable, while one that hardcodes a vendor-specific slash command is not.

That portability is why tooling vendors now ship skills rather than per-agent plugins. TestMu AI distributes Kane CLI as an installable skill for Claude Code, Codex CLI, and Gemini CLI from one source, which is the same pattern you should follow for internal skills: write the procedure once, place it where each agent looks. A wider view of how these agents differ in practice is in our roundup of agentic coding CLI tools.

How to Verify the Agent Followed Your Conventions

A skill raises the probability that generated code matches your standards. It does not guarantee it, and it says nothing at all about whether the result works. Skills influence a model, and a model can still be selected against, skimmed, or overridden by a strongly worded request.

Split verification by what kind of convention you encoded:

• Structural conventions - file placement, import rules, and naming are decidable from the source, so a lint rule or a script called by the skill catches violations at zero marginal cost.
• Contract conventions - error envelopes and response shapes are best pinned by a schema test that fails loudly when the shape drifts, rather than by a reviewer noticing.
• Behavioural conventions - anything about what the user ends up seeing cannot be settled by reading source at all, and needs the finished flow executed in a real browser.

That third category is where agent workflows usually stop short, because the agent's own verification tools all operate on text. The TestMu AI Kane CLI documentation states that "Claude Code, Codex CLI, and Gemini CLI can invoke Kane CLI directly to test and verify UIs on your behalf," which lets the agent close its own loop rather than handing an unverified diff to a human:

npm install -g @testmuai/kane-cli

kane-cli run --agent --headless \
  "Open the billing page, submit the upgrade form with an expired card,
   and confirm the shared error envelope renders with a retry link"

Because Kane CLI drives real Chrome through the Chrome DevTools Protocol and returns evidence-backed verdicts rather than a model's opinion, the pass or fail comes from something the coding agent did not produce. That independence is the whole point, and it is the reason self-review by the same agent falls short, as covered in whether coding agents can test their own code. For coverage beyond a local browser, those same flows run across 3,000+ browser and OS combinations and 10,000+ real devices on the TestMu AI cloud.

What to Ship First

Open your last twenty merged pull requests and find the comment you wrote more than three times. Write that one convention as a single skill in .agents/skills at your repository root this week, with a description naming the words your teammates actually type and one line stating what it does not cover.

Then check that it fires. Open a clean Codex session, make the request the way a colleague would phrase it, and confirm the skill is selected before you assume the convention is enforced. One skill that reliably triggers is worth more than a directory of thorough ones the model never picks.

Pair it with execution from day one, since a convention that is followed in the diff and broken in the browser is still a bug. Install Kane CLI as a skill from the getting-started documentation linked above, let Codex invoke it after each change, and keep the evidence attached to the pull request where a reviewer can see it.