Understanding the Skill Definition Structure in google/skills: A Complete Guide

A skill definition in google/skills is a self-contained learning unit combining YAML front-matter metadata with Markdown documentation, located at skills/<category>/<skill-name>/SKILL.md and optionally supplemented by a references/ subdirectory for deeper technical content.

The google/skills repository provides a standardized format for documenting cloud-related learning tasks. Whether you're consuming existing skills or authoring new ones, understanding this structure ensures you can navigate the catalog efficiently and contribute consistent content.

YAML Front-Matter: The Metadata Layer

Every SKILL.md file begins with a YAML block delimited by triple dashes (---). This header supplies the Skills platform with machine-readable metadata used for catalog generation and filtering.

Required Fields

Field	Purpose	Example
name	Short kebab-case identifier for programmatic reference	workload-manager-basics
metadata	Nested map containing descriptors like category	category: CloudObservabilityAndMonitoring
description	One-sentence summary for skill listings	"Use this skill to manage Google Cloud Workload Manager evaluations…"

The name field must match the containing directory name. The metadata.category value determines where the skill appears in the organizational hierarchy.

Source: [skills/cloud/workload-manager-basics/SKILL.md](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/SKILL.md)

Markdown Body: The Learning Content

After the YAML block, the remainder of SKILL.md contains standard Markdown documentation. While section order is flexible, most skills include these common elements:

Standard Sections

• Title (# …) — Human-readable skill name

• Overview — High-level product or concept description

• Use This Flow — Optional Mermaid workflow diagram

• Core API Constraints — Important restrictions (e.g., "Public surface only")

• Prerequisites — Commands to enable APIs, authenticate, and grant IAM roles

• Quick Client Library Example — Minimal code snippet (Python, Go, or Java)

• Reference Directory — Links to references/ files for deeper dives

• Authoritative References — External links to official Google Cloud documentation

• Additional Context — Optional troubleshooting or community notes

The Skills UI automatically generates a navigable table of contents from these headings.

Source: Body structure in [skills/cloud/workload-manager-basics/SKILL.md](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/SKILL.md)

The references/ Subdirectory

Each skill may include a references/ folder containing auxiliary markdown files:

• core-concepts.md — Fundamental definitions
• client-library-usage.md — Language-specific code samples
• rest-usage.md — Raw HTTP request/response examples
• iam-security.md — Role recommendations and least-privilege guidance

These files are linked from the "Reference Directory" section, keeping the main SKILL.md focused while allowing readers to explore advanced topics.

Example: skills/cloud/workload-manager-basics/references/

Directory Layout and Naming Conventions

All skills follow a consistent filesystem structure according to the google/skills source code:

skills/
└── <category>/
    └── <skill-name>/
        ├── SKILL.md              # Main definition (required)

        ├── references/           # Supplemental docs (optional)

        │   ├── core-concepts.md
        │   └── client-library-usage.md
        └── scripts/              # Helper utilities (optional)

• Path pattern: skills/<category>/<skill-name>/
• Folder name: Must match the name field in YAML front-matter
• No executable code in SKILL.md: All samples are static markdown
• scripts/ directory: Optional location for demo or validation utilities

Source: skills/

Creating a New Skill: Complete Examples

Skeleton SKILL.md

---
name: my-new-skill
metadata:
  category: ExampleCategory
description: >-
  One-sentence summary that tells readers when to use this skill.
---

# My New Skill

## Overview

A brief description of the technology or task covered by the skill.

## Prerequisites

1. Enable the required API:
   ```bash
   gcloud services enable example.googleapis.com --quiet

2. Authenticate with ADC:

   gcloud auth application-default login

Quick Client Library Example (Python)

pip install google-cloud-example

from google.cloud import example_v1

client = example_v1.ExampleClient()

# Replace with a real request

response = client.list_resources()
print(response)

Reference Directory

• Core Concepts
• Client Library Usage

### Sample [`references/core-concepts.md`](https://github.com/google/skills/blob/main/references/core-concepts.md)

```markdown

# Core Concepts

* **Resource** — The primary object the API operates on.
* **Project** — The GCP container that owns resources.
* **IAM Role** — Grants permissions required for the API calls.

For a full list of fields, see the official API reference:
https://cloud.google.com/example/docs/reference/rest

Reference: Key Files in the Repository

Path	Purpose
skills/<category>/<skill-name>/SKILL.md	Main skill definition with YAML front-matter and Markdown
skills/<category>/<skill-name>/references/	Supplemental technical documentation
skills/<category>/<skill-name>/scripts/	Optional demo/validation utilities
README.md (repo root)	Repository overview and contribution guidelines
CONTRIBUTING.md (repo root)	New skill authoring and review process

Example Skill Paths

• Workload Manager: [skills/cloud/workload-manager-basics/SKILL.md](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/SKILL.md)
• GKE Multi-Tenancy: [skills/cloud/gke-multitenancy/SKILL.md](https://github.com/google/skills/blob/main/skills/cloud/gke-multitenancy/SKILL.md)
• Analytics Data API: [skills/analytics/google-analytics-data-api-basics/SKILL.md](https://github.com/google/skills/blob/main/skills/analytics/google-analytics-data-api-basics/SKILL.md)

Summary

• Skill definitions in google/skills combine YAML metadata with Markdown content in a single SKILL.md file
• The YAML front-matter (delimited by ---) provides name, metadata.category, and description for catalog generation
• The Markdown body follows flexible conventions including Overview, Prerequisites, Quick Examples, and Reference Directory sections
• The references/ subdirectory houses deep-dive content linked from the main skill file
• Directory naming must match the YAML name field: skills/<category>/<skill-name>/
• ** Supporting scripts** go in optional scripts/ folders, never in SKILL.md itself

Frequently Asked Questions

What happens if the directory name doesn't match the YAML name field?

The Skills platform relies on consistency between the filesystem path and the name field for catalog indexing and cross-referencing. Mismatches may cause the skill to appear incorrectly in listings or break internal links. Always verify that skills/<category>/<name>/ aligns with the name: value in your YAML front-matter.

Can I include multiple programming languages in the Quick Client Library Example section?

Yes. While most skills lead with a primary language (typically Python), you can include additional tabs or subsections for Go, Java, Node.js, or others. Place language-specific samples in the references/client-library-usage.md file if they become lengthy, and link to them from the main skill.

Is the references/ directory strictly required?

No. The references/ folder is optional. Simple skills with minimal scope can include all necessary content directly in SKILL.md. Add the subdirectory only when your topic requires substantial supplementary material like detailed REST examples, extensive IAM guidance, or multi-language client library coverage.

Where should I put validation or demo scripts?

Place executable scripts in a scripts/ directory at the same level as SKILL.md and references/. For example: skills/cloud/workload-manager-basics/scripts/validate-setup.sh. These utilities are completely optional and must not be embedded in the skill definition file itself.

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