Codex skill not triggering? How to diagnose and fix it

First, split the problem in two

Every “skill not triggering” report is one of two problems, and one test tells you which:

/skills

Then try the skill explicitly:

$your-skill-name do the thing

Result	Problem	Go to
Not in /skills, $ mention does nothing	Discovery: Codex does not see the skill	Discovery checks
Listed, works with $, never loads on its own	Matching: Codex sees it but does not pick it	Matching checks
Loads, but Codex ignores parts of it	Instructions: the body is unclear or too long	The skill loads but is ignored

Discovery checks

1. The path is right, one level deep. Codex expects <skills-dir>/<name>/SKILL.md:

ls ~/.agents/skills/*/SKILL.md
ls .agents/skills/*/SKILL.md

Common mistakes: SKILL.md placed directly in skills/, an extra folder from unzipping (skills/foo/foo/SKILL.md), or a file named something other than SKILL.md, such as README.md or skill.md.

2. The folder is in a scanned location. Codex reads .agents/skills from the working directory up to the repository root, then ~/.agents/skills, /etc/codex/skills and its bundled skills. A skill in packages/api/.agents/skills is invisible when you start Codex at the repository root, because Codex walks up from where you start, not down. Start Codex in the package (codex --cd packages/api) or move the skill to the root .agents/skills.

3. The frontmatter parses. Line 1 must be ---. name and description must both exist. An unquoted description containing : breaks YAML; quote it:

description: "Generates migrations. Note: never for production data fixes."

4. The name follows the rules. Lowercase letters, digits and hyphens, at most 64 characters, matching the folder name.

5. It is not disabled. Look in ~/.codex/config.toml for a [[skills.config]] entry pointing at the skill with enabled = false.

6. Symlinks resolve. Codex follows symlinked skill folders, but a link that points at a moved or deleted directory leaves nothing to load. ls -L ~/.agents/skills/<name>/SKILL.md checks the target.

7. Restart. Codex picks up changes automatically, but if a skill still does not appear, restart Codex. Skills bundled in a plugin appear in the next session after install, and plugins are not available in the IDE extension at all.

8. Cloud tasks. In Codex cloud, only skills committed to the repository are available. Personal skills from your machine are not synced.

Matching checks

When a skill is listed but never chosen, the description is almost always the cause. It is the only text Codex considers when deciding whether to load a skill.

Lead with the job. Codex shortens descriptions when the catalog is crowded, and OpenAI’s guidance is to front-load the key use case and trigger words so a skill still matches after shortening. Put what the skill produces in the first clause.

Use the words people type. Compare:

# Rarely triggers
description: Assists with quality assurance processes for web interfaces.

# Triggers on real requests
description: Writes and fixes Playwright end-to-end tests - locators, auto-waiting, fixtures, traces and flaky test fixes. Use when the user mentions Playwright, e2e or end-to-end tests, browser tests, or a test that times out waiting for an element.

Include file types, tool names, error messages and verbs: “migrate”, “review”, “fill this form”, “the build fails with”.

Check for a competing skill. If two skills claim the same territory, Codex picks one, and it may not be yours. Add a boundary to each: “Not for unit tests; use vitest-testing.”

Check the invocation policy. If the skill has agents/openai.yaml with this, implicit invocation is off by design:

policy:
  allow_implicit_invocation: false

That is right for skills with side effects (deploys, publishing) and wrong for everyday ones.

Test like a user. Start a fresh session for each test prompt, phrase requests the way you naturally would, and keep a short list of prompts that should and should not trigger. The skill-description-tuning skill runs this loop with you, and skill-evals turns it into a repeatable test.

The context budget

Codex does not hand the model every skill in full. It builds a catalog of each skill’s name, description and file path, and that catalog has a budget:

Setting	Default
Catalog budget	2% of the model’s context window
Fallback when the window size is unknown	8,000 characters
Maximum you can configure	10,000 tokens via skills.max_context_tokens

When installed skills exceed the budget, Codex shortens descriptions first. With large sets, it may leave some skills out of the catalog entirely and show a warning. A skill that is not in the catalog cannot be chosen implicitly. If you missed the startup warning, /warnings shows warnings retained for the session.

Fixes, in order of preference:

1. Install fewer skills. Remove ones you have not used in a month.

2. Disable skills per machine with [[skills.config]] instead of deleting shared ones:

   [[skills.config]]
   path = "/Users/you/work/repo/.agents/skills/legacy-deploy/SKILL.md"
   enabled = false

3. Shorten long descriptions across your own skills. Two tight sentences beat a paragraph.

4. Raise the budget if your model’s context window can afford it:

   [skills]
   max_context_tokens = 8000

The budget applies only to the catalog. Once a skill is selected, Codex reads its full SKILL.md regardless.

To see exactly what the model receives, run codex debug prompt-input from the same directory you start Codex in. It prints the first-turn context as JSON, including the skills list with each name, description and file path as the model sees it:

codex debug prompt-input "write the PR description" | grep -o 'pr-description[^"]*'

If your skill is missing from that output, it is a discovery or budget problem. If it is there but its description is cut short, shorten it or reduce the number of installed skills.

When to stop tuning and mention it

Implicit invocation is a convenience. For workflows where you always want a specific skill, say it:

$zero-downtime-migrations add a NOT NULL column "region" to orders

$name and the /skills picker load the skill regardless of how the request is worded. Many teams write the explicit mention into their habits for high-stakes skills (migrations, releases, security reviews) and rely on implicit matching for everyday ones.

You can also point to a skill from AGENTS.md: “For database migrations, use $zero-downtime-migrations.” That line is in context on every task and nudges Codex toward the skill.

The skill loads but is ignored

If Codex clearly loaded the skill (it mentions it, or you invoked it with $) but skipped steps:

• The body is too long. Codex reads the whole file once it is selected; a 900-line skill buries the important parts. Move detail into references/ and keep the main file under about 500 lines.
• The steps are vague. “Ensure quality” is not a step. “Run pnpm test and paste the summary line” is.
• There is no definition of done. Put one at the top.
• AGENTS.md contradicts it. Instructions that load on every task can override the skill. Check for conflicts.
• The step needs approval. A script that needs the network will stop at an approval prompt under the default sandbox. Either approve it, or note in the skill that it needs network access.

Over-triggering

The opposite problem: a skill loads for requests it should not handle. Narrow the description to concrete triggers, add an explicit “Not for …” sentence naming the neighboring skill, and if it has side effects, turn implicit invocation off.

Quick checklist

Check	Command or place
File exists at the right depth	ls ~/.agents/skills/*/SKILL.md
Started Codex in the right directory	/pwd shows the working directory
Frontmatter valid	Line 1 is ---; quote values with colons
Not disabled	[[skills.config]] in ~/.codex/config.toml
Implicit allowed	policy.allow_implicit_invocation in agents/openai.yaml
Description leads with the job and trigger words	SKILL.md frontmatter
Skill appears in the model’s context	codex debug prompt-input
Catalog not over budget	Fewer skills or skills.max_context_tokens
Restarted after changes	Restart Codex or start a new session

For the format itself, see the SKILL.md reference.