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

> Master the google/skills Skill Definition Structure. Learn how YAML metadata and Markdown documentation combine to create powerful learning units. Explore the SKILL.md file and references directory for comprehensive understanding.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: deep-dive
- Published: 2026-08-16

---

**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`](https://github.com/google/skills/blob/main/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)](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`](https://github.com/google/skills/blob/main/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)](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`](https://github.com/google/skills/blob/main/SKILL.md) focused while allowing readers to explore advanced topics.

*Example:* [`skills/cloud/workload-manager-basics/references/`](https://github.com/google/skills/tree/main/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/`](https://github.com/google/skills/tree/main/skills)

## Creating a New Skill: Complete Examples

### Skeleton [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)

```yaml
---
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:
   ```bash
   gcloud auth application-default login
   ```

## Quick Client Library Example (Python)

```bash
pip install google-cloud-example

```

```python
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](references/core-concepts.md)
- [Client Library Usage](references/client-library-usage.md)

```

### 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`](https://github.com/google/skills/blob/main/README.md) (repo root) | Repository overview and contribution guidelines |
| [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/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)](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)](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)](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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md) and `references/`. For example: [`skills/cloud/workload-manager-basics/scripts/validate-setup.sh`](https://github.com/google/skills/blob/main/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.