prompts/docs/contracts/frontmatter.md

icon

icon
lucide/braces

Frontmatter Contract

This page defines the authored frontmatter contracts for native FastMCP skills and registry-backed prompts.

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 Frontmatter

Prompts remain registry-backed and retain repository metadata:

---
name: <prompt-id>
description: <what the prompt does and when to use it>
x-personal-mcp:
  id: <prompt-id>
  version: <semver>
  tags:
    - <tag>
  capabilities:
    - resource://prompts/<prompt-id>/document
  arguments:
    <argument-name>:
      title: <display title>
      description: <input guidance>
      required: true
---

Prompt rules:

1. name, description, and x-personal-mcp are required.
2. x-personal-mcp.id, name, and the prompt directory name must match.
3. version must be semantic version text.
4. capabilities must include resource://prompts/<prompt-id>/document.
5. Argument names must be valid Python identifiers.
6. Argument entries accept optional title, description, and required fields.
7. Unknown prompt fields are rejected by the strict Pydantic registry models.

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 remains registry-oriented and fails server startup for invalid metadata, duplicate prompt ids, or malformed arguments.

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 retain the richer metadata required by their catalog and MCP prompt-object surfaces.
4. All authored content remains under docs/.