SKILL.md Specification: Complete Format Guide

Quick Answer: A SKILL.md file uses YAML frontmatter for metadata (name, version, description, compatibility) followed by markdown content with the skill's instructions. It works across Claude Code, Cursor, Codex CLI, OpenCode, and 20+ other agents. Place it in your agent's .skills/ directory.

The SKILL.md format is the open standard for AI agent skills. It defines how to package instructions that teach any compatible agent a new capability. This guide covers the complete specification with production examples.

File structure

A SKILL.md file has two parts. YAML frontmatter at the top defines metadata. Markdown content below defines the skill's behavior and instructions.

The YAML frontmatter is enclosed in triple-dash delimiters (---) and contains fields like name, version, description, author, tags, and agent compatibility. The markdown content that follows contains the actual instructions the agent reads and follows.

Recommended skills

Agent Evaluation & Regression Suite — Score Skills Before You Ship

by Vivek K

Designs a scored eval suite for an AI agent or SKILL.md skill, measures trigger…

$15

Yaml Finetune Studio

by Edric Vale

Use to fine-tune open LLMs with Axolotl: write YAML configs for LoRA, QLoRA, DPO…

$5

kubernetes-manifest-reviewer

by Timoranjes

Professional-grade Kubernetes YAML auditor for security, API deprecations, and d…

Free

Browse all Skill Md skills

Required and recommended fields

The minimum viable SKILL.md file needs a title (as an H1 heading) and instructions for the agent. In practice, you should include YAML frontmatter with at least name, version, and description for proper marketplace listing and agent recognition.

Recommended frontmatter fields: name (string), version (semver), description (one-line summary), author (creator name or handle), tags (array of category tags), agents (array of compatible agents like claude-code, cursor, codex-cli).

Markdown content structure

The markdown body typically includes: a summary of what the skill does, when to activate (trigger conditions), step-by-step instructions the agent follows, output format specifications, example inputs and outputs, and any constraints or limitations.

The best skills are specific and prescriptive. Instead of "review the code," a good skill says "scan each file for five categories: logic bugs, security vulnerabilities, performance issues, maintainability problems, and architectural inconsistencies. Rate each finding as Critical, Warning, or Suggestion."

Production examples

For real SKILL.md examples from production skills, see SKILL.md examples and the format reference.

To see how 2,000+ skills implement the format in practice, browse the Agensi marketplace. Each skill page shows the full SKILL.md structure.

Creating your own

The fastest way to create a SKILL.md file is to start from an existing template. Download any free skill from Agensi, study its structure, and modify it for your use case. For a step-by-step creation guide, see how to create a SKILL.md from scratch.

If you build something useful, you can list it on the Agensi marketplace and earn 70% of every sale. See the creator guide for details.