# SKILL.md Frontmatter Contract in jakubkrehel/skills: Required Fields and Format > Learn the SKILL.md frontmatter contract in jakubkrehel/skills. Understand the required name and description fields and their format for every SKILL.md file. - Repository: [Jakub Krehel/skills](https://github.com/jakubkrehel/skills) - Tags: api-reference - Published: 2026-09-12 --- **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`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md), the frontmatter must specify: ```yaml 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`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md), a valid description reads: ```yaml description: Helps your project comply with accessibility standards and best practices. ``` This description must match the corresponding entry in the repository's [`README.md`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md) demonstrate the exact format: ```yaml --- 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`](https://github.com/jakubkrehel/skills/blob/main/skills/variant/SKILL.md), [`skills/interface-review/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/interface-review/SKILL.md), [`skills/better-layout/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/better-layout/SKILL.md), and [`skills/better-colors/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/skills/example-skill/SKILL.md) should use: ```yaml --- 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`): ```yaml --- 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: ```yaml --- 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`](https://github.com/jakubkrehel/skills/blob/main/skills/better-accessibility/SKILL.md) and [`skills/variant/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/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`](https://github.com/jakubkrehel/skills/blob/main/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.