---
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](https://gofastmcp.com/servers/providers/skills):

```yaml
---
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:

```yaml
---
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](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts) and [schema reference](https://modelcontextprotocol.io/specification/latest/schema) 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/`.