Codex Skills: Create, Run, and Verify on a Code Review Task

The Skills Mechanism in Codex

The skills mechanism, described in the official documentation, attaches instructions and templates for specialized tasks to an agent without overloading the system context.

A skill is a directory containing a required SKILL.md file. Its YAML frontmatter requires the name and description fields, while the body contains rules for the model:

.agents/skills/boundary-review/
└── SKILL.md

Codex uses progressive disclosure: at startup, it builds a compact index of available skills. The full text of SKILL.md is read by the agent only when it decides to apply a specific skill.

Skill discovery operates across four levels:

1. Repository (REPO): .agents/skills in the current directory and upwards to the Git root.
2. User (USER): $HOME/.agents/skills.
3. Admin (ADMIN): /etc/codex/skills.
4. System (SYSTEM): environment system directories (bundled).

Invocation is performed either explicitly (via the $name prefix) or implicitly (based on semantic matching between the prompt and the description). Availability and conflicts are managed in the config.toml file.

Prerequisites and Isolation

To reproduce this scenario, the following are required:

• Python 3;
• An installed and authorized Codex CLI command-line interface.

Test data was recorded on 2026-09-16 using Codex CLI version 0.153.3.

All commands are executed in a prepared local directory outside of a Git repository. Because text instructions in SKILL.md direct model behavior but do not guarantee operating system isolation, runs are executed with the following flags:

• --ephemeral: prevents persisting session state;
• --skip-git-repo-check: allows running in an isolated folder without Git;
• --sandbox read-only: restricts process write access at the execution environment level.

The CLI may inherit global configurations and emit service warnings about third-party hooks, so actual verification relies strictly on read events of the target skill.

Creating the boundary-review Skill

Create the skill directory in the current folder:

mkdir -p .agents/skills/boundary-review

Save the following content to .agents/skills/boundary-review/SKILL.md:

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

The text instruction prohibits the model from modifying files and requires it to begin its response with the BOUNDARY_REVIEW signal marker while reporting one failing input value.

Defective Test File

Create a pages.py file with a typical off-by-one error when calculating page counts:

def page_count(total, size):
    return total // size + 1

Under the conditions size > 0 and total >= 0, the function fails on boundary values: with total = 1 and size = 1, it returns 2 instead of 1. Additionally, for an empty list with total = 0, the function will return 1.

Running and Verifying Invocations

Queries are passed in single quotes to prevent the command processor from interpreting the $ symbol as an environment variable.

1. Explicit Invocation by Name

Run an explicit check directly specifying the skill:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

The model returns the result:

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

The presence of the BOUNDARY_REVIEW marker alone does not prove that SKILL.md was loaded, as the marker text could be generated from the prompt’s context. In the actual run from 2026-09-16, the system log recorded a command event reading the file .agents/skills/boundary-review/SKILL.md. The combination of the file-read event in the log, the BOUNDARY_REVIEW prefix, and the page_count(1, 1) counterexample confirms execution of the target instruction.

2. Implicit Invocation by Description

Formulate the task in natural language without mentioning the $boundary-review identifier:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

The log for this run also recorded a read of .agents/skills/boundary-review/SKILL.md, triggered by semantic matching between the query phrase and the description field. The agent generated a similar structured response with the BOUNDARY_REVIEW marker and an analysis of the failure on input (1, 1).

Logic Verification and Reader Steps

Let’s check the original function behavior using a local Python interpreter:

python3 -c "from pages import page_count; print(page_count(1, 1))"

The command outputs 2, confirming the presence of the defect.

During the benchmark run on 2026-09-16, the original pages.py file remained unchanged; no repeated CLI run was performed on the modified file. The mathematical correctness of the proposed formula (total + size - 1) // size for total >= 0 and size > 0 was verified across boundary sets:

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2.

To fix it manually, the reader can update pages.py to:

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

After saving the changes, the reader can execute an assertions check:

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

The expected command output after manually editing the file is OK.

Troubleshooting

If a skill is not discovered or fails to trigger automatically:

1. File path: verify that the path relative to the working directory is exactly .agents/skills/<skill-name>/SKILL.md.
2. Registry refresh: if files were added during an active session, restart the CLI process to rescan directories.
3. Configuration block: check ~/.codex/config.toml. If the skill was disabled, an entry such as:

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   will block it from loading. Remove the block or set enabled = true.
4. Name conflicts: if identical name values exist at both the repository and user levels, precedence rules may lead to ambiguity.
5. Description accuracy: for implicit invocation, key triggers (“pagination boundaries”, “boundary errors”) should be placed near the beginning of the description.
6. Third-party skills: when loading external packages is required, the entry point is the $skill-installer utility. Any third-party skills require a mandatory manual audit of their SKILL.md files and scripts/ directory before execution. In the described scenario, no third-party components were installed.