how-to-guide

Required Format for Skill Descriptions in OpenAI Plugins: Complete Frontmatter Guide

September 10, 2026 openai/plugins ↗

Every skill in the OpenAI Plugins repository requires a YAML frontmatter block at the top of its SKILL.md file containing four mandatory fields: name, description, license, and metadata with version and author subfields.

The OpenAI Plugins repository organizes capabilities into discrete units called skills, each defined in a dedicated SKILL.md file. To ensure the plugin engine can discover, catalog, and execute these skills automatically, developers must follow a strict frontmatter format that declares critical metadata before any documentation content.

The YAML Frontmatter Block

Each skill definition begins with a YAML frontmatter block delimited by triple dashes (---). This block must appear exactly at the top of the file, before any Markdown content, and must be surrounded by opening and closing --- lines.

The parser treats everything between these delimiters as structured metadata. Everything after the closing --- becomes the skill’s documentation body.

Required Frontmatter Fields

The plugin loader enforces four mandatory top-level keys. Any missing field or malformed indentation causes the skill to be ignored during runtime.

name

The name field defines a unique identifier for the skill, serving as its URL-friendly slug. This value must be unique across the repository to prevent registration conflicts.

description

The description field provides a concise, human-readable summary explaining what the skill does. This text appears in discovery interfaces and helps users identify the appropriate skill for their needs.

license

The license field declares the SPDX-compatible license under which the skill is released, such as MIT or Apache-2.0. This enables automated compliance checks and ensures only compatible code enters the publication pipeline.

metadata

The metadata field is a nested map that requires two specific subfields:

  • version: A semantic version string (e.g., '1.0.0') that allows downstream tooling to surface the correct release without parsing the documentation body.
  • author: The owning team or individual responsible for the skill, providing traceable attribution for compliance and security review pipelines.

Minimal Valid Frontmatter

For a bare-bones skill that meets all requirements, structure your SKILL.md like this:

---
name: my-simple-skill
description: Briefly explains the skill's purpose.
license: MIT
metadata:
  version: '0.1.0'
  author: my-team
---

# Skill documentation starts here...

Production skills often include optional fields for categorization:

---
name: data-visualization
description: Generates charts and dashboards from structured datasets.
license: Apache-2.0
metadata:
  version: '2.3.1'
  author: data-analytics
  tags:
    - visualization
    - charts
    - dashboards
  runtime: python3.11
---

# Detailed usage instructions follow...

Parsing Skills Programmatically

You can extract skill metadata using standard YAML parsing libraries. The frontmatter block is the first content between the triple-dash delimiters:

import yaml
import pathlib

def load_skill_frontmatter(path: str) -> dict:
    text = pathlib.Path(path).read_text()
    front = text.split('---')[1]  # grab the block between the dashes

    return yaml.safe_load(front)

skill = load_skill_frontmatter(
    "plugins/airtable/skills/airtable-overview/SKILL.md"
)
print(skill["name"], skill["metadata"]["version"])

# → airtable-overview 1.0.0

Canonical Examples in the Repository

The following files demonstrate the required format in production environments:

Summary

  • Every SKILL.md must begin with a YAML frontmatter block delimited by triple dashes at the very top of the file.
  • Four fields are mandatory: name, description, license, and metadata (containing version and author).
  • Strict YAML compliance is required; malformed frontmatter causes the plugin loader to ignore the skill during runtime.
  • Optional fields such as tags, categories, or runtime may follow the required metadata without affecting core loading.
  • Everything after the closing --- becomes the skill's Markdown documentation body.

Frequently Asked Questions

What happens if I omit a required field in the skill frontmatter?

The plugin loader will ignore the skill during runtime. The frontmatter parser requires all four mandatory fields—name, description, license, and metadata—and any deviation causes the file to be skipped without registration.

Can I add custom fields to the metadata section?

Yes. While version and author are required within the metadata map, you may include additional keys such as tags, runtime, or custom categorization fields. The core loader ignores these optional fields, but custom UI components can read them to enhance discovery interfaces.

Does the frontmatter format support multiline descriptions?

Yes. The description field accepts standard YAML string syntax, including multiline strings using the pipe (|) or folded block (>) indicators. Ensure proper indentation to maintain valid YAML structure and prevent parsing errors.

Where must the frontmatter block appear in the file?

The frontmatter block must appear exactly at the top of the SKILL.md file, before any Markdown content or HTML. The opening --- must be the first characters in the file, followed immediately by the YAML content and closing --- delimiter.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →