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

> Master the required format for OpenAI plugin skill descriptions. Learn the essential frontmatter fields name description license and metadata for seamless plugin development.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Every skill in the OpenAI Plugins repository requires a YAML frontmatter block at the top of its [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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 vs. Full-Featured Examples

### Minimal Valid Frontmatter

For a bare-bones skill that meets all requirements, structure your [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) like this:

```yaml
---
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...

```

### Full-Featured Frontmatter

Production skills often include optional fields for categorization:

```yaml
---
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:

```python
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:

- **Airtable Overview**: [[`plugins/airtable/skills/airtable-overview/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/airtable/skills/airtable-overview/SKILL.md)](https://github.com/openai/plugins/blob/main/plugins/airtable/skills/airtable-overview/SKILL.md)
- **Zoom Apps SDK**: [[`plugins/zoom/skills/zoom-apps-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/SKILL.md)](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/SKILL.md)
- **Metric Pack Designer**: [[`plugins/plugin-eval/skills/metric-pack-designer/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/skills/metric-pack-designer/SKILL.md)](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/skills/metric-pack-designer/SKILL.md)
- **Build ChatGPT App**: [[`plugins/openai-developers/skills/build-chatgpt-app/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/openai-developers/skills/build-chatgpt-app/SKILL.md)](https://github.com/openai/plugins/blob/main/plugins/openai-developers/skills/build-chatgpt-app/SKILL.md)
- **Vulnerability Write-up**: [[`plugins/codex-security/skills/vulnerability-writeup/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/codex-security/skills/vulnerability-writeup/SKILL.md)](https://github.com/openai/plugins/blob/main/plugins/codex-security/skills/vulnerability-writeup/SKILL.md)

## Summary

- **Every [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.