SKILL.md Frontmatter Contract in jakubkrehel/skills: Required Fields and Format

Every SKILL.md file must begin with a YAML frontmatter block containing exactly two required fields—name matching the parent directory and a concise description—delimited by triple dashes.

The jakubkrehel/skills repository enforces a strict frontmatter contract across all skill definitions. This standardized metadata schema ensures programmatic discovery and consistent presentation of every skill in the collection.

Required Frontmatter Fields

The frontmatter block must contain precisely two keys. No additional fields are permitted.

The name Field

The name value must be the exact directory name containing the SKILL.md file. For example, in skills/better-accessibility/SKILL.md, the frontmatter must specify:

name: better-accessibility

This requirement creates a strict relationship between the file system structure and the metadata. The repository uses this field to programmatically identify each skill during enumeration.

The description Field

The description provides a concise one- or two-sentence summary of the skill's purpose. According to the source code in skills/better-accessibility/SKILL.md, a valid description reads:

description: Helps your project comply with accessibility standards and best practices.

This description must match the corresponding entry in the repository's README.md file, ensuring synchronized documentation across the project.

File Location and Formatting Rules

The frontmatter block must appear at the very top of the file, before any other content. It must be surrounded by triple dashes (---).

For example, lines 1-4 of skills/better-accessibility/SKILL.md demonstrate the exact format:

---
name: better-accessibility
description: Helps your project comply with accessibility standards and best practices.
---

This pattern repeats across all skill definitions, including skills/variant/SKILL.md, skills/interface-review/SKILL.md, skills/better-layout/SKILL.md, and skills/better-colors/SKILL.md.

Valid and Invalid Examples

Understanding the contract requires examining both conforming and non-conforming implementations.

Valid Frontmatter

A new skill located at skills/example-skill/SKILL.md should use:

---
name: example-skill
description: Provides an illustrative example of how a skill should be documented.
---

Invalid: Missing Required Fields

The following example fails validation because it uses incorrect keys (title and summary instead of name and description):

---
title: example-skill
summary: Does something useful.
---

Invalid: Mismatched Directory Name

Even with correct field names, the frontmatter is invalid if the name does not match the parent directory:

---
name: mismatched-name
description: This description is fine, but the name is wrong.
---

Summary

• Every SKILL.md frontmatter must contain exactly name and description.
• The name field must match the containing directory name exactly.
• The YAML block must appear first in the file, delimited by ---.
• Additional keys beyond the two required fields violate the contract.
• All skill files including skills/better-accessibility/SKILL.md and skills/variant/SKILL.md follow this identical structure.

Frequently Asked Questions

What happens if I add extra fields to the SKILL.md frontmatter?

The contract prohibits additional keys beyond name and description. While YAML parsers may technically process extra fields, the strict schema ensures consistency across the jakubkrehel/skills repository and prevents metadata bloat.

Does the description field support markdown formatting?

The contract specifies the description as a concise one- or two-sentence summary used for skill discovery. While the raw analysis does not explicitly forbid markdown, the requirement for matching the README.md entry suggests plain text is preferred for consistent rendering across different contexts.

Can the frontmatter appear anywhere else in the file?

No. The YAML block must appear at the very top of the file, immediately starting with --- on line 1. Placing the frontmatter after any other content, even empty lines, violates the contract as implemented in files like skills/better-accessibility/SKILL.md.

Is the name field case-sensitive?

According to the contract, the name must be the exact directory name. This implies case sensitivity matches the underlying file system, meaning Better-Accessibility and better-accessibility would be treated as distinct values.

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