SKILL.md Specification: Complete Format Guide
The complete SKILL.md specification: YAML frontmatter, markdown structure, required fields, and production examples.
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
prompt-spec-engineer (support Auto rewrite prompt)
by Roy Yuen
Turn vague prompts into professional task specifications, optimized prompts, and…
Kubernetes Config Error Detective
by Shandra
Audits Kubernetes manifests, Helm values, deployment logs, and service configs t…
designing-hybrid-context-layers
by https://loreto.io · 16
Architects the right retrieval strategy for every query — teaching your agent wh…
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 1,600+ 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.