Give Codex project rules and reusable skills

Codex can inspect a repository and carry a task through changes and checks. Give it the local facts that are easy to guess incorrectly: where the code lives, how to run the checks, and which interfaces the task must preserve.

Check which instructions apply

Codex builds its instruction chain at startup. It reads global guidance, then project guidance from the root toward the working directory. An AGENTS.override.md takes precedence over AGENTS.md at the same level; later project guidance can override earlier guidance.

That is a discovery rule tied to the working directory. Do not assume opening an arbitrary nested file loads a new instruction chain automatically.

Begin a session from the intended directory and ask:

Identify your working directory and the instruction files that apply. List the build and check commands from those files. Flag conflicts or missing commands before choosing a way to verify the task.

Inspect the named files yourself if the answer is surprising.

Write rules that help an actual change

For a static documentation site, a short root file might say:

# Project instructions

- Guide source lives in src/guides; generated output lives in dist.
- Use npm test for content, build, and browser-behavior checks.
- Register new article identities with npm run register:content.
- Keep provider-specific instructions scoped to their actual product.
- Include canonical-route changes in the migration map and check old links.
- Report failed or unavailable checks with the final diff.

These are example commands for this repository. Replace them with the actual commands in yours. Keep a task-specific approval or exception in the task record, with its scope, instead of quietly rewriting the general rule.

Package a proven routine

Suppose checking a translated page repeatedly requires the same steps: compare its required sections, inspect source links, build both locales, and check language navigation. Perform that routine successfully before making a skill.

A repository skill can live at .agents/skills/check-translated-guide/SKILL.md:

---
name: check-translated-guide
description: Check a changed English/German guide pair for missing sections, broken links, and language navigation.
---

Below that header, describe the inputs, procedure, required tools, and final report. Reference an existing script where a deterministic check already exists. Codex supports explicit skill invocation with $ and local skill discovery under .agents/skills. A skill supplies instructions; access still comes from the session's tools and permissions.

What goes wrong

A long instruction file accumulates conflicting history. A nested rule can be absent from the startup chain. A skill that merely says "review thoroughly" provides no repeatable procedure or completion criterion.

Correct the specific cause: remove the obsolete rule, restart from the right directory, or define the skill's observable output. Adding more instruction text to every task usually hides the original problem.

How to check

Give Codex a small change with one deliberate convention mismatch. Verify that it identifies the applicable rule and runs the real checks. Test the skill on one good translation and one with a missing link or section.

Review the reported failures against the files. Success means the routine detects a known problem and leaves enough evidence for another person to check.