How to create an agent skill

To build an agent skill, start from a real, repeated task, not a blank page: do the task once by hand, note the corrections you had to make, and turn only the reusable steps into a skill. This guide walks through building explain-error, the small skill we used to test the four checks across this set of guides, and where to put it for Claude Code and Codex. We checked format, installs, and loads on Codex CLI 0.157.1 and Claude Code CLI 2.1.283 on September 27, 2026.

What you need

• A folder for the skill, named exactly what you’ll put in its name field.
• The skills-ref validator to check frontmatter shape (npx skills-ref validate ./<folder>).
• A host to test in. We used Codex CLI 0.157.1 and Claude Code CLI 2.1.283; we did not have Cursor installed.

1. Pick one job with a recognizable request

The official authoring guidance is specific about this: extract a skill from work you’ve actually done, not from generic knowledge, which tends to produce vague procedures. explain-error came from a recognizable, narrow request: someone pastes an error or stack trace and asks what’s wrong, with a clear input (the trace), a clear output (file, line, cause, one fix), and a procedure worth writing down once.

2. Write the smallest instruction file that preserves the procedure

---
name: explain-error
description: Explains a pasted error message or stack trace and suggests one concrete fix. Use when someone shares an error, exception, stack trace, or traceback and asks what is wrong or how to fix it.
---

# Explain Error

Use this skill whenever the user pastes an error message, exception, or stack trace and asks what went wrong or how to fix it.

## Steps

1. Begin your answer with the exact line: `Checked with explain-error`
2. Read `references/checklist.md` in this skill folder and follow it.
3. Identify the specific file and line number from the trace (or state that none is present).
4. Name the error type and the most likely root cause.
5. Suggest exactly one concrete fix.

Keep the answer short: a marker line, the file/line, the cause, and one fix.

name must be lowercase letters, digits, and hyphens, and must match the folder name; ours is explain-error/. description states what the skill does and when to use it in one place; see how to write skill descriptions that trigger for why that second half matters as much as the first.

3. Add supporting files only where they help

We moved the detailed checklist out of SKILL.md and into references/checklist.md, loaded only when the instructions point to it:

# Explain-error checklist

When explaining an error or stack trace, work through this checklist:

1. **Name the file and line.** State the exact file name and line number where the error was raised. If the trace has no file/line information, say so explicitly instead of guessing.
2. **Name the error type.** State the exception or error class (e.g. `TypeError`, `NameError`, `NullPointerException`).
3. **State the root cause in one sentence.** Explain why the error happened, not just what it says.
4. **Suggest exactly one fix.** Give a single, concrete, actionable fix. Do not list multiple alternatives.
5. **Do not apply the fix yourself.** Only explain it, unless the user explicitly asks you to make the change.

Overly broad, “help with anything” skills are harder for a host to select and harder for anyone to evaluate. The official best-practices guide calls this out directly, and it matches what we saw: a narrow, specific skill is easier to test and easier to trust.

4. Validate the frontmatter

npx skills-ref validate ./explain-error

We got Valid skill: ./explain-error (skills-ref v0.1.5). This confirms name and description are shaped correctly; it does not confirm the skill installs, loads, or works. Treat it as step one of four, not the whole picture.

5. Put the folder where your host looks for it

On Codex CLI 0.157.1 we also confirmed the older .codex/skills/<name>/SKILL.md path still works, so both Codex paths are live simultaneously on this version.

We copied the whole folder (SKILL.md and references/checklist.md) to each path by hand; copying only SKILL.md leaves the reference file behind, which we cover in how references and assets work inside a skill. We also used the installer, npx skills add <path> -a claude-code -y and -a codex -y (skills CLI v1.7.0), which wrote full copies rather than symlinks to .claude/skills/ and .agents/skills/ respectively, plus a skills-lock.json with a content hash of the source. The installer doesn’t target .codex/skills/; we reached that path only by hand-copy.

6. Try it on a fresh task, not the one you wrote it from

Reusing the conversation you wrote the skill in can hide missing instructions, because the agent still has your corrections in context. We ran three fresh Codex sessions with different traceback languages (Python, JavaScript, Java) and three unrelated control prompts, in each case starting a new session so nothing carried over. That’s covered in full in how to test an agent skill.

What we checked

Format

npx skills-ref validate ./explain-error (v0.1.5): Valid skill: ./explain-error.

Installs

Confirmed at .claude/skills/explain-error/, .agents/skills/explain-error/, and .codex/skills/explain-error/ by hand-copy. npx skills add additionally confirmed for .claude/skills/ and .agents/skills/; it doesn’t write .codex/skills/.

Loads

On Codex CLI 0.157.1, the skill was listed by the agent, triggered correctly on a pasted traceback (visible in the trace as cat .agents/skills/explain-error/SKILL.md and cat .../references/checklist.md), and did not trigger on an unrelated prompt.

On Claude Code 2.1.283, claude -p could not authenticate from our test setup. Every call, including claude -p "say hi", returned Not logged in · Please run /login, confirmed as a credential-isolation issue rather than a network or skill problem. Live loading in Claude Code was not tested. Cursor was not installed and was not tested.

Helps

Not measured. We confirmed the skill loads and follows its own checklist, not whether it beats an unaided answer.

What we didn’t check

Live loading in Claude Code, anything in Cursor, and personal-scope paths (~/.claude/skills, ~/.agents/skills). Those are documented from the brief, not tested by us.

Common problems

Generating a skill from general knowledge instead of a real task is one common mistake: the official best-practices guide warns this tends to produce vague, hard-to-follow procedures. Writing a skill so broad it can’t be evaluated is another: a narrow scope with one recognizable trigger is easier to test and easier to trust than “help with X in general.” Weak descriptions or misplaced files can also cause detection problems; a community discussion reports both. Verify any suggested fix against current host docs before relying on it.

Sources

• Agent Skills: authoring best practices
• Anthropic: skill authoring guidance
• Claude Code: skill locations and skill-creator workflow
• Codex: build skills