234 lines
9.0 KiB
Markdown
234 lines
9.0 KiB
Markdown
---
|
|
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. |