What Is the Structure of a Skill in the Google Skills Repository?

A skill in the Google Skills repository is a self-contained learning unit defined by a SKILL.md file with YAML front-matter, stored in its own directory under skills/ with optional references/, scripts/, and assets/ subdirectories.

The google/skills repository organizes technical learning content into modular, discoverable units. Each skill follows a consistent structure that enables automatic indexing while remaining flexible enough for diverse topic areas. This guide explains the required and optional components based on the actual implementation in the source code.

The Required SKILL.md File

Every skill centers on a single SKILL.md file. This file serves as both metadata declaration and primary documentation.

Front-Matter Header

The top of SKILL.md must contain YAML front-matter with three key fields:

---
name: workload-manager-basics
metadata:
  category: CloudObservabilityAndMonitoring
description: >-
  Learn the basics of Google Cloud Workload Manager...
---

As shown in skills/cloud/workload-manager-basics/SKILL.md lines 1-5, the name and category fields enable tooling to categorize and index the skill automatically. The description provides a human-readable summary.

Document Body Sections

Below the front-matter, the body uses standard markdown to organize learning content. The workload-manager skill demonstrates typical sections:

• Overview – High-level purpose and value proposition
• Core Concepts – Fundamental ideas learners must understand
• Usage Flow – Diagram or description of how to apply the skill
• Prerequisites – Required knowledge or setup
• Quick Client Library Snippets – Runnable code examples
• Reference Directory – Links to supplemental files in references/

These sections appear in skills/cloud/workload-manager-basics/SKILL.md lines 17-34, though individual skills may adapt this structure to their needs.

Optional Subdirectories

Beyond SKILL.md, a skill directory may contain three optional folders:

references/

The references/ directory holds expanded documentation on topics mentioned in the main file. For example, workload-manager-basics links to core-concepts.md and client-library-usage.md from its Reference Directory section (lines 14-24). This separation keeps SKILL.md scannable while allowing deep dives for interested readers.

scripts/

Executable helper scripts live in scripts/ and support demos, validation, or automation. The agent-platform-inference skill includes Python SDK wrappers in this directory, as implemented in skills/cloud/agent-platform-inference/scripts/. Scripts can be any language—Python, Bash, or others—depending on the skill's domain.

assets/

Static files such as images, diagrams, or downloadable resources reside in assets/. These are referenced from markdown using relative paths.

Complete Directory Structure

A fully populated skill follows this layout:

skills/
└─ <category>/
    └─ <skill-name>/
        ├─ SKILL.md              # Required: front-matter + documentation

        ├─ references/           # Optional: expanded topic guides

        │   ├─ core-concepts.md
        │   ├─ client-library-usage.md
        │   └─ ...
        ├─ scripts/              # Optional: executable helpers

        │   ├─ demo.py
        │   └─ ...
        └─ assets/               # Optional: images, diagrams

            └─ architecture.png

Only SKILL.md is strictly required. The subdirectories provide modularity without enforcing unnecessary overhead.

Minimal Skill Template

Use this template to create a new skill that will be correctly indexed:

---
name: example-skill
metadata:
  category: ExampleCategory
description: >-
  Demonstrates the minimal required structure of a skill.
---

# Example Skill

Brief introductory paragraph describing the skill's purpose.

## Core Concepts

- **Concept 1** – Short description.
- **Concept 2** – Short description.

## Quick Example

```bash

# Replace with a real command that showcases the skill

echo "Hello, world!"

Reference Directory

• Concept Details: In-depth explanation.

Save this as `skills/<category>/<skill-name>/SKILL.md` and add referenced files under `references/` as needed. The front-matter ensures discoverability; the Reference Directory section links related documentation together.

## Summary

- **SKILL.md with YAML front-matter** is the only required file—`name`, `category`, and `description` fields enable automatic indexing
- **`references/`** stores supplementary markdown files linked from the main document
- **`scripts/`** holds optional executable helpers for demos and validation
- **`assets/`** contains optional static files like images and diagrams
- The **Reference Directory section** in [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) ties the structure together by linking to `references/` contents

## Frequently Asked Questions

### What happens if a skill is missing front-matter in SKILL.md?

The skill will not be indexed by repository tooling. The YAML header with `name`, `metadata.category`, and `description` is mandatory for discoverability. Tools that generate skill listings, search indexes, or navigation menus rely on these fields.

### Can a skill exist without any subdirectories?

Yes. A skill consisting solely of [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) with valid front-matter is valid and will be indexed. The `references/`, `scripts/`, and `assets/` directories are optional conveniences for complex topics, not requirements.

### How does the Reference Directory section differ from the references/ folder?

The **Reference Directory** is a markdown **section** in [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) that contains links; the **`references/` folder** is the actual directory holding the linked files. The section serves as a curated table of contents, while the folder stores the content. This separation allows the main document to remain readable while supporting deep documentation.

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