Frontmatter Reference

All SKILL.md files must include YAML frontmatter between --- delimiters at the top of the file.

Required Fields

Field	Type	Description
name	string	Unique kebab-case identifier. Must match the directory name.
title	string	Human-readable display name shown in the marketplace.
description	string	One sentence describing what the skill does.
version	string	Semantic version string (e.g., "1.2.0").
author	string	Your GitHub handle.
trigger	string	When the agent should activate this skill. Be specific.

Minimal valid frontmatter

---
name: my-skill
title: "My Skill"
description: "Does one specific thing clearly."
version: "1.0.0"
author: "your-github-handle"
trigger: "Use when the user asks to do X."
---

Optional Fields

Field	Type	Default	Description
tags	string[]	[]	Category labels for search filtering. Max 5.
license	string	"MIT"	SPDX license identifier.
homepage	string	—	URL to your skill’s docs or repo.
repository	string	—	GitHub repository URL (auto-detected if submitted via GitHub).
min_runtime	string	—	Minimum Claude Code version required (e.g., "1.4.0").
tools	string[]	[]	List of tool names the skill calls (e.g., ["Bash", "Read", "Write"]).
deprecated	boolean	false	Mark the skill as deprecated. Suppresses it from search.
deprecated_by	string	—	Name of the skill that replaces this one.
experimental	boolean	false	Tag as experimental. Shows a warning badge.

Full example with optional fields

---
name: rna-qc
title: "Single-Cell RNA QC"
description: "Performs quality control on scRNA-seq data using Seurat and scran."
version: "2.1.0"
author: "bioinformatics-jeff"
trigger: "Use when the user wants to perform QC on single-cell RNA-seq data, filter low-quality cells, or assess mitochondrial content."
tags:
  - bioinformatics
  - single-cell
  - R
  - quality-control
license: MIT
homepage: "https://github.com/bioinformatics-jeff/rna-qc"
repository: "https://github.com/bioinformatics-jeff/rna-qc"
min_runtime: "1.3.0"
tools:
  - Bash
  - Read
  - Write
experimental: false
---

Field Validation Rules

• name: lowercase letters, numbers, and hyphens only. No spaces. Must match directory name exactly.
• version: must follow semver — MAJOR.MINOR.PATCH
• tags: each tag lowercase, no spaces (use hyphens). Max 5 tags per skill.
• trigger: minimum 10 words. Vague triggers (< 10 words) fail validation.
• description: maximum 160 characters (fits in search result cards).

Schema Validation

Run npx @hordago/skill-validator to check your frontmatter against the full schema before submitting. Validation errors are reported with line numbers and fix suggestions.