AI Skills: A Beginner’s Guide to Claude and Codex

What Is an AI Skill?

If you have used Claude Code or Codex CLI for a while, you have probably typed the same instructions more than once: “when you write a commit message, keep it under 70 characters”, or “always check for existing duplicates before creating a new file”. A Skill is simply that repeated instruction, written down once and saved, so you never have to type it again.

Think of a Skill as a laminated cheat sheet you hand a new colleague on their first day. You would not hand them your entire company handbook every time they start a task. You would hand them the one-page sheet for the job in front of them, and only when that job comes up. That is exactly how a Skill behaves: it sits quietly on your computer until a task matches it, and only then does the AI pick it up and read it.

Both Claude Code and Codex CLI build Skills the same way underneath: a folder, a required SKILL.md file inside it, and optional extra files the AI only opens if it needs them. The differences are in exactly which settings are required and where the folder needs to live, which is what the rest of this post walks through.

Why Bother Making One?

You do not need to be a programmer to benefit from a Skill. If you find yourself explaining the same thing to your AI assistant in more than one conversation, that is the signal to turn it into a Skill instead. Three common newbie-friendly reasons to make one:

You stop repeating yourself. Once a Skill exists, you never retype the instructions again; the AI reads them from disk every time they are needed. You get consistency. A written-down Skill behaves the same way today as it will next month, instead of depending on how you happened to phrase the request. And you can share it. A Skill is just a folder of text files, so you can hand it to a teammate, or commit it into a project, and everyone gets the same behaviour.

Building a Skill for Claude

Claude Code Skills live in a folder named after the skill, containing a SKILL.md file. Personal skills that work in every project go in ~/.claude/skills/; skills that belong to one specific project go in that project’s .claude/skills/ folder.

Every field in the frontmatter is technically optional except that description is strongly recommended, since it is what the AI reads to decide when to use the skill. Here are the settings a beginner actually needs to know about:

A handful of more advanced settings exist too, for running a skill in an isolated sub-task, limiting it to certain file types, or adjusting how much reasoning effort it uses. The six above cover nearly everything a first skill needs.

Here is a complete, working example. It is a skill called explain-this: paste an error message, and it explains what the error means in plain English and suggests one concrete first step.

# Step 1 — create the skill's folder (a personal skill, usable in any project)
mkdir -p ~/.claude/skills/explain-this

# Step 2 — save this as ~/.claude/skills/explain-this/SKILL.md
---
name: explain-this
description: Explain a pasted error message, exception, or log line in plain English and suggest one concrete first troubleshooting step. Use whenever the user pastes an error and asks what it means.
---

## Instructions

1. Read the pasted error text carefully.
2. Explain what it means in one or two plain-English sentences, avoiding jargon.
3. Suggest exactly one first thing to check or try — not a long list.
4. If the error text is incomplete, say what extra detail would help.

To try it, open Claude Code anywhere and either paste an error message directly, or type /explain-this followed by the error text. Both should trigger the same skill: the first because the pasted text matches the description, the second because you called it by name.

Building the Same Skill for Codex

Codex CLI Skills use the same core idea, laid out slightly differently. A skill folder lives under .agents/skills/, either inside your repository (so it is scoped to that project) or under ~/.agents/skills/ for a personal skill that works everywhere.

The important difference from Claude: Codex requires both name and description in the frontmatter. Skip either one and Codex will not load the skill at all.

Here is the same explain-this skill, rebuilt for Codex:

# Step 1 — create the skill's folder inside your repository
mkdir -p .agents/skills/explain-this

# Step 2 — save this as .agents/skills/explain-this/SKILL.md
---
name: explain-this
description: Explain a pasted error message, exception, or log line in plain English and suggest one concrete first troubleshooting step. Use whenever the user pastes an error and asks what it means. Do not use for general coding questions unrelated to an error.
---

## Instructions

1. Read the pasted error text carefully.
2. Explain what it means in one or two plain-English sentences, avoiding jargon.
3. Suggest exactly one first thing to check or try — not a long list.
4. If the error text is incomplete, say what extra detail would help.

To try it, run Codex CLI in that repository and either type $explain-this followed by an error, or use the /skills menu to run it by name. Paste an unfamiliar error and see whether it triggers automatically first.

Claude vs Codex: Quick Reference

Common Beginner Mistakes

Final Thoughts

Skills are one of the easiest ways to get more consistent, more useful behaviour out of an AI coding assistant, and neither platform requires you to be a professional developer to build one. Start small: pick one instruction you find yourself repeating, write it down as a Skill following the tables above, and see whether the AI picks it up on its own.

The two platforms will keep evolving their exact settings over time, so when in doubt, treat the tables above as a starting point and check the current documentation before relying on a field for something important.