81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
---
|
|
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/`.
|