What Information Belongs in the YAML Frontmatter of a SKILL.md File

Every SKILL.md file in the OpenAI plugins repository requires a YAML frontmatter block containing exactly two required fields: name and description.

The frontmatter serves as the discovery mechanism for the runtime system, enabling the UI to display skill identifiers and summaries while routing commands to the appropriate helpers. When building skills for the OpenAI plugins ecosystem, understanding the precise metadata requirements ensures your helper integrates seamlessly with the platform.

Required Fields in SKILL.md Frontmatter

The OpenAI plugins runtime strictly enforces the presence of two metadata keys. Without these, the skill will not function correctly in the discovery pipeline.

The name Field

The name field provides a short, human-readable identifier for the skill. This string appears in the user interface and acts as the routing key when the system directs commands to specific helpers. According to the source code in plugins/zotero/skills/zotero/SKILL.md, valid names are concise, lowercase identifiers that reflect the service or capability being exposed.

The description Field

The description field contains a concise, one-sentence summary explaining what the skill does. This text renders when the skill is suggested or listed in the UI, helping users understand the capability before invocation. As implemented in plugins/google-drive/skills/google-sheets/SKILL.md, effective descriptions include usage contexts to guide the model toward appropriate tool selection.

Optional Fields and Extensions

While the core runtime only requires name and description, many skills include optional metadata for enhanced UI rendering. Common additions include:

• icon – A reference to an icon asset for visual identification in the interface.
• logo – A larger brand asset displayed in detailed skill views.
• Custom tags – Domain-specific categorization for filtering and organization.

The repository does not enforce these optional fields, but including them improves discoverability when UI components support rich metadata.

Real-World Examples from the OpenAI Plugins Repository

The following examples demonstrate the frontmatter pattern across different plugin domains:

Zotero Skill (plugins/zotero/skills/zotero/SKILL.md):

---
name: Zotero
description: Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, …
---

Google Sheets Skill (plugins/google-drive/skills/google-sheets/SKILL.md):

---
name: google-sheets
description: Analyze and edit connected Google Sheets with range precision. Use when the user wants to create Google Sheets, inspect tabs or ranges, plan formulas, …
---

CircleCI Config Skill (plugins/circleci/skills/config/SKILL.md):

---
name: circleci-config
description: Optimize CircleCI configuration for speed, reliability, and maintainability. Use when users ask to improve .circleci/config.yml, reduce CI runtime, …
---

These examples confirm that regardless of the plugin domain—whether referencing external APIs like Zotero, cloud services like Google Sheets, or configuration files like CircleCI—the frontmatter structure remains consistent.

Summary

• Every SKILL.md file must begin with a YAML frontmatter block delimited by triple dashes (---).
• Only two fields are strictly required: name for identification and description for capability explanation.
• Optional fields such as icon, logo, or custom tags may be added for UI enhancement but are not validated by the core runtime.
• The frontmatter appears at the very top of the file, immediately preceding the Markdown content.

Frequently Asked Questions

What are the required fields in the YAML frontmatter of a SKILL.md file?

The runtime requires exactly two fields: name and description. The name field identifies the skill for routing and UI display, while the description field provides a one-sentence summary of functionality. Both fields must be present in the frontmatter block at the top of the file.

Can I include custom metadata fields in the SKILL.md frontmatter?

Yes, you may include additional fields such as icon, logo, or custom tags, but these are optional. The core runtime only validates the presence of name and description. Any extra metadata serves purely for UI rendering or organizational purposes within specific implementations.

Where should the YAML frontmatter block be placed in a SKILL.md file?

The frontmatter block must appear at the absolute beginning of the file, starting with --- on the first line, followed by the key-value pairs, and closing with another ---. No content, including whitespace or comments, should precede the opening delimiter.

What happens if I omit the required fields from the SKILL.md frontmatter?

If either name or description is missing, the skill will fail to register correctly in the OpenAI plugins runtime. The discovery system relies on these fields to populate the UI and route requests, so their absence prevents the skill from being listed or invoked by the model.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}