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

Google Agent Skills are organized as self-contained directories under a root skills/ folder, each anchored by a mandatory 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 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, the runtime specifically looks for SKILL.md files to construct the available tool list.

Optional Sub-Folders and Assets

While 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 and 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

This structure keeps the primary 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 and skills/cloud/genkit-python/references/agents.md. The process follows these steps:

1. The middleware scans the configured skills/ root for any 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 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 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:

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, 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:

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 and appends the relevant instructions to the conversation.

Direct Skill Inspection with Bash

Developers can inspect skill definitions directly without framework middleware:

# 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 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 register skill directories for platform exposure
• Genkit middleware (skills/cloud/genkit-go/references/middleware.md) scans for 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 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 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 files. As documented in 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 demonstrates cross-skill referencing by pointing to ../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 files and optional support folders.

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