prompts/docs/contracts/frontmatter.md

icon

icon
lucide/braces

Frontmatter Contract

This page defines frontmatter ownership for native skills and prompt documentation.

Skill Frontmatter

Skills use the standard Agent Skills fields consumed by the FastMCP Skills Provider:

---
name: <skill-id>
description: <what the skill does and when to use it>
---

Rules:

1. name and description are required.
2. name must equal the skill directory name.
3. The repository uses lowercase kebab-case directory names.
4. Skill frontmatter contains no x-personal-mcp catalog metadata.
5. Supporting files require no frontmatter manifest. The provider discovers files recursively and generates _manifest with relative paths, byte sizes, and SHA256 hashes.

The provider uses the directory name as the URI identity and the frontmatter description as the main resource description. Repository tests enforce directory/name parity and reject extra skill frontmatter fields.

Prompt Documentation Frontmatter

Prompt runtime metadata is defined by typed Python components, not Markdown frontmatter. A prompt document may retain only fields consumed by the static documentation site:

---
icon: lucide/messages-square
---

Prompt rules:

1. Do not duplicate prompt names, descriptions, versions, tags, or arguments in Markdown YAML.
2. Argument names must be valid Python identifiers in the component signature.
3. Literal value constraints belong in Python type annotations.
4. Markdown placeholders must exactly match the component argument names.

See the MCP prompts concept documentation and schema reference for the protocol-level prompt shape.

Validation Timing

Skill validation is file- and provider-oriented:

1. SkillsDirectoryProvider discovers each directory containing SKILL.md.
2. FastMCP parses the description and scans all files when the provider is created.
3. Repository tests enforce the stricter standard-only frontmatter and directory/name rules.

Prompt validation is provider- and renderer-oriented. Provider discovery validates decorated functions, while focused tests render every prompt and reject placeholder drift.

Invariants

1. Skills remain directly portable to tools that understand standard Agent Skills directories.
2. Native skill discovery has no parallel catalog metadata source.
3. Prompts use FastMCP's native component metadata and protocol surface without a parallel catalog.
4. All authored content remains under docs/.