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

> Learn the SKILL.md format for Google Agent Skills. This guide details YAML front-matter and Markdown sections for workflows, safety, and references.

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

---

**A Google Agent Skill is defined entirely in a single [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md) file located in its respective directory (e.g., [`skills/cloud/spanner-basics/SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`)

```yaml
---
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`](https://github.com/google/skills/blob/main/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.

```markdown

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

```markdown

## 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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/ads/google-mobile-ads-get-started/SKILL.md):

```markdown

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

```markdown

## 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

```markdown
---
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

```markdown
---
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`](https://github.com/google/skills/blob/main/skills/cloud/spanner-basics/SKILL.md)*

## Summary

- **[`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/references/guide.md)). Absolute paths or external URLs are not supported for primary reference linking.