prompts/src/personal_mcp/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

Each prompt stores runtime metadata in a nested prompt mapping beside fields consumed by the static documentation site. The runtime mapping uses this shape:

---
icon: lucide/messages-square
prompt:
 version: "1.0.0"
 description: Describe when to use the prompt.
 tags: [example, prompts]
 arguments: {topic: {description: "Topic to process.", required: true, choices: [first, second]}, notes: {description: "Optional constraints.", required: false}}
---

Prompt rules:

1. version, description, tags, and arguments are required; unknown fields inside prompt or an argument are rejected.
2. The directory name supplies the prompt id. Do not add a duplicate name field.
3. Argument names must be valid identifiers and preserve their authored mapping order.
4. Every argument requires a non-empty description and explicit required boolean.
5. Optional choices must be a non-empty list of unique, non-empty strings.
6. Markdown placeholders must exactly match the declared argument names.
7. Top-level fields such as icon remain owned by the documentation site and are not runtime prompt metadata.

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. Every list or get request reloads and validates the authored files. A malformed definition fails the request instead of publishing a partial prompt set.

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 or Python component file.
4. All authored content remains under docs/.