How to Define Skill Metadata in SKILL.md: A Complete Guide to Categories and Descriptions

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

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

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

---
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, the metadata block includes all three fields to maximize discoverability:

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

---
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 file uses this approach to ensure proper categorization without verbose documentation:

---
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 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 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 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 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, 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.

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