The SKILL.md format

A SKILL.md file is YAML frontmatter between two --- lines, followed by Markdown instructions. The open Agent Skills specification requires two fields, name and description; everything else (scripts, references, assets, extra frontmatter) is optional. Below is the complete example we built and tested for this set of guides.

The spec fields

The Markdown body has no prescribed section schema; the instructions below are our own structure, not a spec requirement. A skill folder can contain scripts/, references/, and assets/, but those are organizational conventions, not required directory names.

Our example: explain-error

This is the skill we used across every guide in this set. It explains a pasted error message or stack trace and suggests one concrete fix.

explain-error/SKILL.md:

---
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.

explain-error/references/checklist.md:

# 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.

The description is 189 characters (well inside the spec’s 1–1,024 limit), and it states both what the skill does and the conditions under which it should be used, which matters more for triggering than the character count. We cover that in how to write skill descriptions that trigger. references/checklist.md is loaded by instruction, not automatically. See how references and assets work inside a skill for what happens when that reference breaks.

Host extensions to watch for

The two files above are the portable core. Hosts add their own fields on top, and none of these are part of the open spec:

We didn’t add any host-specific fields to explain-error; it’s deliberately the portable minimum.

What we checked

Format

npx skills-ref validate ./explain-error (v0.1.5) returned Valid skill: ./explain-error, and npx skills-ref read-properties ./explain-error parsed both fields cleanly. This check only validates frontmatter shape. See how references and assets work inside a skill for what it doesn’t catch.

Installs

Copied by hand to .claude/skills/explain-error/ and to both .agents/skills/explain-error/ and .codex/skills/explain-error/ (Codex CLI 0.157.1, both project paths work on this version). Also installed with npx skills add ... -a claude-code -y and -a codex -y (skills CLI v1.7.0), which wrote full copies, not symlinks, to .claude/skills/ and .agents/skills/ respectively. The installer doesn’t target .codex/skills/, which we reached only by hand-copy.

Loads

On Codex, a pasted traceback triggered the skill: the trace showed cat .agents/skills/explain-error/SKILL.md and cat .agents/skills/explain-error/references/checklist.md, and the reply opened with Checked with explain-error and named the file, line, cause, and one fix, matching the checklist. On Claude Code, claude -p could not authenticate from our test setup (Not logged in · Please run /login, on every invocation, even a plain claude -p "say hi"), so live loading was not tested. Cursor was not installed, so it was not tested at all.

Helps

Not measured on this page.

What we didn’t check

Live loading in Claude Code and anything in Cursor. Host extensions to SKILL.md (when_to_use, paths, agents/openai.yaml, and similar) were documented, not built or tested.

Common problems

Local leniency isn’t the spec: a Claude Code skill that tolerates a missing name locally can still fail skills-ref validate or a claude.ai upload, per Anthropic’s own compatibility notes.

Malformed YAML can half-work. Claude Code’s docs note that broken frontmatter can leave a skill directly invocable while removing the metadata needed for automatic matching; it fails quietly rather than with a clear error.

Wrong layout is another common problem. A Cursor forum report describes skills/SKILL.md used by mistake instead of skills/<name>/SKILL.md. Treat it as a troubleshooting lead, not a guarantee of current behavior.

Sources

• Agent Skills specification
• Claude Code: frontmatter and upload distinctions
• Cursor: skill fields
• Codex: build skills