How a Skill Is Defined in the SKILL.md Format

A skill in the Google Skills repository is a Markdown document with a YAML front‑matter block followed by standard Markdown content, enabling both human‑readable documentation and machine‑parseable metadata.

The SKILL.md format is the core contract that powers the google/skills ecosystem. Every skill—from GKE basics to Google Ads API quickstarts—follows this same structure, allowing tooling, CI pipelines, and registry systems to discover and validate skills without parsing free‑form documentation. This article breaks down the exact specification using concrete examples from the repository source code.

SKILL.md Structure Overview

A SKILL.md file contains two distinct parts:

1. YAML front‑matter between triple‑dash delimiters
2. Markdown body with standard headings, code blocks, and prose

This separation keeps metadata concise for automation while preserving flexibility for detailed documentation.

YAML Front‑Matter Specification

The front‑matter block starts and ends with ---. It must include a name field and a metadata map.

Key	Required	Purpose
name	Yes	Canonical identifier used in URLs and CLI commands
metadata	Yes	Nested map with category and description fields
metadata.category	Yes	High‑level grouping (e.g., Containers, Ads, Analytics)
metadata.description	Yes	One‑sentence summary using YAML block scalar syntax

Optional fields like tags, version, or custom plugin keys can extend the map without breaking existing parsers.

Front‑Matter Example from Source

From skills/cloud/gke-basics/SKILL.md (lines 1‑12):

---
name: gke-basics
metadata:
  category: Containers
  description: >-
    Manages core GKE cluster provisioning, credentials, Autopilot vs Standard selection,
    and workload deployment…
---

The >- block scalar keeps multi‑line descriptions readable in source while collapsing to a single line when parsed.

Markdown Body Conventions

After the closing ---, the document follows standard Markdown with repository‑specific conventions:

• # Top‑level heading — Human‑readable skill title

• ## Section headings — Logical breakdowns: Key Selection Rules, Critical Gotchas, Reference Directory

• Fenced code blocks — CLI commands, YAML snippets, configuration examples

• Internal links — Relative paths like references/core-concepts.md

Body Example from Source

From the same GKE Basics skill (lines 13‑30):

# GKE Basics & Critical Gotchas

Managed Kubernetes platform on Google Cloud. Defaults to Autopilot mode unless Standard is explicitly required.

## Key Selection Rules: Autopilot vs. Standard

* **Default to Autopilot** for almost all workloads.
* **Use Standard ONLY if:** …

The body can span any length—step‑by‑step tutorials, architectural diagrams, troubleshooting guides—while the front‑matter remains fixed and parseable.

Why This Format Enables Automation

The SKILL.md structure delivers three critical capabilities:

• Discoverability — The skill registry lists all skills by reading only front‑matter, never parsing full documents
• CI validation — Pipelines verify required fields exist and Markdown renders without errors
• Extensibility — New metadata keys added to metadata or root level don't break existing YAML parsers

This design creates a self‑contained, version‑controlled definition stored in every skill's directory.

Minimal SKILL.md Template

Copy this template to create a new skill:

---
name: my-skill
metadata:
  category: <Your Category>
  description: >-
    One‑sentence summary of what the skill does. Use the block scalar (`>-`) to keep
    the description readable in the source file.
---

# My Skill Title

A brief introductory paragraph that expands on the description.

## Core Concepts

- **First concept** – explanation.
- **Second concept** – explanation.

## Example Usage

```bash

# Replace with the actual command you want to illustrate

gcloud example command --flag=value

References

• Related docs

## Reference Implementations in the Repository

| File | Demonstrates |
|------|--------------|
| [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md) | Full‑featured Cloud skill with complex metadata |
| [`skills/ads/google-ads-api-quickstart/SKILL.md`](https://github.com/google/skills/blob/main/skills/ads/google-ads-api-quickstart/SKILL.md) | Cross‑domain application (Ads category) |
| [`plugins/cloud/google-cloud-developer/skills/gcloud/SKILL.md`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/skills/gcloud/SKILL.md) | Skill embedded within a plugin directory |

Each file validates that the **SKILL.md definition** remains consistent across contexts—standalone skills, category hierarchies, and plugin bundles.

## Summary

- **SKILL.md** = YAML front‑matter + Markdown body, delimited by `---`
- **Required front‑matter keys**: `name`, `metadata.category`, `metadata.description`
- **Body conventions**: `#` title, `##` sections, fenced code blocks, relative links
- **Design goal**: Human‑readable docs with machine‑parseable metadata for registry automation
- **Extensibility**: Custom fields addable without breaking parsers

This format powers the entire `google/skills` repository, from cloud tooling to advertising APIs.

## Frequently Asked Questions

### What happens if I omit the YAML front‑matter in a SKILL.md file?

The skill registry parser will fail to index the file. According to the `google/skills` source implementation, the front‑matter is mandatory for discovery—tools expect to extract `name` and `metadata` without parsing the full Markdown body. Skills without front‑matter won't appear in listings or CLI commands.

### Can I add custom fields to the front‑matter beyond name and metadata?

Yes. The YAML map is flexible—fields like `tags`, `version`, or plugin‑specific keys can be added without breaking existing parsers. The registry only enforces the presence of `name` and `metadata`; additional keys are ignored by standard tooling but available for custom automation pipelines.

### Does the SKILL.md format support multiple skills in one file?

No. Each SKILL.md defines exactly one skill with a single `name` field. For related skills, the repository uses directory structures: `skills/cloud/gke-basics/` and `skills/cloud/gke-security/` each contain their own SKILL.md, enabling independent versioning and metadata.

### How does the description field handle multi‑line text?

Use the YAML `>-` block scalar (folded style). This preserves line breaks in source for readability while parsing to a single line of text. From [`skills/cloud/gke-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gke-basics/SKILL.md): the description spans four source lines but renders as continuous text in tooling outputs.

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