Home › Rules › SKILL.md examples

SKILL.md examples, format and frontmatter (Claude Code, Cursor, Codex, Copilot and Antigravity)

From the Agent Skills spec and each tool's own docs, checked Nov 2, 2026. Sources below.

• Guide
• Skills
• SKILL.md
• Claude Code
• Cursor
• Codex
• Copilot
• Antigravity

Short answer: A skill is a folder with a SKILL.md file in it. The file starts with a YAML header between two --- lines, with a name and a description, and then your steps in plain Markdown. Claude Code, Cursor, OpenAI Codex, GitHub Copilot and Google Antigravity all read this same format, because it's an open standard called Agent Skills. What changes from tool to tool is the folder it goes in and a few extra header fields. The agent only sees each skill's name and description at first, and reads the whole file when your task matches.

The SKILL.md format (a template you can copy)

This is the smallest skill that works in all five tools. Save it as SKILL.md inside a folder with the same name as the name line, for example my-skill/SKILL.md.

---
name: my-skill
description: What this skill does, and when the agent should use it. Use the words people would actually type.
---

# My skill

1. First step.
2. Second step.
3. How to check the result.

Only SKILL.md is required. The spec suggests these optional folders next to it:

my-skill/
├── SKILL.md       # Required: header + instructions
├── scripts/       # Optional: code the agent can run
├── references/    # Optional: longer docs, read when needed
└── assets/        # Optional: templates, images, data files

The spec suggests keeping SKILL.md under 500 lines and moving long reference material into separate files, because the whole SKILL.md is loaded once the skill is used.

SKILL.md frontmatter fields (the open standard)

Good description vs weak one. The spec's own example of a weak description is "Helps with PDFs." A good one says what the skill does and when: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

What each tool adds (and where the folder goes)

For project skills, Claude Code, Codex and Antigravity look in the folder you start in and each parent folder up to the repo root. Cursor also picks up .cursor/skills/ or .agents/skills/ folders further down in the repo, and scopes them to that part of the code. More detail for one tool: Claude Code skills, Cursor rules vs skills, Antigravity skills.

One skill for every tool

There's no single folder all five read. .agents/skills/ covers Cursor, Codex, Copilot and Antigravity. Claude Code reads .claude/skills/ instead (Cursor and Copilot read that one too). Two simple ways to handle it:

• You only use Claude Code plus Cursor or Copilot: put skills in .claude/skills/. All three read it.
• You use Codex or Antigravity too: keep the real folder in .agents/skills/ and add a link to it from .claude/skills/. Claude Code's docs say a skill folder can be a symlink, and Codex's docs say the same. On Mac or Linux:

mkdir -p .agents/skills/fix-failing-test .claude/skills
# put SKILL.md in .agents/skills/fix-failing-test/, then:
ln -s ../../.agents/skills/fix-failing-test .claude/skills/fix-failing-test

For a skill that works everywhere, stick to name, description and plain steps. Tool-only fields like paths or arguments may just be ignored by the others.

4 SKILL.md examples you can copy

These are our own examples for beginners, not from any tool's docs. Each name matches its folder, so they follow the strictest rules (Cursor's and the spec's). Change the commands to match your project.

Example 1: fix a failing test

---
name: fix-failing-test
description: Finds out why a test is failing and fixes it. Use when a test fails, the test command shows errors, or the user says tests are broken.
---

# Fix a failing test

1. Run the test command from package.json (or the README) and copy the exact error.
2. Explain in one or two plain sentences why it fails.
3. Decide if the test is wrong or the app code is wrong. Tell me which, and why.
4. Make the smallest change that fixes it. Don't touch other tests.
5. Run the tests again and show me they pass.

Example 2: add an API key or environment variable safely

---
name: add-env-var
description: Adds a new environment variable or API key to the project safely. Use when the user adds a key, secret, token or setting that goes in a .env file.
---

# Add an environment variable

1. Add the name to .env.example with an empty value. Never put the real value there.
2. Ask me to paste the real value into .env myself. Don't print it back.
3. Check that .env is listed in .gitignore. If it isn't, add it and tell me.
4. Read the variable in one place in the code, with a clear error if it's missing.
5. Tell me where to add it on the hosting site (for example the Vercel or Netlify settings).

