# Build a Codex skill from work you have already accepted

> Trace an accepted artifact back to its real input, write a new Codex skill from the repeatable steps, then check it on a second task and revise an observed defect.

By BIG CHANGE Editorial

Published: 2026-10-21T21:29:38.580Z
Updated: 2026-10-21T21:29:38.580Z
Canonical: https://bigchange.ai/blog/codex-skill-from-accepted-work-guide

![Conceptual charcoal illustration of a metal contour gauge pressed against the curved edge of a wooden profile on a workbench.](https://bigchange.ai/api/media/file/skill-pattern-contour-gauge-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

OpenAI's [Build skills manual](https://learn.chatgpt.com/docs/build-skills.md) lets Codex use a local `SKILL.md` as a reusable procedure. The hard part is deciding what that file should say. Start with a piece of your own work that someone has actually accepted, trace it back to the real input, and find out which actions and checks can survive a different assignment. The result is a new skill for your task, rather than a copy of the first output.

This guide is for a Codex CLI or IDE user who can reuse the source material, save a local skill, and try it on a second permitted instance. You need the accepted artifact, its actual input and work record, the person responsible for acceptance, and a second real input. If those are missing, establish them before writing instructions. BIG CHANGE has not run the procedure or tested a reader's skill.

## The big change

- **What changed:** Codex can load a local procedure from `SKILL.md`; a user can derive that procedure from the decisions and checks behind work already accepted, instead of starting with generic instructions.
- **Why it matters:** Tracing each accepted feature to its source and rule gives the next run something specific to follow and the owner something concrete to inspect. The saved file alone does not establish that it works on new input.
- **What to watch:** The second real task and a nearby request outside the skill's scope reveal whether the instructions transfer and whether selection stays bounded. Keep a revision only after checking actual output and selection evidence.

## 1. Reconstruct the work that passed

Open the accepted artifact alongside the input it came from. Record its exact version or path, who accepted it, when, and what made it acceptable. Ask that person to turn a general approval into observable checks: which sections, facts, formatting, or decisions must be right, and which failures would cause rejection? An attractive finished file alone does not reveal the steps that produced it.

For each important feature of the output, fill a derivation record from your own materials:

| Accepted output feature | Actual source and input location | Action or decision that produced it | How it was checked | Reusable step or one-off fact? |
| --- | --- | --- | --- | --- |
| [Fill from the accepted artifact] | [Fill from its real input] | [Confirm with the owner or work record] | [Record the acceptance check] | [Classify] |

The bracketed cells are deliberately empty. Do not infer an unseen action from the result. Check the original work record or ask the workflow owner; leave unresolved steps marked unknown. Keep names, dates, figures, private content and task-specific conclusions in future inputs. Put only stable actions and checks in the skill. Have the owner confirm the reconstructed order before you author it.

## 2. Define the next run before writing the skill

Choose a second actual, authorized input now. Write down what the skill may read and change, the required input format and rights, the output location and shape, and the owner's pass/fail checks. Name decisions that still require human judgment. Specify when Codex must stop, such as a missing source, conflicting evidence, or an action beyond the user's permission. A skill supplies instructions; it does not grant access or authorize a send, release, or other external action.

Give the procedure one job and a clear trigger. Also write down a nearby request that should not select it. That negative case helps distinguish a useful description from one that matches every task in the same broad field.

## 3. Save a new `SKILL.md`

The [current manual](https://learn.chatgpt.com/docs/build-skills.md) says Codex searches `.agents/skills` from the working directory up to the repository root. For a personal skill, use `~/.agents/skills`. Choose the scope and a unique name deliberately; skills with duplicate names can both appear. Save a copy of the first version so later changes can be reviewed. If you already have a procedure to install and check, [our earlier Codex guide](https://bigchange.ai/blog/codex-noncoding-files-image-gmail-schedule-guide) walks through that supplied-skill task; here you are authoring a new procedure from your own accepted work.

Create a named folder in that location and put `SKILL.md` inside it. The following is an **unfilled scaffold**, not a demonstrated working skill. Replace every bracketed item using the confirmed record; do not run it as written.

```markdown
---
name: [unique-lowercase-skill-name]
description: [Use for this one recurring task with its required input. Exclude the nearby different task.]
---

# Outcome
[The owner-confirmed reusable result]

## Required input and authority
[Real source, input format, rights, permitted reads and writes; stop if missing]

## Procedure
1. [First confirmed action, with its source and decision rule]
2. [Next confirmed action]

## Output and checks
[Save location and shape; objective checks and named human review]

## Recovery
[What to inspect, what to hold, and when to ask the owner]
```

The required YAML fields are `name` and `description`. Make the description precise enough for Codex to select the skill for the right task and leave it alone for the nearby one. The body should say what inputs to inspect, in what order to act, what to save, how to check it, and when to stop. Start with instructions alone; add scripts, references or other files only when their purpose and behavior have been reviewed. OpenAI also offers `$skill-creator` to draft a skill from a working example, but you still need to compare its saved file with your confirmed procedure.

Reopen the exact saved file. Trace every step and acceptance check back to your derivation record. Replace vague directions such as “make it like the example” with the actual rule. Remove first-instance facts that the second input must supply anew. Confirm the path, metadata and any optional command against the current manual and your permissions.

## 4. Transfer it to real work and inspect the result

In Codex CLI or the IDE, use `/skills` to check discovery, then mention your skill explicitly as `$name` in a prompt for the second authorized input. Record whether Codex actually selected that skill. If it is absent, inspect the working directory, folder, filename and frontmatter; the manual says to restart Codex if a change has not appeared.

Inspect the saved output and all file or tool changes from that run. Compare each owner-defined check with the second input's authoritative source, recording pass, fail or unknown and any human judgment. Do not look for the first artifact's names or figures in a different task. Then try the nearby out-of-scope request in a fresh context without naming the skill and record whether implicit selection stayed off. A listed skill, fluent answer or plausible file is not proof of correct selection or output.

If the run exposes a defect, identify where it began: the backward reconstruction, trigger, input contract, instructions, permission boundary or output check. Change the smallest relevant part of `SKILL.md`, retain its before-and-after diff, and rerun the failed case plus a positive and nearby negative check. If no defect appears, record that no revision was justified. Keep the new version only after the owner accepts the actual output and selection evidence; hold or restore the prior one otherwise.

For an overbroad trigger, narrow the description and retest. The manual also documents optional `agents/openai.yaml` metadata with `policy.allow_implicit_invocation: false`; explicit `$name` use still works. To disable a troublesome local skill while repairing it, the manual documents a `[[skills.config]]` entry with its `path` and `enabled = false` in `~/.codex/config.toml`, followed by a restart. Recheck relevant cases after a material workflow or source change.

Local file storage does not mean local-only model processing. Codex runs can consume the account's applicable usage or API billing, and inputs may pass through OpenAI or connected tools under the account's settings. Check those settings and permissions before supplying sensitive material. The file itself gives no new authority and no guaranteed quality or time saving.

## Sources

- [OpenAI Build skills manual](https://learn.chatgpt.com/docs/build-skills.md) — Current SKILL.md frontmatter, Codex local discovery paths, invocation and optional selection/disable controls; no document date or version stated.
- [OpenAI Save workflows as skills use case](https://learn.chatgpt.com/use-cases/reusable-codex-skills.md) — Supports beginning with a working example and updating after a later use; its older personal path is superseded by the current manual.
- [BIG CHANGE earlier Codex workflow guide](https://bigchange.ai/blog/codex-noncoding-files-image-gmail-schedule-guide) — Related coverage supplies and verifies its own procedure; this article derives a new one from reader-owned accepted work.