How to Format a Google Agent Skill Markdown File (SKILL.md)

A Google Agent Skill is defined entirely in a single SKILL.md file that combines YAML front-matter with structured Markdown sections describing workflows, safety constraints, and reference materials.

The google/skills repository hosts community-contributed agent skills for Google AI agents. Every skill is encapsulated in exactly one SKILL.md file located in its respective directory (e.g., skills/cloud/spanner-basics/SKILL.md), following a strict schema that enables programmatic parsing while remaining human-readable according to the source code analysis.

YAML Front-Matter Schema

Every SKILL.md must begin with a YAML block delimited by triple dashes (---). This front-matter contains machine-readable metadata consumed by the skill-registry parser.

The required and optional keys are:

• name (required): Short identifier used as the skill ID (kebab-case recommended)
• metadata (required): Nested object containing at minimum a category field
• description (required): One-sentence summary shown in skill listings (use >- for folded multi-line strings)
• version (optional): Semantic version string (e.g., 1.2.0)

---
name: spanner-basics
metadata:
  category: Databases
description: >-
  Assists in provisioning instances and databases, designing performant schemas,
  and querying data in Spanner. Use when designing primary keys, writing SQL
  queries or client library code, or diagnosing performance issues.
---

Source: skills/cloud/spanner-basics/SKILL.md

Title Heading and Document Structure

Immediately following the front-matter, the file must contain a top-level Markdown heading (#) that repeats the skill name for human readability.

# Spanner Basics

After the title, content is organized into standard H2 sections. While the exact order may vary, valid skills typically include Core Principles, Safety, Common Workflows, and Reference Directory sections.

Required Content Sections

Core Principles

This section provides high-level conceptual guidance that shapes how the agent applies the skill. It uses bullet lists or paragraphs to outline performance considerations, architectural patterns, or domain-specific rules.

Safety Instructions

Any skill capable of invoking destructive cloud operations must include a Safety section with a highlighted caution block. The standard format uses GitHub-style alert syntax (> [!CAUTION]) followed by bold critical instructions:

## Safety

> [!CAUTION] **CRITICAL INSTRUCTION:** You MUST obtain explicit user confirmation before executing any destructive operations such as deleting instances, dropping databases, or modifying production schemas.

Source: skills/cloud/spanner-basics/SKILL.md

Common Workflows

Workflows are presented as ordered lists (numbered 1., 2., etc.) describing step-by-step procedures. Complex workflows may include nested bullet points or checkbox items (- [ ]) to track progress through multi-stage processes.

Example from skills/ads/google-mobile-ads-get-started/SKILL.md:

## Workflow

1. **Determine the user's platform** by asking which mobile OS they target.
2. **Read the platform guide** from the references directory.
3. **Follow these steps**:
   - [ ] Add the SDK dependency to the build configuration
   - [ ] Set the application identifier in the manifest
   - [ ] Configure the test device for development

Reference Directory Structure

The final section enumerates supplemental Markdown files stored in the skill's references/ subdirectory. Each entry uses standard Markdown link syntax with relative paths:

## Reference Directory

- [Core Concepts](references/core-concepts.md)
- [CLI Usage](references/cli-usage.md)
- [Best Practices](references/best-practices.md)

These auxiliary files contain detailed tables, command examples, or platform-specific instructions that would clutter the main skill definition.

Complete SKILL.md Template

Minimal Valid Skeleton

---
name: my-sample-skill
metadata:
  category: Example
description: >-
  Demonstrates the required structure of a Google Agent Skill.
---

# My Sample Skill

## Core Principles

- Explain what the skill does and when to apply it.
- Outline key constraints or assumptions.

## Safety

> [!CAUTION] **CRITICAL INSTRUCTION:** Always ask for explicit user confirmation before executing any write operations.

## Workflow

1. Identify user intent and required parameters.
2. Validate inputs against constraints.
3. Execute the operation with confirmation.

## Reference Directory

- [Sample Reference](references/sample.md)

Real-World Production Example

---
name: spanner-basics
metadata:
  category: Databases
description: >-
  Assists in provisioning instances and databases, designing performant schemas,
  and querying data in Spanner.
---

# Spanner Basics

## Core Principles

- **Performance First:** Always consider primary key design implications for write throughput and read latency.
- **Schema Design:** Use interleaved tables for parent-child relationships to improve data locality.

## Safety

> [!CAUTION] **CRITICAL INSTRUCTION:** You MUST obtain explicit user confirmation before executing DDL statements that modify production databases or delete instances.

## Common Workflows

### Schema Evolution & DDL

1. Review the current schema using `gcloud spanner databases ddl describe`.
2. Draft the ALTER statements in a transaction.
3. Apply changes using `gcloud spanner databases ddl update`.

## Reference Directory

- [Core Concepts](references/core-concepts.md)
- [CLI Usage](references/cli-usage.md)
- [Schema Design Guide](references/schema-design.md)

Source: skills/cloud/spanner-basics/SKILL.md

Summary

• SKILL.md is the single required file defining a Google Agent Skill in the google/skills repository.
• YAML front-matter must include name, metadata.category, and description, with an optional version field.
• Safety sections are mandatory for destructive operations and must use the > [!CAUTION] blockquote format with explicit confirmation instructions.
• Reference Directory lists supporting files in references/*.md using relative Markdown links.
• Workflow sections support numbered steps with optional checkboxes (- [ ]) for interactive guidance.

Frequently Asked Questions

What is the exact filename required for a Google Agent Skill?

The skill-registry parser specifically looks for a file named exactly SKILL.md (case-sensitive) in the skill's root directory. No other filenames are recognized as primary skill definitions.

Is the version field in the YAML front-matter mandatory?

No, the version field is optional. When provided, it should follow semantic versioning (e.g., 1.2.0), but the parser does not enforce its presence for skill registration.

How must safety warnings be formatted to pass validation?

Safety warnings must appear in a section titled "Safety" and use the GitHub alert syntax > [!CAUTION] followed by bold text emphasizing "CRITICAL INSTRUCTION." The block must explicitly state that user confirmation is required before destructive actions, as seen in skills/cloud/spanner-basics/SKILL.md.

Can a skill reference files outside its own directory?

No, the Reference Directory should only link to files within the skill's references/ subdirectory using relative paths (e.g., references/guide.md). Absolute paths or external URLs are not supported for primary reference linking.

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