prompts/docs/contracts/frontmatter.md

icon

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
2. MCP schema reference for Prompt and PromptArgument: 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:

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

---
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.