# How Google Agent Skills Are Structured and Organized in the google/skills Repository

> Discover how Google Agent Skills are structured and organized in the google/skills repository. Learn about self-contained directories, SKILL.md files, and automatic discovery for frameworks like Genkit.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: architecture
- Published: 2026-09-04

---

**Google Agent Skills are organized as self-contained directories under a root `skills/` folder, each anchored by a mandatory [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file containing YAML front-matter metadata and instructional content, enabling automatic discovery and runtime loading by frameworks like Genkit.**

The `google/skills` repository serves as a catalog of reusable capabilities for AI agents. Each skill follows a uniform layout that allows tooling to automatically discover, load, and invoke them when an LLM calls `use_skill("<skill-name>")`.

## Core Directory Structure

The repository organizes skills hierarchically to ensure logical grouping and mechanical discovery.

### Root and Domain Organization

At the top level, the `skills/` directory acts as a container that groups skills by domain. This logical separation keeps related capabilities together while maintaining a predictable path structure.

Key domain folders include:

- `skills/cloud/` – Cloud-related capabilities such as BigQuery, GKE, and IAM
- `skills/ads/` – Advertising SDKs and APIs
- `skills/analytics/` – Google Analytics Data API integrations

Each domain folder contains multiple skill directories, creating a navigable taxonomy of agent capabilities.

### Individual Skill Directories

Every skill resides in its own directory under a domain folder, following the pattern `skills/<domain>/<skill-name>/`. The directory name itself serves as the skill identifier used in runtime calls.

For example, the BigQuery Basics skill lives at `skills/cloud/bigquery-basics/`, while cross-referencing skills like the Gemini Agents API skill reside at `skills/cloud/gemini-agents-api/`.

### The SKILL.md File Format

Each skill directory must contain a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file. This file serves as the complete definition of the skill and contains two distinct parts:

1. **YAML front-matter** – Defines metadata including the skill name, category, and description
2. **Instructional body** – Contains sections like **Setup and Basic Usage**, **Reference Directory**, and **Related Skills**

When the Genkit middleware scans the repository, it parses this file to build the skill catalog. According to the source code in [`skills/cloud/genkit-go/references/middleware.md`](https://github.com/google/skills/blob/main/skills/cloud/genkit-go/references/middleware.md), the runtime specifically looks for [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files to construct the available tool list.

## Optional Sub-Folders and Assets

While [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) contains the core definition, richer skills utilize optional sub-folders to maintain clean separation between primary instructions and supplemental resources.

### references/, scripts/, and assets/

Skill directories may include these standard sub-folders:

- `references/` – Supplemental documentation such as core concepts, CLI usage guides, and client library examples. For instance, `skills/cloud/bigquery-basics/references/` contains files like [`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)
- `scripts/` – Helper scripts that automate setup or common workflows
- `assets/` – Static resources including templates, diagrams, or output formats like [`output-template.md`](https://github.com/google/skills/blob/main/output-template.md)

This structure keeps the primary [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) concise while allowing comprehensive documentation to live in organized sub-directories.

## Plugin Registration and Discovery

Skills integrate with frameworks through a plugin system that bridges the repository structure and runtime environments.

### How Middleware Scans for Skills

The discovery mechanism relies on middleware implementations documented in [`skills/cloud/genkit-go/references/middleware.md`](https://github.com/google/skills/blob/main/skills/cloud/genkit-go/references/middleware.md) and [`skills/cloud/genkit-python/references/agents.md`](https://github.com/google/skills/blob/main/skills/cloud/genkit-python/references/agents.md). The process follows these steps:

1. The middleware scans the configured `skills/` root for any [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file
2. It parses the YAML front-matter to build a catalog of available skill names
3. It inserts a system prompt listing the catalog, allowing the LLM to understand available tools
4. Plugin registration files such as [`plugins/cloud/google-cloud-developer/plugin.json`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/plugin.json) declare which skill directories should be exposed to specific platforms

### Runtime Loading and use_skill Invocation

When an LLM calls `use_skill("<name>")`, the middleware retrieves the full markdown body from the corresponding [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file and injects it into the conversation context. This dynamic loading allows agents to access skill instructions on-demand without overwhelming the context window with unused capabilities.

## Code Examples

The repository includes integration patterns for multiple languages and environments.

### Listing Available Skills in Genkit-Go

The Genkit-Go middleware provides functions to automatically load and list skills from the repository structure:

```go
import (
    "github.com/google/genkit"
    "github.com/google/genkit/middleware"
)

func main() {
    // Initialise Genkit with the default plugin that reads SKILL.md files.
    g := genkit.New()
    middleware.LoadSkills(g) // scans `skills/` for SKILL.md

    // Retrieve the catalog (generated by the middleware).
    catalog := g.GetSkillCatalog()
    fmt.Println("Available skills:", catalog) // → [bigquery-basics …]
}

```

The `LoadSkills` call walks the repository tree, reads every [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md), and registers its name in the runtime catalog.

### Invoking Skills in Genkit-Python

Python implementations use the same underlying structure but expose skills through the `use_skill` tool:

```python
import genkit as gk
from genkit import middleware

# Initialise the Genkit runtime – it will auto‑load SKILL.md files.

gk.init()

# Prompt that asks the model to run the BigQuery Basics skill.

prompt = """
Please create a BigQuery dataset called `demo_ds` and list the first 5 rows
from the public `usa_names` table. Use the skill named "bigquery-basics".
"""

# The middleware injects a `use_skill` tool, so the model can call it.

response = gk.generate(prompt, tools=[middleware.use_skill])
print(response.text)

```

When the model calls `use_skill("bigquery-basics")`, the middleware fetches the markdown from [`skills/cloud/bigquery-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-basics/SKILL.md) and appends the relevant instructions to the conversation.

### Direct Skill Inspection with Bash

Developers can inspect skill definitions directly without framework middleware:

```bash

# Bash – retrieve the raw markdown for inspection.

curl -s https://raw.githubusercontent.com/google/skills/main/skills/cloud/bigquery-basics/SKILL.md | less

```

This approach is useful for debugging or building custom tooling that consumes the skill documentation outside of Genkit environments.

## Summary

Google Agent Skills in the `google/skills` repository follow a standardized, file-system-based architecture that enables automated discovery and dynamic loading:

- Skills are organized under `skills/<domain>/<skill-name>/` with the directory name serving as the unique identifier
- Each skill requires a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file containing YAML front-matter metadata and instructional markdown
- Optional `references/`, `scripts/`, and `assets/` folders provide supplementary documentation without cluttering the core definition
- Plugins like [`plugins/cloud/google-cloud-developer/plugin.json`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/plugin.json) register skill directories for platform exposure
- Genkit middleware ([`skills/cloud/genkit-go/references/middleware.md`](https://github.com/google/skills/blob/main/skills/cloud/genkit-go/references/middleware.md)) scans for [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files and exposes them via the `use_skill("<name>")` tool

## Frequently Asked Questions

### What is the purpose of the SKILL.md file?

The [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file serves as the canonical definition of a Google Agent Skill. It contains YAML front-matter specifying metadata like the skill name and category, followed by instructional content that teaches LLMs how to perform specific tasks. The file is mandatory for discovery, as middleware implementations scan specifically for [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files to build the runtime catalog.

### How do frameworks discover skills automatically?

Frameworks like Genkit use middleware that walks the `skills/` directory tree looking for [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files. As documented in [`skills/cloud/genkit-python/references/agents.md`](https://github.com/google/skills/blob/main/skills/cloud/genkit-python/references/agents.md), the middleware parses the YAML front-matter to extract skill identifiers, then dynamically injects these capabilities into the system prompt as available tools. This allows LLMs to reference skills by name without hardcoding their definitions in the application code.

### Can skills reference other skills?

Yes, skills can reference related capabilities using relative paths. For example, [`skills/cloud/gemini-agents-api/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gemini-agents-api/SKILL.md) demonstrates cross-skill referencing by pointing to [`../gemini-interactions-api/SKILL.md`](https://github.com/google/skills/blob/main/../gemini-interactions-api/SKILL.md). This allows skill authors to build modular, composable instructions that leverage existing definitions without duplication.

### What domains are covered in the repository?

The repository organizes skills into logical domain folders under `skills/`, including `cloud/` for Google Cloud Platform capabilities (BigQuery, GKE, IAM), `ads/` for advertising SDKs and APIs, and `analytics/` for Google Analytics Data API integrations. Each domain follows the same directory structure with mandatory [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files and optional support folders.