---
icon: lucide/braces
---

# Frontmatter Contract

This page defines the `SKILL.md` frontmatter and FastMCP metadata contract.

Prompt modules use the same contract style in `docs/prompts/<prompt-id>/PROMPT.md` with prompt-specific capability and MCP-aligned prompt argument metadata.

## Validated Frontmatter Surface

The registry runtime validates a strict, standard-only frontmatter surface:

1. Top-level fields accepted for skills: `name`, `description`, `x-personal-mcp`.
2. Top-level fields accepted for prompts: `name`, `description`, `x-personal-mcp`.
3. Unknown top-level fields are rejected during registry load.

Skill and prompt identifier rules:

1. `name` is required, 1-64 chars, lowercase kebab-case, and must not contain `anthropic` or `claude`.
2. `description` is required, 1-1024 chars.
3. `x-personal-mcp.id` must exactly match `name`.
4. Directory slug must exactly match `name`.

Capability invariants:

1. Skill capabilities must include `resource://skills/<skill-id>/document`.
2. Prompt capabilities must include `resource://prompts/<prompt-id>/document`.

Repository contract decisions:

1. Treat `name` and `description` as required in all `SKILL.md` files.
2. Keep only validated standard fields at top level.
3. Keep MCP indexing metadata in a namespaced extension block.
4. Reject unsupported optional top-level fields until explicit model support is added.

Reference specs:

