Create your first Codex Skill and test when it should run

1. Pick a task that benefits from a repeatable contract

A good first skill turns messy bug notes into a report another person can reproduce. The input is short, the output is easy to inspect, and a mistake such as inventing a browser version is visible. Keep the first version instruction-only: no scripts, credentials, external services or installation steps are needed for this example.

Use AGENTS.md for standing project instructions such as the test command or repository conventions. Use this skill for a selected workflow with its own input and result. The skill can refer to project rules; it should not duplicate every rule or silently gain permission to edit files, file issues or fix the bug.

Before creating a new name, check your available skills for the same job. Reuse an appropriate existing skill if it already produces the report you need. A broad collection of impressive-sounding skills is less useful than one workflow you can evaluate.

Reference: OpenAI: Build skills · OpenAI: Build skills for plugins

2. Put the skill in the project where you will test it

For a repository-scoped example, create .agents/skills/bug-brief/SKILL.md inside the intended project. Use the exact uppercase filename and keep the folder dedicated to this skill. A repo-scoped skill can be reviewed with the project instead of becoming a personal default everywhere.

Current documentation also describes user-level skills under ~/.agents/skills. Start locally so an experiment does not affect unrelated projects. On Windows, the tilde is home-directory notation in the documentation; use your actual user directory if your editor or shell does not expand it.

You can ask the built-in skill creator to help draft the file, or write it manually. In Codex, the creator is invoked as $skill-creator. Inspect what it proposes before saving it. Do not install plugins or add a connector just to perform this text-only workflow.

.agents/
  skills/
    bug-brief/
      SKILL.md

Reference: OpenAI: Build skills

3. Write a trigger and a small procedure

Copy the complete example below into SKILL.md. The name and description help Codex decide when to consider it; the body specifies how to produce the report. State exclusions in the description so a request to explain a concept does not become a bug-report task.

The no-invention rule is the important part of this example. An issue that looks complete but includes guessed steps or an assumed cause wastes the next person's time. Unknowns should be visible and actionable.

---
name: bug-brief
description: Turn observed bug notes into a reproducible bug report with steps, expected and actual results, and explicit unknowns. Use when asked to prepare a bug report; not for explaining concepts, proposing fixes, or writing release notes.
---

Use only the notes supplied by the user. Do not inspect other files or run commands.
Write these headings in order: Summary, Steps to reproduce, Expected, Actual,
Evidence, Unknowns.

1. Keep the summary to one sentence about the observed failure.
2. Number only steps present in the notes. Do not invent a setup or login step.
3. Separate the expected result from the observed result.
4. Under Evidence, preserve supplied environment details and observations.
5. Under Unknowns, list missing facts needed to reproduce the issue. Never
   invent a browser version, frequency, cause, screenshot, or successful retest.
6. If the notes are insufficient, still return the report and ask one focused
   follow-up question. Do not claim the bug is fixed or change anything.

Reference: OpenAI: Build skills · OpenAI: Build skills for plugins

4. Test a named invocation before testing automatic selection

Open a fresh task in the intended project. In the Codex CLI or IDE extension, use /skills or type $ to select the skill; interfaces using an @ skill picker use that picker instead. Confirm that bug-brief is available before treating a response as evidence that the file was discovered.

Use only synthetic or redacted notes. For example: Windows, Chrome. Add one item to the cart, then refresh. Expected: the item remains. Actual: the cart is empty. Browser version, frequency and root cause are unknown.

A good report has the six requested headings. The steps contain adding the item and refreshing; Expected says the item remains, Actual says the cart is empty. Evidence retains Windows and Chrome. Unknowns names the missing version, frequency and cause. There is no invented login step, storage diagnosis or claim that a fix was tested.

$bug-brief Turn these notes into a reproducible bug report:
Windows, Chrome. Add one item to the cart, then refresh.
Expected: the item remains. Actual: the cart is empty.
Browser version, frequency and root cause are unknown.

Reference: OpenAI: Build skills

5. Check the requests that should and should not use it

Repeat each request in a fresh task. A prior task may already contain the skill instructions, making a later negative test misleading. Inspect both the chosen workflow and the resulting report; a model can produce report-like text without having discovered your skill.

We ran these four cases in separate native Codex CLI sessions on Windows. The named and indirect requests selected bug-brief; the indirect run read its SKILL.md before returning the report. The concept question stayed outside the workflow, and the incomplete report request kept missing details unknown and asked one focused question. These are dated checks of CLI 0.163.0 with gpt-6.1-sol, not a guarantee for every client or wording.

Make the incomplete-input test's job explicit: ask to prepare a bug report, then supply only Checkout is broken. In a separate test, the bare sentence Checkout is broken did not select this skill; Codex asked whether checkout meant a purchase page or Git checkout. A failure statement alone can mean diagnosis or a fix, so do not broaden this report-writing skill to capture every mention of a bug.

Reference: OpenAI: Build skills for plugins · OpenAI: Testing Agent Skills systematically with evals

6. Fix discovery and output problems separately

If the skill is absent, check the actual project directory, .agents/skills location, SKILL.md filename and name/description front matter. Current documentation says changes are detected automatically and recommends restarting when a change does not appear. Do not scatter duplicate copies across personal and project directories to hide a discovery problem.

If the client cannot start a model session or sign in, diagnose that environment problem first. It does not show whether the skill would trigger. If a named invocation works but the indirect request does not, sharpen the description around the user's actual words. If both select the skill but reports invent facts, repair the procedure and rerun the same notes.

Change one thing at a time and retain a small record of the input, selected skill and output. Once these cases work, try a few different real but redacted reports. Add a script only when a genuinely repetitive mechanical step needs one. Add external tools only when the reader's task needs them, with their own permissions.

Reference: OpenAI: Build skills · OpenAI: Build skills for plugins · OpenAI: Testing Agent Skills systematically with evals

Try it in Codex

Create a project-scoped bug-report skill

Help me create one instruction-only Codex skill named bug-brief in the intended project's .agents/skills/bug-brief/SKILL.md. First confirm the project and check for an existing skill serving the same job; preserve existing files.

The skill should turn only supplied, redacted bug notes into a report with Summary, Steps to reproduce, Expected, Actual, Evidence and Unknowns. Give it a description that includes direct and indirect bug-report requests and excludes concept explanations, proposed fixes and release notes. Do not invent environment details, steps, causes or successful retests. If notes are incomplete, preserve unknowns and ask one focused question.

Show the complete proposed file and save only that local file when the destination is clear. Then give me four fresh-task tests: a named invocation, an indirect report request, a negative concept question and incomplete notes. Separate file validation, skill discovery, selection and output quality in the results. Do not claim a test ran unless it did. Do not install anything, call external services, change personal configuration, fix product code, file an issue, commit, push or publish.

Check your result

• The skill has one clear job and an inspected SKILL.md in the intended project.
• A named invocation confirms discovery in the actual Codex client.
• Direct and indirect requests produce useful reports without invented facts.
• A negative task stays outside the workflow, and incomplete notes retain unknowns.
• Any client, discovery or selection failure is recorded separately from file validity.

Sources and scope

Official references support the product behavior described above. The task prompts and practical checks are our community guidance.

• OpenAI: Build skillsLocal skill structure, repository and user locations, explicit and implicit invocation, and discovery guidance.
• OpenAI: Build skills for pluginsFocused workflow boundaries, instruction-only skills, and representative positive, negative and incomplete-input tests.
• OpenAI: Testing Agent Skills systematically with evalsSeparate activation and output checks and use concrete, observable evaluations.

Something changed in your version? Send a correction with the guide URL, platform, and version. Leave out credentials and private project content.