mdskills
← Specs

What is a skill.md file?

A skill.md file (also written SKILL.md) is a Markdown file with YAML frontmatter that packages domain expertise for AI coding agents. Drop one into your project and Claude Code, Cursor, or Codex activates it automatically when the task matches. Every skill.md file is free to download, and the format is the open standard maintained at agentskills.io.

What problem does it solve?

Without skills, you repeat the same complex prompts every time you want an agent to do something specific — generate a PDF, build a design system, write Playwright tests. SKILL.md packages those instructions once so any compatible agent can pick them up automatically. Skills are loaded on demand, so they don't bloat your agent's context window.

How it works

A skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions. At minimum, a skill needs a name and description.

---
name: pdf-processing
description: Extract text and tables from PDF files,
merge documents, fill forms, and convert to images.
license: MIT
compatibility:
- Claude Code
- Cursor
allowed-tools: Bash(python:*) Read Write
---
# PDF Processing
When the user asks you to work with PDF files, follow
these instructions...

Frontmatter fields

FieldRequiredDescription
nameYesUnique identifier. Max 64 chars, lowercase letters, numbers, hyphens.
descriptionYesWhat the skill does and when to activate it. Max 1024 chars.
licenseNoSPDX license identifier or reference to a license file.
compatibilityNoList of compatible agents and environment requirements.
metadataNoArbitrary key-value pairs (author, version, tags).
allowed-toolsNoSpace-delimited list of pre-approved tools for the agent.

How to install a skill.md file

Three ways to install a skill.md file, matching how each AI coding agent expects it:

  1. Download and drop. Click Download on any skill page on mdskills.ai. Place theSKILL.mdinside .claude/skills/<name>/(Claude Code), .cursor/skills/(Cursor), or the equivalent for your agent.
  2. Install from the terminal.
    npx mdskills install owner/skill-name
  3. Clone the repo. Every skill listing links to its GitHub source. Clone or fork the repo and copy the folder into your project.

How to download a skill.md file

Every skill on mdskills.ai has a green Download button on its detail page. Downloads are free. You get either the raw SKILL.mdfile (for standalone skills) or a .ziparchive of the skill folder (when the skill includes scripts, references, or assets alongside the SKILL.md).

skill.md vs AGENTS.md vs cursorrules

FormatLoad modelBest for
SKILL.mdOn-demand, description-based activationDeep, domain-specific knowledge you don't want in every session
AGENTS.mdEvery session, always loadedBaseline project conventions and cross-agent instructions
CLAUDE.mdEvery session, Claude Code onlyClaude Code-specific instructions and project state
.cursorrulesEvery session, Cursor onlyCursor-specific rules and behavior overrides

Progressive disclosure

Skills use a three-phase loading model to keep context windows efficient:

  1. Discovery — Agent reads only the name and description (~100 tokens)
  2. Activation — When a task matches, the full SKILL.md is loaded (<5000 tokens)
  3. Execution — Agent follows instructions, loading referenced files as needed

Who supports it

The SKILL.md format is supported by Claude Code, Cursor, OpenAI Codex, Gemini CLI, VS Code, GitHub Copilot, Amp, Roo Code, Goose, Windsurf, Continue, and many more. The full list of compatible agents is maintained at agentskills.io.

Related specs

  • AGENTS.md — project-level context (loaded every prompt, not on demand)
  • CLAUDE.md — Claude-specific project rules
  • MCP — for connecting agents to external tools and services

Official Specification

The full SKILL.md specification is maintained at agentskills.io.

Read the full specification