Codex · Part 5

Codex — Part 5 — Creating a Custom Skill

A Codex Skill packages a repeatable procedure so it runs on demand instead of being re-explained in chat, and a working Windows Event Log triage skill to build one for real.

By K Shankar R Karanth Codex Series Part 5

Quick idea: A Codex Skill is a folder with a SKILL.md file inside it. Codex loads the name and description into every session and only loads the full instructions when the skill actually runs.

SKILL.md

The one required file. Frontmatter tells Codex when to use it, markdown content tells it what to do.

$skill-name

Mention a skill directly by name, or let Codex load it automatically when relevant.

scripts/

An optional folder for executable code, used when a task needs deterministic behaviour rather than prose instructions.

Introduction

Part 4 covered AGENTS.md: facts and standing rules that should be true in every session. A Skill is for the other kind of thing you keep repeating, a procedure. This works essentially the same way in Codex as it does in Claude Code, covered earlier in this site’s other series, right down to the SKILL.md file format.

What Is a Skill?

A Skill is a directory containing a SKILL.md file with name and description frontmatter, followed by markdown instructions for what to do when it runs. Codex can invoke it automatically when your request matches the description, or you can invoke it directly by mentioning $skill-name or browsing /skills.

The folder can also hold a scripts/ directory for executable code, a references/ directory for supporting documentation, an assets/ directory for templates, and an optional agents/openai.yaml file that controls how the skill appears and behaves in the ChatGPT desktop app specifically.

Key point: Codex only loads the name, description, and file path of a skill into context by default, capped at roughly 2% of the context window or 8,000 characters. The full instructions load only once a skill is actually selected.

Where Skills Live

Scope	Path	Applies To
Repo, current folder	`.agents\skills\` under your current working directory	Folder-specific workflows
Repo, root	`.agents\skills\` at the repository root	Whole-repository skills, shared via source control
User	`%USERPROFILE%\.agents\skills\`	Personal, available across every project on your machine

Codex checks these in order, closest to your working directory first, and also scans an admin-level and built-in tier above the ones you would normally touch. Skill folders can be symlinked, and Codex follows the link.

A Worked Example: Event Log Triage

This mirrors the same skill built in the Claude Code series, adapted to how Codex actually structures a skill: instructions in SKILL.md, the command itself in a separate script file, rather than embedded inline.

# %USERPROFILE%\.agents\skills\check-eventlog\SKILL.md

---
name: check-eventlog
description: Summarizes recent errors and warnings from a Windows Event Log and flags anything worth investigating. Use when asked to check the event log, review recent errors, or find out what broke.
---

# Instructions

1. Run `scripts/check-eventlog.ps1` to collect recent System log errors and warnings.
2. Summarize the output in a short list grouped by likely cause.
3. Flag anything that repeats more than twice, and call out any event ID
   that commonly indicates a hardware, disk, or service failure.
4. If there are no errors or warnings, say the log is clean.

# %USERPROFILE%\.agents\skills\check-eventlog\scripts\check-eventlog.ps1

Get-WinEvent -LogName System -MaxEvents 50 |
  Where-Object { $_.LevelDisplayName -in 'Error','Warning' } |
  Select-Object TimeCreated, Id, LevelDisplayName, Message |
  Format-List

Important: Codex’s own guidance is to prefer prose instructions over scripts unless the task genuinely needs deterministic behaviour or external tooling. A fixed data-collection step like this one is exactly the case scripts are for; the summarising and judgement calls stay in the instructions.

Testing It

what broke on this server recently?

That should trigger the skill automatically, matching the description. To run it explicitly instead, mention it directly or browse the list:

$check-eventlog

/skills

Key point: Codex detects new and edited skill files automatically in most cases. If a change does not seem to take effect, restart the session.

Controlling Who Invokes It

By default, both you and Codex can trigger a skill. For anything with a real side effect, an optional agents/openai.yaml file alongside SKILL.md can require an explicit mention instead.

# agents/openai.yaml
policy:
  allow_implicit_invocation: false

With that set, Codex never decides on its own that now is a good moment to run the skill. You still can, any time, by mentioning it directly.

Final Thoughts

Skills work almost identically across Codex and Claude Code at the concept level: a folder, a description that controls matching, instructions that only cost context once actually used. The differences are in the file layout, .agents/skills instead of .claude/skills, a separate scripts folder instead of inline shell injection, and an explicit invocation policy file instead of a single frontmatter flag.

A single skill running inline covers most needs. The next step up, in Codex as in Claude Code, is delegating a task to a separate agent thread entirely.

Key takeaway: If you keep re-typing the same procedure into chat, save it as a Skill. Put the fixed data-collection step in scripts/, keep the judgement calls in SKILL.md, and set allow_implicit_invocation: false for anything with a real side effect.

Next in this series

Next, we look at subagents: running a task in an isolated agent thread so a deep investigation does not fill up your main session with intermediate noise.