# What Is the Structure of a Skill in the Google Skills Repository? > Explore the Google Skills repository structure. Learn how a skill is defined by SKILL.md files and organized into directories with optional assets and scripts. - Repository: [Google/skills](https://github.com/google/skills) - Tags: getting-started - Published: 2026-08-10 --- **A skill in the Google Skills repository is a self-contained learning unit defined by a [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md) file. This file serves as both metadata declaration and primary documentation. ### Front-Matter Header The top of [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) **must** contain YAML front-matter with three key fields: ```yaml --- 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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/core-concepts.md) and [`client-library-usage.md`](https://github.com/google/skills/blob/main/client-library-usage.md) from its Reference Directory section (lines 14-24). This separation keeps [`SKILL.md`](https://github.com/google/skills/blob/main/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/ └─ / └─ / ├─ 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`](https://github.com/google/skills/blob/main/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: ```markdown --- 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](references/concept-details.md): In-depth explanation. ``` Save this as `skills///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.