What Are Agent Skills? A Plain Guide to SKILL.md

An agent skill is a small package of know-how for an AI coding agent. It is a folder with a SKILL.md file: a short description of when to use it, then step-by-step instructions the agent follows. Think of it as a recipe card. The agent keeps the titles of all its recipe cards in view and pulls out the full card only when you ask for that dish.

Skills follow an open format, Agent Skills, so one folder works in Claude Code, Codex, Cursor, Gemini CLI and other agents.

What is inside a skill

At minimum, one file. A skill that makes a video might look like this:

launch-video/
├── SKILL.md            instructions + metadata (required)
├── scripts/            code the agent runs
│   └── launch-video.mjs
├── examples/           sample inputs
│   └── launch.json
└── LICENSE

SKILL.md starts with YAML frontmatter, then plain Markdown:

---
name: launch-video
description: Make a product launch video (MP4) from a product name, features
  with screenshots and a call to action. Use for product launches, feature
  announcements and app promos.
license: MIT
---

# Launch video

1. Collect the product name, tagline, features and screenshots.
2. Write launch.json (see examples/launch.json).
3. Run: node scripts/launch-video.mjs launch.json

The standard defines these frontmatter fields:

Field	Required	What it is
name	yes	Up to 64 characters: lowercase letters, numbers and single hyphens. Must match the folder name.
description	yes	Up to 1,024 characters. What the skill does and when to use it: this is what the agent matches your request against.
license	no	A licence name or a bundled licence file.
compatibility	no	Up to 500 characters on what the skill needs, such as “Node.js 22+ and FFmpeg”.
metadata	no	Your own key-value pairs, such as author or version.
allowed-tools	no	Tools the skill may use without asking (experimental; support varies).

Agents can add their own fields. Claude Code, for example, accepts disable-model-invocation: true for a skill that should only run when you type its name.

How an agent uses a skill

Skills load in three steps, which the spec calls progressive disclosure:

1. At startup the agent reads only each skill’s name and description, about 100 tokens per skill.
2. When your request matches a description, it loads that skill’s full SKILL.md. The spec recommends keeping it under 5,000 tokens and 500 lines.
3. While it works, it opens the skill’s other files (scripts, reference notes, templates) only when the instructions point to them.

That is why you can install dozens of skills without slowing the agent down. It is also why the description matters most: a vague one (“Helps with videos”) is never picked, while a specific one (“Make a product launch video from screenshots”) is.

You can also call a skill by name. In Claude Code and Cursor, type /skill-name; in Codex, type $skill-name or run /skills.

Where skills live

Each agent reads skills from a personal folder (every project) and a project folder (shared with everyone who works in that repository):

Agent	Personal	Project
Claude Code	~/.claude/skills/	.claude/skills/
Codex	~/.agents/skills/	.agents/skills/
Cursor	~/.cursor/skills/ or ~/.agents/skills/	.cursor/skills/ or .agents/skills/
Gemini CLI	~/.gemini/skills/ or ~/.agents/skills/	.gemini/skills/ or .agents/skills/

Cursor also reads Claude Code’s and Codex’s folders, so a skill installed for one often works in the other.

How to install a skill

• Copy the folder into one of the folders above. This always works.
• npx skills add owner/repo installs skills from a GitHub repo into the agents you choose; add --skill <name> for one skill and -g for every project.
• Claude Code plugins: /plugin marketplace add owner/repo, then /plugin install <name>@<marketplace>.
• Gemini CLI: gemini skills install <git URL or folder>.
• Codex: $skill-installer adds skills from OpenAI’s catalog or another repo.

After installing, just describe the task. You don’t have to name the skill.

Skills, MCP servers and project instructions

These three are often mixed up:

• A skill is instructions plus files that load only when a task needs them.
• An MCP server is a separate program that gives the agent new tools, such as calling an image model’s API. A skill can use one, but doesn’t have to.
• Project instructions (CLAUDE.md, AGENTS.md) load in every session. Use them for rules that always apply, and skills for tasks you do now and then.

Before you install a skill, read it. A skill can tell your agent to run its scripts, so treat it like any code you download.

Skills on Glidezo

Every Glidezo skill is one of these folders, and each page shows a real result made by the skill.

• Code skills write a HyperFrames composition and render it on your computer: a launch video, animated captions, a logo reveal or a YouTube thumbnail, among others. They are free, with no API key and no cost per video.
• AI model skills call a video or image model. Today you run them online with credits, like virtual staging; downloads that use your own API key are planned.