# SKILL.md Frontmatter in Garden Skills: The Agent Contract Specification

> Understand the SKILL.md frontmatter in Garden Skills. This YAML metadata acts as a contract for AI agents, defining when and how to invoke skills. Learn more about this essential specification.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: api-reference
- Published: 2026-09-01

---

**The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) frontmatter is a mandatory YAML metadata block that serves as a machine-readable contract telling AI agents when and how to invoke a specific skill.**

The Garden Skills repository (`ConardLi/garden-skills`) is a curated collection of reusable AI-coding workflows. Every skill in the repository must include a [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file at its root, and the frontmatter at the top of this file acts as the primary interface between the skill and the consuming agent.

## The Contract: When and How

The frontmatter functions as a **declarative contract** that agents parse to determine skill applicability. According to the Garden Skills source code, this contract tells the agent **when** to use the skill and provides the metadata necessary for routing decisions.

### Required YAML Fields

Every [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) frontmatter must contain two specific fields in the YAML block delimited by triple dashes:

- **`name`**: A unique identifier that must match the parent folder name (e.g., `web-video-presentation`). Agents inspect this field to match incoming user requests against available skills in `skills/<skill-name>/SKILL.md`【^1†L1-L3】.
- **`description`**: A concise, human-readable summary explaining the skill's purpose and expected outcome【^1†L2-L4】.

The [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) file explicitly defines this frontmatter as *"the contract that tells the agent when to use the skill"*【^2†L99-L102】, establishing it as a required component for all contributions.

## Frontmatter Structure and Syntax

The frontmatter uses standard YAML syntax enclosed between `---` delimiters at the very beginning of the [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file.

### Standard Format Example

```yaml
---
name: web-video-presentation
description: 把一篇文章或口播稿，做成"看起来像视频"的点击驱动 16:9 网页演示，可选合成口播音频。
---

```

**Key constraints:**
- The `name` value must exactly match the directory name containing the skill (e.g., `skills/web-video-presentation/`)
- The `description` should be actionable and clear enough for both human users and AI agents to understand the skill's scope
- The YAML block must be the first content in the file

## How Agents Parse the Contract

AI-coding agents (Claude Code, Cursor, Codex, etc.) consume the [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) frontmatter as an entry point for skill discovery and execution routing.

### Intent Matching Logic

The agent loads the frontmatter, extracts the `name` field, and compares it against the user's intent or request context. When a match occurs, the agent proceeds to execute the detailed workflow described in the body of the [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) file or its accompanying `references/` files.

### Practical Parsing Implementation

Agents typically implement frontmatter parsing similar to this Python pseudo-code:

```python
import yaml
import pathlib

def load_skill_contract(skill_dir):
    """Extract frontmatter contract from SKILL.md"""
    skill_path = pathlib.Path(skill_dir, "SKILL.md")
    content = skill_path.read_text()
    frontmatter = content.split("---")[1]
    contract = yaml.safe_load(frontmatter)
    return contract  # Returns {'name': ..., 'description': ...}

# Agent routing logic

contract = load_skill_contract("skills/web-video-presentation")
if user_intent == contract["name"]:
    run_skill(contract)

```

This pattern enables dynamic skill registration where the agent validates the contract before invoking the corresponding workflow implementation.

## Relationship to Adjacent Metadata Files

While the frontmatter provides the **routing contract**, Garden Skills separates concerns by storing additional metadata in companion files.

### Distinction from manifest.json

Each [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) is accompanied by a [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) file in the same directory (e.g., [`skills/web-video-presentation/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/manifest.json)). This JSON file supplies supplementary metadata such as version numbers, compatibility constraints, and dependency information, while the frontmatter remains focused solely on the **agent invocation contract**.

### CONTRIBUTING.md Specifications

The repository's [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) mandates that every new skill must include the frontmatter block to ensure interoperability across different AI platforms. This requirement ensures that skills remain **portable, version-controlled, and discoverable** regardless of the specific agent implementation consuming them.

## Summary

- **The [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) frontmatter is a mandatory YAML block** that serves as the machine-readable contract between a skill and AI agents.
- **Required fields are `name`** (matching the folder name) and **`description`** (summarizing the skill's purpose).
- **Agents parse the frontmatter** to match user intent against available skills before executing the workflow.
- **The contract is distinct from [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json)**, which handles versioning while frontmatter handles routing.
- **All skills in `ConardLi/garden-skills`** must implement this frontmatter according to [`CONTRIBUTING.md`](https://github.com/ConardLi/garden-skills/blob/main/CONTRIBUTING.md) specifications.

## Frequently Asked Questions

### What fields are required in the SKILL.md frontmatter?

The frontmatter requires exactly two fields: `name` and `description`. The `name` field must match the skill's directory name (e.g., `web-video-presentation`), while the `description` field provides a human-readable summary of what the skill accomplishes. Both fields are mandatory for the agent to properly route requests.

### How does the name field affect skill discovery?

The `name` field acts as the primary routing key. When an agent processes a user request, it compares the request intent against the `name` values in all available [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) files. An exact match triggers the agent to load and execute that specific skill's workflow, making the `name` field critical for correct skill invocation.

### What's the difference between SKILL.md frontmatter and manifest.json?

The frontmatter in [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md) contains the **agent contract** (`name` and `description`) used for routing decisions, while [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) stores **operational metadata** such as version numbers, compatibility requirements, and dependencies. The frontmatter is parsed first to determine *if* a skill should run; the manifest provides additional context *after* selection.

### Can I add custom fields to the frontmatter?

While the YAML parser will accept additional fields, the Garden Skills specification only recognizes `name` and `description` for the agent contract. Custom fields should be placed in [`manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/manifest.json) instead to maintain compatibility with standard agent implementations that expect only the two standard fields in the frontmatter block.