Frontmatter
Every SKILL.md file begins with YAML frontmatter enclosed in triple dashes. The frontmatter contains metadata about the skill that agents and tools use for discovery, categorization, and validation.
Format
Frontmatter uses standard YAML syntax:
SKILL.md
---
name: my-skill-name
description: A concise description of what this skill teaches
---
# My Skill Name
...Required Fields
| Field | Type | Constraints | Example |
|---|---|---|---|
name | string | Lowercase, hyphenated, max 64 characters. Must match /^[a-z0-9][a-z0-9-]*[a-z0-9]$/ | css-layout-expert |
description | string | Max 200 characters. Plain text, no markdown. | Expert CSS layout patterns using modern flexbox and grid techniques |
Name Rules
The name field is the primary identifier for the skill. It must be:
Name validation rules
✓ css-layout-expert # lowercase, hyphenated
✓ react-hooks # simple, descriptive
✓ a11y-testing # abbreviations OK
✓ my-skill # minimum 2 characters
✗ CSS-Layout-Expert # no uppercase
✗ css layout expert # no spaces
✗ css_layout_expert # no underscores
✗ -leading-hyphen # cannot start with hyphen
✗ trailing-hyphen- # cannot end with hyphen
✗ a # too short (minimum 2 characters)Smidge-Specific Fields
Skills generated by Smidge include additional fields. These are optional in the spec but always present in Smidge output:
| Field | Type | Description |
|---|---|---|
generated_by | string | Always smidge for Smidge-generated skills. |
generator_url | string | Always https://smdg.app. |
version | string | Skill version, starting at "1.0". Quoted to force string type. |
Complete Example
SKILL.md
---
name: react-server-components
description: Patterns and best practices for React Server Components in Next.js App Router
generated_by: smidge
generator_url: https://smdg.app
version: "1.0"
---
# React Server Components
## Overview
...Invalid Frontmatter
Common mistakes that will cause validation failures:
Invalid examples
# Missing frontmatter entirely — no --- delimiters
# This is just a markdown file without metadata
---
# Missing name field
description: This skill is missing a name
---
---
name: My Skill Name # Invalid: contains spaces and uppercase
description: OK
---
---
name: css-expert
description: This description is way too long and exceeds the 200 character limit which means it will fail validation because the Agent Skills specification requires descriptions to be concise and machine-readable so they can be displayed in skill listings and search results without truncation
---Tip
If you're editing a Smidge-generated skill, you can change the name and description freely — just ensure they meet the constraints above. The
generated_by and generator_url fields are optional and can be removed.