Codex skill examples: eight patterns from real skills, annotated

How to read these examples

Each example below is a pattern pulled from a working skill in this catalog, with a short excerpt, what it does for Codex, and how to reuse it. They are ordered roughly from the top of a SKILL.md to the bottom. Most good skills use four or five of them.

If you are starting from scratch, read the SKILL.md reference for the format and the first skill tutorial for the workflow; come back here for structure.

1. A description that says what and when

From pytest-testing:

description: Writes and organizes pytest suites - fixtures with the right scope and
  yield teardown, conftest.py layering, parametrize with ids and indirect fixtures,
  ... Use when a Python project tests with pytest, when fixtures leak state between
  tests, tests pass alone but fail together, parametrized cases are unreadable, or
  the suite is slow and needs parallelism.

Why it works. The first clause names the job. The middle names the concrete things a user might mention (conftest.py, parametrize). The “Use when” sentence lists symptoms in the user’s words: “tests pass alone but fail together” is exactly what someone types when they have a fixture leak. Codex decides implicit invocation from this text alone, so symptoms are worth more than adjectives.

Reuse it. Write the job first, then the nouns, then three to five symptoms or requests.

2. A definition of done at the top

From systematic-debugging:

Done means three things are true: you can state the causal chain from trigger to symptom
in two sentences, a check that failed before your change passes after it, and the diff
contains nothing that the explanation does not require.

Why it works. An agent needs to know when to stop. Without this, “fix the bug” ends when the error message changes. With it, Codex has three checks it can verify and report. It also rules out the most common bad outcome (a diff full of unrelated edits) before any work starts.

Reuse it. Open every skill with one paragraph that starts “Done means”.

3. Inspect before acting, with non-interactive commands

From git-commit-hygiene:

2. Look at the whole tree, not just what you remember editing:

```bash
git status --porcelain=v1
git diff --stat
git diff --cached --stat        # anything already staged by someone else?
```

The same skill stages hunks with git apply --cached rather than git add -p.

Why it works. Interactive commands like git add -p or git rebase -i wait for keyboard input, which an agent handles poorly and can get stuck on. The skill gives commands that produce machine-readable output and need no input. The inspection step also catches files Codex did not create, which is where accidental commits of .env files come from.

Reuse it. Before any step that changes state, add a step that reads state. Prefer --porcelain, --json and other scriptable output.

4. A decision table instead of prose

From codex-sandbox-approvals:

| Task | Sandbox | Approvals | Flags |
|---|---|---|---|
| Explore, explain, plan; no edits | `read-only` | `on-request` | `codex -s read-only -a on-request` |
| CI analysis, reports, reviews | `read-only` | never asks (exec default) | `codex exec` (read-only by default) |
| CI that edits the checkout | `workspace-write` | never asks | `codex exec -s workspace-write` |

Why it works. When a skill has to choose between options, a table maps situations to answers in a form the model applies reliably. Paragraphs of “it depends” lead to hedged output; a row lookup leads to a decision.

Reuse it. Any time your instructions say “if X, do A; if Y, do B” more than twice, make it a table.

5. A reference file loaded only when needed

From zero-downtime-migrations, whose folder holds references/lock-matrix.md:

3. Classify each statement with [references/lock-matrix.md](references/lock-matrix.md)
   (read it for any statement not covered in the quick table).

Why it works. The full lock matrix for PostgreSQL DDL is long and needed only for unusual statements. The main file carries a quick table for common cases and tells Codex exactly when to open the reference. That keeps the body small, since Codex reads the whole SKILL.md every time the skill loads, while the detail is one relative link away.

Reuse it. Link references with a condition (“if the form uses XFA, read …”) and keep them one level deep.

6. A bundled script with honest limits

From sql-query-review, which ships scripts/sql_risk_scan.py:

2. **Scan.** For files, run the bundled heuristic scanner to get a starting list:

```bash
python3 scripts/sql_risk_scan.py db/migrations/ reports/monthly.sql
```

   It is regex-based: confirm every hit by reading the statement, and do not treat a
   clean scan as a pass.

The script uses only the Python standard library and exits 1 when it finds a high-severity issue.

Why it works. Scanning dozens of files for UPDATE without WHERE is mechanical; a script does it identically every time and costs no context. The instructions then say what the script cannot do, so Codex treats its output as a lead, not a verdict. Standard-library-only means no install step and nothing that needs network access inside the sandbox.

Reuse it. Script the deterministic part, keep judgment in the instructions, document exit codes, and avoid dependencies where you can. Scripts run under your sandbox and approval policy like any other command.

7. An output contract

From owasp-top-10-review:

#### [Critical] A01 Broken Access Control — IDOR on order lookup
- Location: `routes/orders.js:42`
- Untrusted input: `req.params.id` (any authenticated user)
- Sink: `Order.findById(req.params.id)` returned without owner check
- Impact: any user reads any order (PII, totals)
- Fix: ...
- Status: confirmed by code path

Why it works. A fixed format makes results comparable across runs and easy to scan. Each field forces evidence: a location, the input, the sink. A finding that cannot fill those fields is probably not a finding. It also makes the output usable by scripts if you run the skill through codex exec.

Reuse it. End the skill with an “Output” section showing a filled-in example, not just a list of headings.

8. Hard rules, and an explicit-only skill

From git-commit-hygiene:

- Never commit with `--no-verify` to get past hooks unless the user explicitly asks; fix
  what the hook reports.
- Never commit secrets. If one was committed, stop and tell the user: removing it from
  history is not enough, the secret must be rotated.

Why it works. Short “never” rules cover the failure modes that matter most and that a helpful agent is most tempted toward, such as bypassing a failing hook to finish the task. Each rule says what to do instead.

For skills where the whole workflow has side effects, go one step further and make the skill explicit-only. A minimal example of your own:

deploy-preview/
├── SKILL.md
└── agents/
    └── openai.yaml

# agents/openai.yaml
interface:
  display_name: "Deploy preview"
  short_description: "Deploy this branch to a preview environment"
policy:
  allow_implicit_invocation: false

With implicit invocation off, Codex loads the skill only when someone types $deploy-preview, so a request like “can you check the preview build?” will not start a deployment.

Putting the patterns together

A skeleton that combines them:

---
name: your-skill
description: <Job in one clause>. <Concrete nouns>. Use when <symptom>, <request>, or <error text>. Not for <neighbor>; use <other-skill>.
---

# Your skill

Done means: <two or three verifiable conditions>.

## Before you start
1. Read AGENTS.md. <Inspect state with scriptable commands.>

## Decide
| Situation | Do this |
| --- | --- |

## Steps
1. ... (If <rare case>, read references/<file>.md.)
2. Run `scripts/<tool> <args>`; exit code 1 means <meaning>.

## Hard rules
- Never ... ; instead ...

## Output
<filled-in example>

Browse more complete examples in the Codex Power User and Starter Pack collections, or install one and read it locally:

curl -fsSL https://codexskills.dev/install.sh | sh -s -- sql-query-review
ls -R ~/.agents/skills/sql-query-review