changed to skill provider
This commit is contained in:
John Lancaster
+50
-204
@@ -4,231 +4,77 @@ icon: lucide/braces
|
||||
|
||||
# Frontmatter Contract
|
||||
|
||||
This page defines the `SKILL.md` frontmatter and FastMCP metadata contract.
|
||||
This page defines the authored frontmatter contracts for native FastMCP skills and registry-backed prompts.
|
||||
|
||||
Prompt modules use the same contract style in `docs/prompts/<prompt-id>/PROMPT.md` with prompt-specific capability and MCP-aligned prompt argument metadata.
|
||||
## Skill Frontmatter
|
||||
|
||||
## 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:
|
||||
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 this skill does and when to use it>
|
||||
description: <what the skill does and when to use it>
|
||||
---
|
||||
```
|
||||
|
||||
# Repository-specific metadata
|
||||
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: <skill-id>
|
||||
id: <prompt-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>
|
||||
- resource://prompts/<prompt-id>/document
|
||||
arguments:
|
||||
<argument-name>:
|
||||
title: <display title>
|
||||
description: <input guidance>
|
||||
required: true
|
||||
---
|
||||
```
|
||||
|
||||
## Repository Metadata Field Rules
|
||||
Prompt rules:
|
||||
|
||||
Rules for `x-personal-mcp`:
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Prompt-specific additions:
|
||||
## Validation Timing
|
||||
|
||||
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`.
|
||||
Skill validation is file- and provider-oriented:
|
||||
|
||||
Example prompt frontmatter:
|
||||
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.
|
||||
|
||||
```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`.
|
||||
Prompt validation remains registry-oriented and fails server startup for invalid metadata, duplicate prompt ids, or malformed arguments.
|
||||
|
||||
## 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.
|
||||
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/`.
|
||||
|
||||
Reference in New Issue
Block a user