# How to Define Skill Metadata in SKILL.md: A Complete Guide to Categories and Descriptions > Learn to define skill metadata like category and description in SKILL.md files within the google/skills repository. Enhance skill organization and searchability. - Repository: [Google/skills](https://github.com/google/skills) - Tags: how-to-guide - Published: 2026-09-04 --- **Each SKILL.md file in the google/skills repository uses a YAML front-matter block to define metadata such as category and description, enabling the Instagit runtime to organize, search, and display skills correctly.** The google/skills repository powers the Instagit platform, where each capability is defined by a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file containing executable instructions and documentation. Properly defining skill metadata ensures your skills appear in the correct UI categories, support search indexing, and provide contextual help to users browsing the platform. ## Understanding the SKILL.md Front-Matter Structure Every [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file begins with a YAML front-matter block delimited by triple dashes (`---`). Within this block, the `metadata` map contains structured fields that the Instagit engine parses at runtime to categorize and describe the skill. If this front-matter block is omitted, the skill will still load but will lack category grouping and descriptive text, significantly reducing discoverability across the platform. ### Required and Optional Metadata Fields The `metadata` section supports several key fields: - **`category`** – Groups the skill under a logical domain such as *Containers*, *Analytics*, or *Ads* - **`description`** – A markdown-compatible paragraph explaining the skill's purpose and usage - **`name`** – Optional identifier that often mirrors the folder name for clarity ## Defining Category and Description Metadata To define skill metadata in SKILL.md, you must structure the YAML front-matter with precise key placement. The Instagit parser expects the `metadata` map to contain the `category` field, while the `description` field typically sits at the root level of the front-matter block. ### Specifying the Category Field The `category` field within the `metadata` map determines where your skill appears in the Instagit UI navigation. Valid categories align with organizational domains like *Containers*, *Ads*, or *Analytics*. ```yaml --- metadata: category: Containers --- ``` This categorization enables users to browse related skills together and allows the platform to filter capabilities by functional area. ### Writing the Description Field The `description` field accepts free-form text using the YAML folded style (`>-`) to support multi-line strings without preserving line breaks. This text appears in skill listings, tooltips, and help pages. ```yaml --- description: >- Manages core GKE cluster provisioning, credentials, Autopilot vs Standard selection, and workload deployment. Use when creating GKE clusters, fetching kubectl credentials, or configuring Workload Identity. --- ``` The description should clearly articulate what the skill does and when to invoke it, as this content surfaces directly in search results and UI cards. ### Adding the Optional Name Identifier While the system can infer the skill name from the directory structure, explicitly defining the `name` field in the front-matter provides clarity and ensures consistent referencing across the platform. ```yaml --- name: gke-basics metadata: category: Containers --- ``` ## Complete SKILL.md Metadata Examples The following examples from the google/skills repository demonstrate practical implementations of skill metadata definitions. ### Full Metadata with Category and Description In [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md), the metadata block includes all three fields to maximize discoverability: ```yaml --- name: gke-basics metadata: category: Containers description: >- Manages core GKE cluster provisioning, credentials, Autopilot vs Standard selection, and workload deployment. Use when creating GKE clusters, fetching kubectl credentials, configuring Workload Identity, or deciding between Autopilot and Standard modes. --- ``` This structure ensures the skill appears under the *Containers* category while providing comprehensive context for users evaluating its capabilities. ### Alternative Field Ordering The [`skills/cloud/gke-cluster-creation/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-cluster-creation/SKILL.md) file demonstrates that field order within the front-matter is flexible. Here, the `description` precedes the `metadata` block, yet the Instagit parser correctly extracts the category information: ```yaml --- name: gke-cluster-creation description: >- Plans and executes GKE cluster creation, provisioning, and production readiness audits using pre‑defined templates (Autopilot, Standard Regional, GPU/AI Inference, AI Hypercompute). Use when creating GKE clusters, provisioning GKE environments, selecting cluster modes, or auditing GKE clusters. metadata: category: Containers --- ``` ### Minimal Metadata Configuration For simple skills where a description is unnecessary, you can provide only the category metadata. The [`skills/ads/google-ads-api-quickstart/SKILL.md`](https://github.com/google/skills/blob/main/skills/ads/google-ads-api-quickstart/SKILL.md) file uses this approach to ensure proper categorization without verbose documentation: ```yaml --- metadata: category: Ads --- ``` This minimal configuration still enables the skill to appear in the *Ads* category group within the Instagit UI. ## How Metadata Impacts the Instagit Platform When you define skill metadata in SKILL.md files according to these patterns, the Instagit engine surface-feeds this information to downstream components. The category drives UI organization and navigation trees, while the description populates search indexes and contextual help panels. Skills lacking this metadata remain functional but invisible to category-based browsing and provide no explanatory context in search results, reducing adoption and usability. ## Summary - Begin each [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) with a YAML front-matter block enclosed in triple dashes to define skill metadata - Place the `category` field inside a `metadata` map to enable proper UI organization and browsing - Use the `description` field with `>-` folded style for readable multi-line explanations that appear in search results - Include an optional `name` field for explicit skill identification, though the system can infer this from directory names - Reference existing implementations like [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md) for proven metadata patterns ## Frequently Asked Questions ### Where does the metadata block go in a SKILL.md file? The metadata must appear at the very beginning of the [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file as a YAML front-matter block starting and ending with `---`. The Instagit parser reads this section before processing the markdown content, extracting the `metadata` map and description fields to build the skill's index entry. ### What happens if I omit the category metadata? If you omit the `metadata` block or the `category` field within it, the skill will still execute when invoked, but it will not appear in any category groups within the Instagit UI. Users must know the exact skill name to access it, significantly limiting discoverability compared to properly categorized skills. ### Can I use markdown formatting inside the description field? Yes, the `description` field supports markdown-compatible text. While the examples in [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md) use plain text with the `>-` folded style, you can include standard markdown syntax that will render correctly in UI tooltips and help pages, allowing for formatted lists or code references when necessary. ### Is the name field required if the folder already describes the skill? No, the `name` field is optional. According to the source structure in [`skills/cloud/gke-cluster-creation/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-cluster-creation/SKILL.md), the Instagit runtime can infer the skill identifier from the directory name. However, explicitly defining `name` ensures consistency and clarity, particularly when the folder structure uses hyphens or abbreviations that differ from the preferred display name.