What is the SKILL.md format?

SKILL.md is the open file format for an agent skill: YAML frontmatter (name + description) followed by markdown instructions. It's shared across Claude, Codex, and Gemini CLI / Antigravity.

Do agent skills work on more than one AI model?

Yes. The same SKILL.md runs on Claude, OpenAI Codex, and Gemini CLI / Antigravity. The only difference is where each tool looks for installed skills.

Is a SKILL.md the same as an Azure skillset or a Gemini Gem?

No. An Azure AI Search skillset is a search-indexing pipeline, and a Gemini Gem is a no-code chatbot. Neither is an installable agent SKILL.md.

How do I create a SKILL.md file?

Make a folder, add a SKILL.md with a name and description in the frontmatter, then write the instructions. Or generate one instantly with the free Skill Builder.

Agent Skills and SKILL.md: How to Create a Skill for Any AI Agent

Agent skills are an open way to give any AI agent reusable know-how through a single SKILL.md file. This guide explains the format, how it works, how to create one for any tool, and how to avoid the common look-alikes.

What are Agent Skills? (the open standard)

Agent Skills are reusable capabilities you give an AI agent as a small folder containing a SKILL.md file. The agent reads each skill's name and description up front and loads the full instructions only when a task matches — so you can equip an agent with many skills without bloating its context.

It's an open standard, not one vendor's feature: the same SKILL.md runs on Claude, OpenAI Codex, and Gemini CLI / Antigravity.

Anatomy of a SKILL.md file

YAML frontmatter — a name (lowercase, kebab-case, matching the folder) and a description (what the skill does + when to trigger it).
Markdown body — the actual instructions, as clear imperative steps.
Optional bundled resources — scripts, references, or templates the skill can point to.

How progressive disclosure works

Skills stay cheap because the agent always sees only the lightweight name + description of each installed skill. It pulls the full body into context only when the task matches, and reads bundled files only if the instructions ask. That's what lets skills scale where a giant system prompt can't.

How to create a SKILL.md file (tool-agnostic)

The steps below work for any compatible agent.

One SKILL.md across Claude, Codex, and Gemini / Antigravity

The file is identical; only the install location differs:

Claude Code — ~/.claude/skills/<name>/SKILL.md
OpenAI Codex — ~/.agents/skills/<name>/SKILL.md
Gemini CLI / Antigravity — ~/.gemini/config/skills/<name>/SKILL.md

Here is a minimal, portable example:

---
name: pr-review
description: Reviews a pull request for bugs, security, and style. Use when the user asks to review code or a PR.
---

# PR Review

1. Read the full diff before commenting.
2. Flag correctness bugs, then security, then style.
3. Give concrete feedback with file:line references.
4. End with approve or request-changes.

SKILL.md is not an Azure AI Search skillset or a Gemini Gem

Two frequent mix-ups:

Azure AI Search "skillset" is an enrichment pipeline for search indexing — unrelated to agent SKILL.md files.
Gemini "Gems" are no-code custom chatbots at gemini.google.com — not installable SKILL.md skills.

If you're here to build an agent capability as a file, agent skills / SKILL.md is what you want.

Create your skill by tool

Pick your agent for a step-by-step guide:

Or get the fundamentals in what are agent skills and grab a SKILL.md template.

Build your first agent skill now

Skip the boilerplate with the free Skill Builder, or browse ready-made skills to install one in seconds.