SKILL.md Format

Complete specification of the SKILL.md file format and frontmatter fields. Learn how to structure skills for maximum compatibility across AI agents.

Overview

SKILL.md is a Markdown file with YAML frontmatter that defines an AI agent skill. It is the standard format recognized by all major AI coding agents including Claude, Codex, and Cursor. The frontmatter declares metadata (name, version, tags, environment variables), while the Markdown body contains the actual instructions the agent will follow.

File Structure

Every SKILL.md follows the same two-part structure: YAML frontmatter enclosed in --- fences, followed by Markdown content.

SKILL.md
---
[YAML frontmatter]
---

# Skill Name

[Markdown content with instructions]

Frontmatter Fields

The YAML frontmatter declares metadata about the skill. Only name is required — all other fields are optional but recommended.

name (required)

The unique identifier for the skill. Must be 2–64 characters, lowercase alphanumeric with dots, hyphens, and underscores allowed. Must start and end with an alphanumeric character.

  • Type: string
  • Pattern: ^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$
  • Length: 2–64 characters
  • Examples: my-skill, api.docs.generator, lint_config_v2

description (optional)

A short description of what the skill does. Displayed in search results and skill detail pages.

  • Type: string
  • Max length: 500 characters

metadata.author (optional)

The name of the skill author or organization.

  • Type: string
  • Max length: 100 characters

metadata.version (optional)

The skill version in semantic versioning format. Used by the registry to track releases and resolve version ranges during pull.

  • Type: string
  • Format: Semver — X.Y.Z with optional -prerelease or +build suffixes
  • Examples: 1.0.0, 2.3.1-beta.1, 0.1.0+build.42

metadata.tags (optional)

An array of keywords that describe the skill. Tags are used for search and discovery in the registry.

  • Type: string[]
  • Max items: 10
  • Max length per tag: 32 characters

env (optional)

An array of environment variable declarations. These define configuration values that the skill expects at runtime. See the dedicated section below.

  • Type: object[]
  • Max items: 20

Environment Variable Declarations

The env array lets a skill declare the environment variables it needs. When a skill is pulled, the CLI can prompt the user to set these values. Each entry supports the following fields:

name (required)

The variable name, in SCREAMING_SNAKE_CASE.

description (required)

A human-readable description of what the variable is used for. Max 200 characters.

required (optional)

Whether the variable must be set for the skill to work. Defaults to true.

default (optional)

A default value used when the variable is not explicitly set.

Environment variable example
env:
  - name: API_BASE_URL
    description: "Base URL for API endpoints"
    required: true
  - name: OUTPUT_FORMAT
    description: "Output format (markdown, html, json)"
    required: false
    default: "markdown"

Complete Example

A full SKILL.md using all available frontmatter fields:

api-docs-generator/SKILL.md
---
name: api-docs-generator
description: "Generate comprehensive API documentation from source code"
metadata:
  author: "Acme Corp"
  version: "1.2.0"
  tags:
    - documentation
    - api
    - openapi
env:
  - name: API_BASE_URL
    description: "Base URL for API endpoints"
    required: true
  - name: OUTPUT_FORMAT
    description: "Output format (markdown, html, json)"
    required: false
    default: "markdown"
---

# API Docs Generator

## Instructions

When the user asks you to generate API documentation, follow these rules:
- Scan the project for route handlers and controller files
- Extract endpoint paths, HTTP methods, request/response types
- Generate OpenAPI 3.0 compliant documentation
- Include example requests and responses for each endpoint

## Examples

Given a Next.js project with API routes in `app/api/`,
generate a complete `docs/api-reference.md` with all endpoints
documented including query parameters, request bodies, and
response schemas.

Minimal Example

Only the name field is required. This is the smallest valid SKILL.md:

my-skill/SKILL.md
---
name: my-skill
---

# My Skill

When the user asks for help with this task, follow these steps:
1. Analyze the current codebase
2. Apply the appropriate changes
3. Verify the result

Validation Rules

The CLI and registry enforce the following constraints when parsing SKILL.md:

  • name is required and must match the pattern ^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$ (2–64 chars)
  • description must not exceed 500 characters
  • metadata.author must not exceed 100 characters
  • metadata.version must be valid semver if provided
  • metadata.tags allows at most 10 tags, each up to 32 characters
  • env allows at most 20 variable declarations
  • Each env entry must have both name and description
  • env[].name must be in SCREAMING_SNAKE_CASE
  • env[].description must not exceed 200 characters
  • env[].required defaults to true if omitted

Name must match directory

The name field in the frontmatter should match the directory name of the skill. A mismatch will produce a warning during skillreg push and may cause unexpected behavior when pulling or resolving skills.

Validate before pushing

Use skillreg push --dry-run to validate your SKILL.md without uploading anything. The CLI will report any frontmatter errors before packaging.