Agent Skills

Turn a repeated Codex request into a reusable skill. You will create a small, instruction-only website review workflow, invoke it on a real example, and check that it handles missing information instead of guessing.

Before you start

• A working Codex CLI or IDE extension session in a local project. This walkthrough uses their documented $skill-name invocation.
• Permission to create a folder under the project’s .agents/skills directory, and a saved copy or Git checkpoint of the current project.
• One repeatable task with a clear output. The example here reviews supplied website text for missing customer information without editing files.
• A short sample of your website text, including its intended audience and the action you want readers to take.

Want to do it yourself?

Difficulty

6 out of 10

Estimated completion time

45–90 minutes for one tested skill

Skills you’ll need: Write repeatable instructions, inspect the saved skill, and test both a real sample and missing input.

I’ll do it myselfI’d rather get help

How this helps your brand

A reusable copy check can help you notice missing service areas, unclear actions, and unsupported statements on your website. Testing the instructions on incomplete input keeps the review grounded in your supplied facts.

1. 1

   Step 1: Define one job with a visible result

   A skill is a folder containing a SKILL.md instruction file and, optionally, supporting resources or scripts. It is useful when the same workflow comes up repeatedly. It does not give Codex new access to services or guarantee that every response will be correct.

   Start with a narrow job: review supplied website copy and return missing facts plus suggested wording. Keep the first version instruction-only so you can inspect the entire workflow without installing or running a script.

   Write down the required input, the output format, and the boundary. For this example the input is page text, audience, and desired action; the output is a short review; the boundary is no invented facts and no file edits.

2. 2

   Step 2: Ask the built-in creator to draft the skill

   Use the prompt at the end of this guide in Codex CLI or the IDE extension. It explicitly invokes $skill-creator and requests a project-local skill named website-copy-check.

   Ask the creator to save it under .agents/skills/website-copy-check/SKILL.md in this project. Codex discovers repository skills in .agents/skills locations from the current directory up to the repository root. A folder elsewhere is not automatically a repository skill.

   Answer any follow-up about scope or inputs. If a skill with that name already exists, inspect it first and choose another unique name rather than overwriting it.

   Illustrated exampleGive the skill a discoverable home

   Inside your project

   • my-website/
     • .agents/
       • skills/
         • website-copy-check/
           • SKILL.md

   Keep the exact filename: SKILL.md.

   SKILL.mdMetadata excerpt

   ---
   name: website-copy-check
   description: Review supplied website copy for clarity and missing customer information. Do not use for code changes, publishing, or general research.
   ---

   Name

   Matches the skill you will invoke.

   Description

   Says when to use it and when to skip it.

3. 3

   Step 3: Inspect the instructions before using them

   Open the created SKILL.md. Its opening metadata must include name and description. The name should be website-copy-check, and the description should say when the skill applies and when it does not.

   Read the workflow as if you were following it yourself. It should collect missing input, review only the supplied text, explain specific problems, and separate proposed wording from facts that need confirmation.

   Remove broad instructions such as “improve everything” or instructions to publish, contact customers, or rewrite the site. The finished skill should be small enough that you can explain its purpose in one sentence.

   • Inputs: page text, target audience, and intended visitor action.
   • Output: up to three issues, suggested wording, and a list of missing facts.
   • Boundary: do not invent business details or edit project files.
4. 4

   Step 4: Invoke it explicitly on a real sample

   In Codex CLI or the IDE extension, run /skills to look for the skill or type $ to select it. Invoke $website-copy-check and supply your sample text, audience, and desired action.

   For example, use a service paragraph that says “We help local businesses” but gives no service area. A useful review should identify the missing service area and ask you to supply it, rather than inventing a city.

   Read the run’s messages to confirm the skill was selected, then compare its output with the format you specified. Explicit invocation tests the workflow before you depend on Codex choosing it automatically.

5. 5

   Step 5: Test missing input and repair discovery problems

   Run the same skill with page text but deliberately omit the intended audience. Check that it asks for the missing input or clearly labels the gap. It should not silently turn a general page into a sales pitch for an invented customer group.

   If the skill is missing from the selector, check the folder, exact SKILL.md filename, and name and description metadata. Confirm you started Codex in the intended project. Codex detects changes automatically, but OpenAI recommends restarting if an update does not appear.

   Then try a natural request that fits its description, without naming the skill, and inspect whether Codex selects it. Automatic selection can vary; improve the description if the match is unclear, and use explicit invocation when you need this exact workflow.

   Illustrated exampleA useful review passes two different tests

   Explicit invocation$website-copy-check

   1. ANormal sample
      Supplied inputs

      “We help local businesses.”

      Audience

      Local business owners

      Action

      Request a quote

      Expected review

      Issue: The service area is missing.

      Suggested wording: “Local business owner? Request a quote.”

      Confirm: Which locations do you serve?

      Flags the gap without inventing a city.

   2. BMissing-input sample
      Supplied inputs

      “We help local businesses.”

      Audience

      Deliberately omitted

      Action

      Request a quote

      Expected follow-up

      “Who is the intended audience for this page?”

      Collect the missing input before reviewing.

      Asks you instead of assuming an audience.

   If either result misses the mark, revise the instructions and repeat both tests.

6. 6

   Step 6: Save the version that passed both examples

   Update the skill with any lessons from the tests, repeat the normal sample and missing-input sample, and save the reviewed file with your project.

   A repository-local skill is appropriate for this project. If you later want to distribute a workflow beyond one repository, OpenAI recommends packaging reusable skills as a plugin. You do not need that extra step for this first local skill.

$skill-creator Create an instruction-only project skill named website-copy-check. Save it in .agents/skills/website-copy-check/SKILL.md in [project folder]. If that skill already exists, show it to me before changing anything.

Use it when I ask to review supplied website copy for clarity and missing customer information. Do not use it for code changes, publishing, or general research.

Require these inputs: page text, intended audience, and the action visitors should take. Ask for missing inputs. Return up to three concrete issues, suggested wording using only supplied facts, and a list of missing facts I must confirm. Never invent prices, contact details, locations, or claims. Do not edit project files during a copy review.

Include valid name and description metadata. Show me the created file, explain how to invoke it, and give me one normal test and one missing-input test. Do not add scripts or install dependencies.