1. MCP prompts data types: [Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts)
2. MCP schema reference for `Prompt` and `PromptArgument`: [Schema](https://modelcontextprotocol.io/specification/latest/schema)

## Canonical Frontmatter Schema

Use this two-layer pattern:

1. Anthropic layer: top-level fields intended for Anthropic and Agent Skills behavior.
2. Repository layer: one namespaced block, `x-personal-mcp`, for MCP catalog and routing metadata.

Canonical shape:

```yaml
---
name: <skill-id>
description: <what this skill does and when to use it>

# Repository-specific metadata
x-personal-mcp:
  id: <skill-id>
  version: <semver>
  tags:
    - <tag>
  capabilities:
    - resource://skills/<skill-id>/document
    # Optional: overrides and nested references only.
    # Top-level references/*.md are auto-discovered.
  references:
    <ref-id>:
      path: references/<file>.md
      mime_type: text/markdown
      title: <short title>
---
```

## Repository Metadata Field Rules

Rules for `x-personal-mcp`:

1. `id` is required, must follow the skill id rules from the content contract, and must equal the directory name.
2. `version` is required and must be a semantic version string.
3. `tags` is optional and should be a list of kebab-case discovery labels.
4. `capabilities` is required and lists the MCP URIs the skill publishes.
5. `references` is an optional map keyed by `ref-id` for overrides and nested entries.

Prompt-specific additions:

1. `arguments` is an optional map keyed by argument name.
2. Each argument supports optional `title`, optional `description`, and optional `required`.
3. This aligns with MCP `PromptArgument` shape (`name`, optional `title`, optional `description`, optional `required`) where `name` is represented by the map key.
4. Prompt `capabilities` must include `resource://prompts/<prompt-id>/document`.

Example prompt frontmatter:

```yaml
---
name: initial-test-structure
description: Generate a baseline pytest test layout for a target scope.
x-personal-mcp:
    id: initial-test-structure
    version: 1.0.0
    tags:
        - pytest
        - testing
    capabilities:
        - resource://prompts/initial-test-structure/document
    arguments:
        target_scope:
            title: Target scope
            description: Target package or module under test.
            required: true
---
```

Reference entry rules:

1. `ref-id` is lowercase kebab-case.
2. `path` is a skill-relative markdown path and must stay inside the same skill directory.
3. Top-level files under `references/*.md` are auto-discovered with `ref-id` derived from a normalized filename stem (lowercase kebab-case).
4. Nested folders under `references/` are not auto-discovered and must be declared explicitly.
5. `mime_type` defaults to `text/markdown` when omitted.
6. `title` is an optional display label.
7. Renaming `ref-id` values is allowed when needed; optional aliases may be used during transitions.

## Auto-Generated Reference IDs

Top-level markdown files directly under `references/` are auto-registered as MCP references even when `x-personal-mcp.references` is empty.

How `ref-id` is derived:

1. Start from the filename stem (without `.md`).
2. Normalize to lowercase kebab-case.
3. Publish at `resource://skills/<skill-id>/references/<ref-id>`.

Examples:

1. `references/ruff-docs.md` -> `ref-id: ruff-docs`
2. `references/Ruff Integrations.md` -> `ref-id: ruff-integrations`
3. `references/python_logging_docs.md` -> `ref-id: python-logging-docs`

When to use explicit `x-personal-mcp.references` entries:

1. The file is nested, for example `references/guides/ci.md`.
2. You need to override defaults (`title`, `mime_type`, or custom `ref-id`).
3. You need compatibility aliases during a rename.

## Validation Models

The normative runtime model uses strict Pydantic v2 validation:

1. Models are immutable (`frozen=True`) and reject unknown fields (`extra="forbid"`).
2. `SkillFrontmatter` accepts only `name`, `description`, and `x-personal-mcp`.
3. `PromptFrontmatter` accepts only `name`, `description`, and `x-personal-mcp`.
4. `PromptArgumentEntry` accepts only optional `title`, optional `description`, and optional `required`.
5. Skill and prompt metadata enforce semver, kebab-case ids, capability requirements, and id/name/directory consistency.
6. Reference paths are validated as markdown files under `references/`.

Validation behavior contract:

1. Validate required core fields and relationships during registry load before FastMCP resource or tool registration.
2. Reject unknown or unsupported fields at parse and model-validation time.
3. Treat hard contract violations, including missing required fields, invalid ids, and broken required mappings, as startup errors.
4. Keep failure messages path-aware and field-specific for CI readability.

Projection mode contract for Anthropic API upload pipelines:

1. Parse with `SkillFrontmatter` first.
2. Emit Anthropic-safe frontmatter with standard fields only.
3. Preserve `x-personal-mcp` in source-of-truth documents; projection output is a build artifact.

## Anthropic Upload Compatibility Rule

1. Anthropic documentation guarantees behavior for standard frontmatter fields but does not explicitly guarantee handling of arbitrary unknown top-level keys.
2. Publishing pipelines that target strict API compatibility should support a projection mode that emits only standard frontmatter fields for upload.
3. Source-of-truth authoring remains in `x-personal-mcp`; upload payload shape is an explicit build concern.

## FastMCP Native Metadata Surfaces

Resources support native definition metadata:

1. `name`
2. `description`
3. `mime_type`
4. `tags`
5. `annotations`, including `readOnlyHint` and `idempotentHint`
6. `icons`
7. `meta`
8. `version`
9. `enabled`, which is deprecated in FastMCP v3 in favor of server-level enable and disable controls

Resources also support runtime metadata through `ResourceContent.meta` and `ResourceResult.meta`.

Tools support native definition metadata:

1. `name`
2. `description`
3. `tags`
4. `annotations`, including `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`
5. `icons`
6. `meta`
7. `version`
8. `timeout`
9. `output_schema`
10. `run_in_thread`
11. `enabled`, which is deprecated in FastMCP v3 in favor of server-level enable and disable controls

Tools also support runtime metadata through `ToolResult.meta`.

## Frontmatter To FastMCP Mapping Contract

At server startup, map `x-personal-mcp` into FastMCP registration as follows:

1. `x-personal-mcp.id` defines the canonical URI namespace and identity checks.
2. `description` becomes the default description for the primary skill document resource.
3. `x-personal-mcp.tags` maps to resource and tool tags.
4. `x-personal-mcp.version` maps to resource and tool version metadata.
5. `x-personal-mcp.capabilities` becomes the registered URI list and catalog exposure.
6. `x-personal-mcp.references[*]` becomes resource templates or concrete resources with `mime_type`, read-only annotations, and `meta` that includes `skill_id`, `ref_id`, and source `path`.

## Invariants

This contract guarantees:

1. Anthropic-required frontmatter stays valid for custom skill upload and Claude Code loading.
2. MCP-specific metadata remains embedded in `SKILL.md` frontmatter, with no `metadata.yaml` sidecar.
3. FastMCP registration uses native metadata fields for resources and tools.
4. Reference ids and metadata can evolve with low-friction updates while internal file layout under `references/` stays refactor-friendly.

## Non-Goals

This contract does not define:

1. URI versioning and deprecation rollout policy details.
2. Migration script design from existing `metadata.yaml` files.
3. Runtime caching and indexing performance tuning.