# What Information Belongs in the YAML Frontmatter of a SKILL.md File > Learn what information belongs in your SKILL.md file's YAML frontmatter. Discover the two required fields name and description for OpenAI plugins. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: best-practices - Published: 2026-09-13 --- **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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/SKILL.md)): ```yaml --- 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`](https://github.com/openai/plugins/blob/main/plugins/google-drive/skills/google-sheets/SKILL.md)): ```yaml --- 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`](https://github.com/openai/plugins/blob/main/plugins/circleci/skills/config/SKILL.md)): ```yaml --- 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.