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

> Learn how SKILL.md frontmatter in Garden Skills works. Understand validation rules and see examples for consistent skill metadata. Validate your skill structure now.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Garden Skills requires every [`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/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:

```javascript
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:

```bash
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`](https://github.com/ConardLi/garden-skills/blob/main/.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`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-design-engineer/SKILL.md):

```yaml
---
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`](https://github.com/ConardLi/garden-skills/blob/main/.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`](https://github.com/ConardLi/garden-skills/blob/main/.github/workflows/validate-skills.yml) fails, blocking the pull request from merging until the frontmatter `name` value aligns with the directory name.