What is a SKILL.md file?

A SKILL.md file is a markdown file that teaches an AI agent how to do one specific job. It sits inside its own folder, starts with a short block of YAML frontmatter (a name and a description), and continues with plain-language instructions. Agents like Claude Code and Cursor read the description to decide when the skill is relevant, and load the full instructions only when it's needed.

SKILL.md is the core of Agent Skills, an open standard documented at agentskills.io. Because it's a standard, the same skill folder works in any tool that supports it.

What a SKILL.md file looks like

Here's a shortened version of the free Code Review Companion skill on Skillvize:

---
name: code-review-companion
description: "Paste in a diff and get a structured review: bugs, edge cases,
  naming, and the one thing worth fixing before merge."
---

# Code Review Companion

## Steps

### 1. Scan for bugs
Read the input line by line and flag logic errors, typos, off-by-ones,
wrong comparisons. Quote the line.

### 2. Check edge cases
Identify unhandled inputs: null/undefined, empty collections, zero,
negatives, unexpected types.

### 3. Review naming and clarity
### 4. Pick the one fix that matters

The two parts:

• Frontmatter. name is the skill's identifier. Lowercase and hyphens is the safe choice: Cursor requires it, and it should match the folder name. description says what the skill does and when to use it. This is the part the agent sees up front, so it does most of the work of getting the skill triggered at the right moment.
• Body. The actual instructions: steps, conventions, checklists, examples. Write it like you're briefing a sharp colleague.

A skill folder can also hold optional extras, such as scripts/ the agent can run, references/ it loads on demand, and assets/ like templates.

Where SKILL.md files go

Cursor also loads skills from .claude/skills/ and .codex/skills/ for compatibility, so a skill you set up for Claude Code usually works in Cursor without changes.

How agents use a skill

1. When a session starts, the agent sees each installed skill's name and description, but not the full body.
2. When your request matches a description, the agent loads that skill's instructions and follows them.
3. You can also invoke a skill directly by typing /skill-name.

This "progressive" loading is the main advantage over pasting one giant prompt. Twenty skills cost little context until one is actually used.

SKILL.md vs CLAUDE.md, rules, and prompts

• CLAUDE.md / AGENTS.md hold facts and conventions the agent should always know about a project. Skills hold procedures that load on demand.
• Cursor rules (.mdc files in .cursor/rules) are Cursor-specific guidance. See Cursor rules vs Claude skills.
• A saved prompt only works if you paste it. A skill is a file the agent can find and use on its own.

Free SKILL.md examples to try

Every skill on Skillvize downloads as a SKILL.md folder. A few free ones to start with:

• Code Review Companion: a structured review of a diff
• Error Message Explainer: a plain-English read of a stack trace
• Meeting Notes → Action Plan: decisions, owners, and a follow-up email
• Deep Research Brief: sub-questions, findings with confidence levels, and a bottom line

Five of these are also in the public free-skills repo on GitHub. In Claude Code, add it as a plugin marketplace with /plugin marketplace add tyelf22/free-skills.

Write your own

Start small: one job, one clear description, a few steps. If it saves you time, it'll probably save someone else time too. You can list skills on Skillvize for free and set a price or give them away.

Browse all skills on Skillvize →