65 lines
2.6 KiB
Markdown
65 lines
2.6 KiB
Markdown
---
|
|
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](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 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:
|
|
|
|
```yaml
|
|
---
|
|
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](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 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/`.
|