Skip to main content

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.