How to create a skill for Claude Code and Codex: stop repeating instructions

You ask an agent to finish a task. It edits a few files, tells you everything is ready, and you breathe out.

Then you open the project and find it never tested the form, a page doesn't load, or half the criteria stayed in the chat as good intentions.

The problem isn't always that the agent can't do the work. Sometimes nobody made clear how you check that it's done.

A skill can help with that. It's a way to store a reusable procedure so the agent knows when to apply it, which steps to follow and what to hand back.

This article grew out of Gilberts Ahumada Cabrera's video on creating skills for Claude Code and Codex (in Spanish). According to the video description and the author's LinkedIn post, his example builds a skill called prove that checks whether a task is truly finished and returns a pass or fail verdict. We recommend watching the whole video. Here we take the idea and build our own review template that you can adapt to your projects.

What a skill is, in two minutes

A skill is a folder with instructions for a task or workflow. Its main file is called SKILL.md, and it can come with references, templates or scripts when they're needed. At first the agent only sees the name and description, and it loads the full instructions when your request matches or when you invoke it yourself.

You could create a skill to:

• Review articles before publishing them.
• Get an app ready for a delivery.
• Analyze a spreadsheet with your company's method.
• Check a software update.
• Produce reports with a fixed structure.

If you want the whole picture (the open standard, each agent's folders, how to install community skills and how many is too many), see our guide on skills for coding agents. If you work in the Claude app rather than an editor, read Claude Skills, connectors and plugins. Here we go straight to building one.

The benefit isn't that the AI gains a superpower. It's that the method no longer depends on someone remembering to write it out in full in every conversation.

The difference between a prompt and a skill

A prompt can be a one-off instruction:

Check that the contact form works.

A skill can define a broader procedure:

When asked to review a delivery, identify the acceptance criteria, run the checks available, record the evidence and separate what passed from what's pending.

The practical difference is scope and reuse. A prompt can be detailed too, and a skill is also text. What the skill adds is a way to organize that process so you can reuse it, along with any resources it needs:

• Typical use. A prompt handles one specific request; a skill applies a procedure that repeats.
• Where it lives. A prompt, in the conversation or a template; a skill, in a folder with a SKILL.md file.
• What it holds. A prompt, instructions and context inside the message; a skill, instructions, references, templates and, if needed, scripts.
• When it fits. A prompt, when the task is one-off or keeps changing; a skill, when the process is stable and you want to apply it many times.

You don't need a skill for everything. If an instruction is used once and fits in two lines, it's probably not worth turning into a small administrative department.

When a skill makes sense

A good candidate usually meets three conditions:

1. The task repeats. You review deliveries, write product sheets or prepare reports often.
2. The method matters. "Do it well" isn't enough; there are specific steps or criteria.
3. You can describe a good result. You know what it should include and how to check whether something is missing.

For example, "create a skill to make the AI smarter" is far too broad. But "create a skill to review a page before publishing it: links, form, mobile view and final copy" has a clear purpose and a clear result.

What goes in a SKILL.md file

The simplest version has two parts:

1. A header between --- lines with the name and description.
2. The instructions the agent should follow.

---
name: delivery-review
description: Reviews a finished task against its acceptance criteria and presents evidence. Use when asked to verify a delivery.
---

# Delivery review

1. Identify what was asked and what the acceptance criteria are.
2. Check each criterion with the means available.
3. Record what you reviewed and what result you got.
4. Point out what you couldn't check and why.
5. Deliver a summary with results and open items.

Use lowercase letters and hyphens for the name, with no spaces: it's easy to invoke and matches the folder name.

The description matters most, because it's what the agent reads to decide when to use the skill. If it only says "helps with tasks", it gives no direction. OpenAI's guide to building skills recommends concise descriptions with clear scope and boundaries, putting the use case and the words someone would use to ask for it first. The Claude Code documentation says much the same: every header field is optional, but it recommends a description so Claude knows when to load the skill.

Worked example: a skill to review deliveries

Let's build a template called delivery-review. Its goal is to answer a single question:

What evidence do we have that the task really does what was asked?

This example was written for this article. It isn't a copy of prove or a reproduction of the code shown in the video.

Step 1. Define the input

The skill needs to know what to review. It can start from:

• The original request.
• The acceptance criteria.
• The files or app that were changed.
• The tests available.
• The constraints set by the person who asked for the work.

If there are no clear criteria, the skill can rebuild them from the request and point out which parts are still ambiguous.

Step 2. Define the expected result

Instead of an answer like "all done", we ask for a report per criterion. For example, for a contact form:

• The form opens. Check: open the page. Status: passed, failed or not checked. Evidence: the page or screenshot reviewed.
• Submitting works. Check: send an authorized test submission. Status: passed, failed or not checked. Evidence: the result observed.
• It looks right on mobile. Check: view it on a small screen. Status: passed, failed or not checked. Evidence: the screen used and what was seen.

The "not checked" status matters. If the agent has no access to a service, it mustn't present a missing test as a success. It's the same principle as our guide on how to check an AI answer before you use it: separate what was checked from what is only claimed.

Step 3. Write the instructions

Create a folder called delivery-review and, inside it, a SKILL.md file with this content:

---
name: delivery-review
description: Checks a delivery against the requested criteria. Use when asked to verify whether a task, change or deliverable is finished.
---

# Delivery review

## Goal

Check a delivery's acceptance criteria and report what passed,
what failed and what could not be verified.

## Procedure

1. Read the original request and extract the acceptance criteria.
2. Review the files, pages or results related to the task.
3. For each criterion, choose an appropriate check that is available.
4. Only run actions that are authorized for this review.
5. Record the result and the evidence observed.
6. If a check can't be done, explain why.
7. Present the findings in order of importance.

## Output format

Include a table with:

- Criterion.
- Check performed.
- Status: passed, failed or not checked.
- Evidence or reason.

End with the open items that keep the delivery from being finished.

## Limits

- Don't invent test results.
- Don't claim something works if you didn't check it.
- Don't publish, send data or change external services
  without the proper authorization.
- If essential criteria are missing, say so.

This skill needs no code to get started: it's a process written in plain language. Later you could add scripts for checks that must always come out the same, such as running the project's tests, as long as they genuinely add something.

The skill reviews better when the criteria exist from the start. If you don't have them yet, begin with the prompt From idea to a spec an AI can actually build: first you define what will be built and how you'll know it's right, and then the skill checks whether it was done.

Where to save the skill

To use it inside a project, each tool looks in a different folder.

In Claude Code:

your-project/
└── .claude/
    └── skills/
        └── delivery-review/
            └── SKILL.md

In Codex:

your-project/
└── .agents/
    └── skills/
        └── delivery-review/
            └── SKILL.md

Codex looks for .agents/skills in every folder from the one you have open up to the repository root. Both tools also support personal skills that follow you across projects; the details are in the Claude Code and Codex documentation.

You can keep the same basic content in both locations. That doesn't mean every extra feature of one tool exists in the other: if you add tool-specific options, scripts or integrations, check compatibility and test each environment separately.

How to invoke and test the skill

In Claude Code, type a slash followed by the name:

/delivery-review

In the Codex CLI or the editor extension, you can pick it from /skills or mention it with $:

$delivery-review

Both tools can also trigger it on their own when your request matches the description. That's why the description matters so much.

Then give it a concrete task. For example:

Use the delivery review skill to check the form changes. The criteria are: the page opens, required fields are validated and submitting works. If you can't check the submission, say so.

Seeing the skill in the list isn't enough. Check whether the result is what you expected:

• Did it identify every criterion?
• Did it run the checks it had available?
• Did it show evidence?
• Did it mark as pending what it couldn't check?
• Did it avoid saying "everything works" without testing it?

Also try a request that shouldn't trigger the skill. If it runs in any conversation, its description is too broad.

What to do when the skill fails

A skill is an instruction, not a guarantee. The agent can misread a criterion, skip a check or run into a limitation of the environment.

When that happens, don't start by adding twenty random rules. First look at where it failed:

• If it doesn't trigger: check the name, the description and the folder location.
• If it triggers for everything: narrow the description to the tasks it should really cover.
• If the report is vague: ask for an output format with criterion, result and evidence.
• If it claims things it didn't check: add an explicit instruction to separate what was observed from what's pending.
• If it depends on a tool that isn't always available: explain what to do when it's missing and how to report that limitation.

After changing it, rerun the same test case and compare. That's how you know whether the change helped.

A skill doesn't replace your judgment

Storing a procedure makes the work more consistent. It doesn't guarantee the agent follows every step or that a test is well designed.

That's why it pays to review third-party skills before installing them, especially if they include scripts, ask for file access or connect to external services. A folder can hold a lot more than nice instructions.

A human review also makes sense when the result touches customer data, publications, payments or changes that are hard to undo. The agent does the work; you steer and decide.

The useful question isn't "did the agent say it finished?". It's this:

What was asked, what was checked, and what evidence do we have?

A well-designed skill helps you answer it every time, without writing the procedure from scratch.

Frequently asked questions

Do I need to know how to code to create a skill?

For a skill made only of instructions, a Markdown text file is enough. If you add scripts or integrations, you'll need to know enough to review and test them.

Does the same skill work in Claude Code and Codex?

A simple SKILL.md-based skill is a good starting point in both. You need to put it in each tool's folder and test it in both, because each product's specific features can differ.

Does a skill guarantee the agent won't make mistakes?

No. It makes a procedure clearer and reusable, but the result still needs checking. Test it with real cases and look at what happens when something fails.

Can I use a skill to create content?

Yes. You can define an editorial structure, quality criteria and review steps. For the content to add value, you also need reliable sources, relevant examples and a check of what it claims.

When don't I need a skill?

When the task is one-off, keeps changing or is handled well by a short instruction. A skill earns its folder when the procedure is worth repeating.

Keep reading

• Skills for coding agents: the full picture of skills, each agent's folders and how to install community skills safely.
• Claude Skills, connectors and plugins: how to create a skill by talking to Claude in the app, and when a plugin makes sense.
• How to check an AI answer before you use it: the method for separating what was checked from what is only claimed.
• Reverse engineering with AI using REA: another agent workflow where evidence comes first.
• From idea to a spec an AI can actually build: the prompt for defining the criteria before the agent starts.

Sources

• How to create skills for Claude Code and Codex (video by Gilberts Ahumada Cabrera, in Spanish)
• Gilberts Ahumada Cabrera's post about the prove skill (LinkedIn, in Spanish)
• Skills in Claude Code (official documentation)
• Build skills (OpenAI documentation for Codex and ChatGPT)
• Skills (OpenAI plugins documentation, concepts)