How SKILL.md Frontmatter Works in Garden Skills: Validation Rules and Examples

Garden Skills requires every SKILL.md file to begin with a YAML frontmatter block containing a name field matching the folder name and a description field, which the validateSkillStructure function in scripts/release/lib/skills.mjs parses and validates to ensure consistent skill metadata.

The Garden Skills repository (ConardLi/garden-skills) uses structured SKILL.md frontmatter to standardize skill definitions across all contributions. This metadata block enables automated discovery, catalog generation, and CI validation. Understanding the parsing logic and strict validation rules helps contributors ensure their skills pass automated checks and appear correctly in generated listings.

Structure of the SKILL.md Frontmatter

Every skill definition resides in skills/<folder-name>/SKILL.md and must begin with a YAML frontmatter block wrapped in triple-dash delimiters (---). According to the source code in scripts/release/lib/skills.mjs (lines 124–129), the release tooling reads only the first 4 KB of each file and extracts content matching the regex pattern ^---\s*\n([\s\S]*?)\n--- to isolate the frontmatter string.

Required Fields

The validator enforces exactly two mandatory keys within the frontmatter:

• name: Must match the parent folder name exactly (skills/<name>). The validator applies the regex /^name:\s*(\S+)\s*$/m at lines 132–138 to extract this value and compare it against the directory name.
• description: A concise summary of the skill's purpose. If the description contains a colon followed by a space (: ), the value must be wrapped in single or double quotes to prevent YAML parsing ambiguity.

Optional Fields

While only name and description are validated, the frontmatter parser treats the block as a raw string and ignores additional YAML keys. These extra fields can support downstream tooling or custom prompt generators without triggering validation errors.

Validation Logic and Error Handling

The core validation logic resides in the validateSkillStructure function within scripts/release/lib/skills.mjs. This function is invoked by both the list-skills utility (scripts/release/list-skills.mjs) and the release pipeline to enforce consistency across the repository.

Name Matching

The validator ensures the frontmatter name field matches the directory name exactly. A mismatch generates an error message like:

web-video-presentation: SKILL.md frontmatter name "web-video-presentation" does not match folder "web-video"

This check prevents discrepancies between a skill's declared identity and its filesystem location.

Description Formatting

Descriptions containing colons must be quoted. The validation logic at lines 40–53 checks for the pattern /:\s/ and verifies quote wrapping using:

const isQuoted = (description.startsWith('"') && description.endsWith('"')) ||
                 (description.startsWith("'") && description.endsWith("'"));

If an unquoted description contains : , the validator pushes an error indicating the description must be quoted.

Local Validation and CI Enforcement

Running Validation Locally

Developers can validate frontmatter syntax before committing by executing:

node scripts/release/list-skills.mjs

This command runs validateSkillStructure against all skills, prints a table of results, and exits with a non-zero status code if any frontmatter violations are detected.

CI Integration

The GitHub Actions workflow defined in .github/workflows/validate-skills.yml executes the same validation on every pull request. Malformed frontmatter causes the workflow to fail, blocking the merge and preventing inconsistent skills from entering the main branch.

Practical Examples

Valid Frontmatter Structure

Here is a compliant example from skills/web-design-engineer/SKILL.md:

---
name: web-design-engineer
description: "Build or redesign polished browser‑rendered visual artifacts with HTML/CSS/JavaScript/React..."
---

The quoted description accommodates colons within the text, and the name matches the containing folder exactly.

Common Validation Errors

Attempting to use an unquoted description with colons triggers:

<skill-name>: SKILL.md frontmatter description contains ": " and must be quoted

Missing frontmatter entirely results in:

<skill-name>: SKILL.md is missing YAML frontmatter (--- ... ---)

Summary

• SKILL.md frontmatter uses YAML syntax wrapped in --- delimiters, parsed from the first 4 KB of each skill file using regex ^---\s*\n([\s\S]*?)\n---.
• The name field must exactly match the skill's folder name in skills/<name> according to lines 132–138 of scripts/release/lib/skills.mjs.
• Descriptions containing : must be quoted to avoid YAML parsing ambiguity, as enforced by lines 40–53.
• Validation occurs via validateSkillStructure, accessible locally through node scripts/release/list-skills.mjs.
• The CI workflow .github/workflows/validate-skills.yml enforces frontmatter correctness on every PR, blocking merges with malformed metadata.

Frequently Asked Questions

What fields are required in the Garden Skills frontmatter?

The frontmatter must include exactly two fields: name (matching the folder name) and description (a concise skill summary). Additional YAML fields are allowed but ignored by the core validator in scripts/release/lib/skills.mjs.

Why does my description need quotes in SKILL.md?

If your description contains a colon followed by a space (: ), you must wrap it in single or double quotes. The validator checks lines 40–53 of scripts/release/lib/skills.mjs and rejects unquoted strings containing this pattern to prevent YAML parsing errors during the release process.

How do I test my SKILL.md frontmatter locally?

Run node scripts/release/list-skills.mjs from the repository root. This executes the validateSkillStructure function against all skills and reports specific errors with file paths before you commit, allowing you to fix issues before opening a pull request.

What happens if the frontmatter name doesn't match the folder?

The validator generates an error stating the name does not match the folder, and the CI workflow defined in .github/workflows/validate-skills.yml fails, blocking the pull request from merging until the frontmatter name value aligns with the directory name.

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