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

The 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 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 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 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 file.

Standard Format Example

---
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 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 file or its accompanying references/ files.

Practical Parsing Implementation

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

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 is accompanied by a manifest.json file in the same directory (e.g., 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 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 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, which handles versioning while frontmatter handles routing.
• All skills in ConardLi/garden-skills must implement this frontmatter according to 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 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 contains the agent contract (name and description) used for routing decisions, while 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 instead to maintain compatibility with standard agent implementations that expect only the two standard fields in the frontmatter block.

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