The SKILL.md Format Explained
The SKILL.md format is the open specification for defining AI agent skills. It's designed to be human-readable, agent-parseable, and version-controllable. This article breaks down every part of the format.
File Structure
Every SKILL.md file has two parts:
- Frontmatter — YAML metadata between
---delimiters - Body — Markdown content with structured instructions
---
name: my-skill
version: 1.0.0
description: What this skill does
---
# Skill Instructions
The actual instructions for the agent...
Frontmatter Fields
Required Fields
| Field | Type | Description |
|-------|------|-------------|
| name | string | Unique skill identifier (lowercase, hyphens allowed) |
| version | string | Semantic version (e.g., 1.2.3) |
| description | string | One-line description of what the skill does |
Optional Fields
| Field | Type | Description |
|-------|------|-------------|
| agents | string[] | Compatible agents (claude-code, codex, cursor, etc.) |
| tags | string[] | Searchable tags for discovery |
| author | string | Skill author or organization |
| license | string | SPDX license identifier |
| repository | string | Source repository URL |
| env | object | Required environment variables |
Agent Compatibility
The agents field declares which AI agents can execute this skill. If omitted, the skill is assumed to be agent-agnostic.
agents:
- claude-code
- codex
- cursor
- windsurf
Environment Variables
Skills can declare required environment variables without exposing their values:
env:
DEPLOY_TOKEN:
description: "API token for deployment"
required: true
REGION:
description: "Target deployment region"
default: "us-east-1"
Body Content
The body is standard Markdown. While there's no strict structure required, we recommend organizing content into clear sections:
Recommended Structure
## Overview
Brief description of what the skill accomplishes.
## Prerequisites
What needs to be in place before running.
## Steps
The actual instructions the agent will follow.
## Guardrails
Safety constraints and things the agent should NOT do.
## Expected Output
What success looks like.
Guardrails and Safety
The guardrails section is critical for production skills. It defines boundaries the agent must respect:
## Guardrails
- NEVER delete files without explicit user confirmation
- NEVER commit directly to the main branch
- ALWAYS run tests before proposing changes
- ALWAYS validate environment variables before deployment
Agents that support SKILL.md will parse these as hard constraints during execution.
Versioning
SKILL.md uses semantic versioning (semver):
- MAJOR (1.0.0 → 2.0.0) — Breaking changes to skill behavior
- MINOR (1.0.0 → 1.1.0) — New capabilities, backward-compatible
- PATCH (1.0.0 → 1.0.1) — Bug fixes, wording improvements
When you push a skill to SkillReg, the registry enforces valid semver and prevents version conflicts.
Real-World Example
Here's a complete SKILL.md for a code review skill:
---
name: code-review
version: 2.1.0
description: Review pull requests for code quality, security, and best practices
agents:
- claude-code
- codex
tags:
- review
- quality
- security
author: "@acme-corp"
---
## Overview
Review the current pull request for code quality issues, security vulnerabilities,
and adherence to team coding standards.
## Steps
1. Read all changed files in the PR
2. Check for common security issues (SQL injection, XSS, secrets in code)
3. Verify test coverage for new code paths
4. Check naming conventions and code style
5. Provide a summary with actionable feedback
## Guardrails
- NEVER approve a PR automatically
- NEVER modify code — only suggest changes
- Flag any hardcoded credentials as critical issues
Want to learn more? Check the complete SKILL.md reference or get started with SkillReg.