Example 3: write the README

---
name: write-readme
description: Writes or updates the README for this project in plain English. Use when the user asks for a README, setup steps, or docs for someone new to the project.
---

# Write the README

Cover these, in this order, and keep it short:
1. What the app does, in one sentence.
2. How to install it and run it locally (check the real commands first).
3. Which environment variables it needs (names only, never values).
4. How to deploy it, if the project shows how.
Don't invent features. If you're not sure something works, leave it out and ask me.

Example 4: a deploy checklist you run yourself

---
name: deploy-check
description: Runs a checklist before deploying the app. Use only when the user runs it by name.
disable-model-invocation: true
---

# Deploy check

Before I deploy, check and report each one as pass or fail:
1. The build command finishes with no errors.
2. The tests pass.
3. No API keys or passwords are in the code or in git.
4. Every environment variable the app reads is set on the hosting site.
5. There's a way to roll back (the previous deploy is still there).
Don't deploy anything yourself. Just give me the list.

disable-model-invocation: true means the agent won't pick this skill on its own; you run it with /deploy-check. Claude Code, Cursor and VS Code document that field. Codex uses allow_implicit_invocation: false in agents/openai.yaml instead, and Antigravity's docs don't list a switch for it, so there the description's "only when the user runs it by name" is what keeps it from running.

Want more? Our 7 Claude Code skills examples show the Claude-only extras, like $ARGUMENTS and allowed-tools.

CLAUDE.md vs skills (and AGENTS.md vs skills)

Anthropic's docs draw the line simply. CLAUDE.md is for facts the agent should know in every session: build commands, conventions, project layout, "always do X" rules. If something is a procedure with several steps, or only matters for one part of the code, make it a skill. The difference is when they load: CLAUDE.md is read every session, while a skill's steps load only when it's used, so a long skill costs almost nothing until you need it.

AGENTS.md works the same way as CLAUDE.md for Codex, Cursor, Copilot and Antigravity: short, always-on facts. Anthropic's tip for spotting a skill: you keep pasting the same checklist into chat, or a section of CLAUDE.md has grown into a step-by-step procedure. See CLAUDE.md examples and AGENTS.md examples.

"Missing YAML frontmatter" and other SKILL.md errors

Errors like "missing YAML frontmatter" or "frontmatter must be a YAML mapping" mean the tool couldn't read the header. The usual causes:

• The first line isn't ---. Nothing can come before it, not even a blank line or a title.
• No closing --- after the last header line.
• A colon followed by a space inside the description, like description: Use when: the user asks. Put the whole description in double quotes, or reword it.
• Tabs instead of spaces in the header. YAML doesn't allow tabs for indenting.
• Wrong file name. It must be SKILL.md, inside its own folder.
• Name doesn't match the folder, or has capitals, spaces or underscores. Cursor, VS Code and the spec all require lowercase with hyphens, matching the folder.

To check a skill, the spec's skills-ref tool runs skills-ref validate ./my-skill. You can also ask the agent: in Claude Code run /skills, in Cursor type / in Agent chat, in Copilot CLI run /skills list, in Codex run /skills, and in Antigravity open Customizations (or /skills in its CLI).

Skill loads but never gets picked? Rewrite the description with the words you'd actually type, and put the main use first. Codex shortens descriptions when you have lots of skills, and Claude Code cuts the description off at 1,536 characters in its list.

Related

• Claude Code skills examples (7 SKILL.md files with Claude-only extras)
• Google Antigravity skills (skills folder, workflows vs skills)
• Cursor rules vs skills
• CLAUDE.md examples
• AGENTS.md examples
• Custom slash commands
• Every rules file format
• Free rules file generator

Sources

• Agent Skills specification
• Claude Code docs: Skills
• Claude Code docs: Memory and CLAUDE.md
• Cursor docs: Skills
• GitHub Docs: About agent skills
• GitHub Docs: Adding agent skills for Copilot CLI
• VS Code docs: Agent skills
• OpenAI docs: Build skills (Codex)
• Google Antigravity docs: Agent skills

Everything here was checked Nov 2, 2026 against the Agent Skills spec and each tool's own docs. These tools change often. If something here no longer matches, tell us at [email protected].