Structure of a SKILL.md File in the Google Skills Repository

A SKILL.md file is the canonical source-of-truth for a single Google Skills "skill," consisting of YAML front-matter delimited by triple dashes followed by human-readable Markdown documentation.

The structure of a SKILL.md file follows a strict two-part layout defined in the google/skills repository. This format ensures every skill remains machine-parseable while providing comprehensive documentation for developers and AI systems.

YAML Front-Matter Structure

Every SKILL.md file begins with metadata wrapped in triple dashes (---). This block supplies machine-readable attributes that identify and categorize the skill.

Required Fields

The front-matter must include three specific keys:

• name: A short, hyphen-separated identifier used to reference the skill (e.g., gke-basics)
• metadata: A map containing descriptive attributes, typically including category to group the skill (e.g., Containers, Analytics)
• description: A concise summary using the >- block scalar to allow multi-line strings without literal newlines

---
name: <skill-identifier>
metadata:
  category: <category-name>
description: >-
  <concise description of the skill's purpose and usage scenarios>
---

As implemented in google/skills, the front-matter parser requires exact field names and proper YAML syntax. The description field specifically uses folded style (>-) to maintain readability in raw files while rendering as continuous text.

Markdown Body Structure

After the closing --- delimiter, the file contains standard Markdown documenting the skill's implementation details.

Standard Sections

The body typically organizes content into these hierarchical sections:

• Title: An H1 heading repeating the skill name for immediate identification
• Overview: High-level description covering mode defaults and decision criteria for when to apply the skill
• Key Concepts: Bulleted lists of critical terminology and architectural decisions
• Usage Examples: Fenced code blocks demonstrating CLI commands, API calls, or configuration files (commonly Bash, YAML, or JSON)
• References: Relative links to supporting documentation (e.g., references/core-concepts.md)

The Markdown content in skills/cloud/gke-basics/SKILL.md demonstrates this pattern with sections covering Autopilot vs Standard selection, credential configuration, and Workload Identity setup.

Code Examples

Minimal Skill Skeleton

New skills should follow this template structure:

---
name: my-new-skill
metadata:
  category: <Your-Category>
description: >-
  One-sentence summary of what the skill does.
---

# My New Skill

Brief introductory paragraph describing the skill's purpose.

## Key Concepts

- Bullet list of important concepts.
- Architecture decisions and constraints.

## Usage Example

```bash

# Replace with the actual command or API call

gcloud example command --flag=value

References

• Related Docs

### Real-World Implementation (GKE Basics)

The production skill at [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md) illustrates the complete structure:

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

# GKE Basics & Critical Gotchas

## Selection Rules

### Autopilot vs Standard

- Use Autopilot when...

This file demonstrates the >- scalar handling long descriptions and includes practical gcloud container clusters command examples in fenced blocks.

Key File Locations

Reference these concrete implementations in the repository to understand variations across categories:

• skills/cloud/gke-basics/SKILL.md: Fully-featured cloud skill with extensive CLI examples
• skills/developers/finding-google-skills/SKILL.md: Developer-focused skill with minimal metadata footprint
• plugins/cloud/google-cloud-developer/skills/gcloud/SKILL.md: Plugin-level skill demonstrating nested directory structures
• skills/ads/google-ads-api-quickstart/SKILL.md: Ads category implementation showing API-specific documentation patterns

Each file maintains identical front-matter syntax while adapting the Markdown body to domain-specific requirements.

Summary

• Every SKILL.md file contains YAML front-matter wrapped in --- delimiters followed by standard Markdown
• Required front-matter fields are name, metadata (with category), and description using >- block notation
• The Markdown body requires an H1 title and typically includes Overview, Key Concepts, Usage Examples, and References sections
• Repository examples at skills/cloud/gke-basics/SKILL.md and skills/developers/finding-google-skills/SKILL.md demonstrate production-ready implementations

Frequently Asked Questions

What happens if the YAML front-matter is malformed?

The google/skills parser will fail to load the skill into the index. All three required fields (name, metadata, description) must be present with valid YAML syntax, and the block scalars must use proper indentation to avoid parse errors.

Can I use HTML tags inside the Markdown body?

While standard Markdown allows HTML, the canonical structure relies on pure Markdown elements (headings, lists, fenced code blocks) to ensure consistent rendering across different viewers and AI processing pipelines.

How long should the description field in the front-matter be?

The description should be a concise paragraph spanning 1-3 sentences using the >- folded block scalar. This allows the text to wrap in the source file while rendering as a single paragraph, optimizing for both human editing and machine consumption.

Are there specific categories I must use for the metadata field?

The repository uses standardized category values like Containers, Analytics, Ads, and Developers. Check existing files in your target directory (e.g., skills/cloud/ or skills/ads/) to identify the appropriate category taxonomy for your skill's domain.

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