Skip to content
AgentAtlas

Codex skills: create SKILL.md, skill folder locations and $skill invocation

How do I create and use skills in Codex?

A Codex skill is a folder with a SKILL.md file whose YAML frontmatter has a name and a description. Put it in .agents/skills in your repository or in ~/.agents/skills for all projects. Call it with /skills or by typing $ and the skill name, or let Codex pick it when your task matches the description.

Compare: Agent Skills (SKILL.md) in every AI coding agent →

What a skill contains

  • SKILL.md (required): instructions plus YAML frontmatter with name and description. The description should say when the skill should and should not trigger.
  • scripts/ (optional): executable code.
  • references/ (optional): documentation.
  • assets/ (optional): templates and other resources.
  • agents/openai.yaml (optional): UI appearance, invocation policy and tool dependencies.

.agents/skills/release-notes/SKILL.md

---
name: release-notes
description: Draft release notes from recent commits. Use when the user asks for release notes or a changelog. Do not use for code changes.
---

1. Read the commits since the last tag.
2. Group changes into Features, Fixes and Other.
3. Write the notes in plain Markdown.

Where to put skills

  • $CWD/.agents/skills: the folder where you launch Codex.
  • $CWD/../.agents/skills: parent folders, when you launch inside a Git repository.
  • $REPO_ROOT/.agents/skills: the top of the repository.
  • $HOME/.agents/skills: your personal skills for every project.
  • /etc/codex/skills: admin-installed skills.
  • System skills bundled with Codex.

Codex scans .agents/skills from the current folder up to the repository root. Skills with the same name are not merged; both appear in the selector. Symlinked skill folders work.

Run a skill

  • Explicit: in the Codex CLI or IDE extension, run /skills or type $ and the skill name.
  • Implicit: Codex may choose a skill on its own when the task matches its description.

Build a new skill with the built-in helper

$skill-creator

Install a curated skill

$skill-installer linear

Turn off implicit use or disable a skill

To stop Codex from picking a skill on its own, set policy.allow_implicit_invocation to false in agents/openai.yaml. Explicit $skill calls still work.

agents/openai.yaml

policy:
  allow_implicit_invocation: false

To disable a local skill completely, add a [[skills.config]] entry to ~/.codex/config.toml and restart Codex.

~/.codex/config.toml

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Limits and reloading

  • Codex detects skill changes automatically. If an update does not show, restart Codex.
  • The initial skills list is capped at 2% of the context window, or 8,000 characters if the window size is unknown. With many skills installed, Codex shortens descriptions first.
  • To share skills with others, package them in a plugin.

Sources

More Codex guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →