john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

changed to skill provider

Browse Source
This commit is contained in:
John Lancaster
2026-08-07 19:09:54 -05:00
parent c6817a074e
commit 44edffb8b7
48 changed files with 552 additions and 2946 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/frontmatter.md
+50 -204
View File
@@ -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/`.
docs/contracts/skill_contract.md
+15 -5
View File
@@ -40,9 +40,9 @@ Rules:
## Metadata Location Constraint
1. Skill metadata is embedded in YAML frontmatter in `SKILL.md`.
2. No `metadata.yaml` sidecar exists in the end state.
3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `SKILL.md` frontmatter declares overrides and nested mappings when needed.
1. `SKILL.md` frontmatter contains only standard `name` and `description` fields.
2. No `metadata.yaml` sidecar or repository-specific skill metadata block exists.
3. The provider discovers supporting files recursively; their real relative paths are published in the generated `_manifest`.
## Skill Id Contract
@@ -52,8 +52,8 @@ Rules:
2. Character set: `a-z`, `0-9`, and `-`.
3. Must start with a letter.
4. No underscores, spaces, dots, or uppercase characters.
5. Directory name should equal `skill-id` in each committed revision.
6. Frontmatter `id` should equal directory name in each committed revision.
5. Directory name equals `skill-id` in each committed revision.
6. Frontmatter `name` equals the directory name.
7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
Valid examples:
@@ -68,6 +68,16 @@ Invalid examples:
2. `Zensical-Docs`
3. `docs.zensical`
## Provider Publication
[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans `docs/skills/` with `supporting_files="template"` and publishes:
1. `skill://<skill-id>/SKILL.md`
2. `skill://<skill-id>/_manifest`
3. `skill://<skill-id>/{path*}` for supporting files
Only the main file and manifest appear in `resources/list`. Clients inspect the manifest before reading supporting paths.
## Direct Documentation Inclusion
1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
docs/contracts/uris.md
+58 -162
View File
@@ -4,183 +4,79 @@ icon: lucide/link
# URI Contract
This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
This page defines the public resource URI contract for native skills, registry-backed prompts, and general authored documentation.
Conventions in this document follow [MCP resource semantics](https://modelcontextprotocol.io/docs/learn/server-concepts#resources), [URI generic syntax (RFC3986)](https://www.rfc-editor.org/rfc/rfc3986), and [URI templates (RFC6570)](https://www.rfc-editor.org/rfc/rfc6570).
## Native Skill URIs
## Canonical URI Surface
The [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills) publishes each skill through the `skill://` scheme:
The public, preferred direct resource URIs are:
1. `skill://<skill-name>/SKILL.md`
2. `skill://<skill-name>/_manifest`
3. `skill://<skill-name>/<supporting-path>`
1. `resource://catalog/skills_index`
2. `resource://catalog/skills/{skill_id}`
3. `resource://skills/{skill_id}/document`
4. `resource://skills/{skill_id}/references/{ref_id}`
5. `resource://docs/{path*}`
6. `resource://catalog/prompts_index`
7. `resource://catalog/prompts/{prompt_id}`
8. `resource://prompts/{prompt_id}/document`
The first two are concrete resources returned by `resources/list`. Supporting files use a per-skill wildcard resource template when the provider is configured with `supporting_files="template"`:
The public, preferred resource template URIs are:
```text
skill://<skill-name>/{path*}
```
1. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
### Main File
`skill://<skill-name>/SKILL.md` returns the canonical authored skill document. The skill directory name supplies `<skill-name>`, and the resource description comes from `SKILL.md` frontmatter.
### Manifest
`skill://<skill-name>/_manifest` returns JSON containing the skill name and every file beneath its directory. Each file entry includes:
1. relative POSIX path
2. byte size
3. SHA256 hash
Clients read the manifest before requesting supporting files. FastMCP client utilities such as `list_skills()` and `get_skill_manifest()` understand this contract directly.
### Supporting Files
Supporting files retain their real skill-relative paths. For example:
```text
skill://pytesting/references/pytest-docs.md
```
FastMCP confines reads to the selected skill directory. Absolute paths, traversal outside the directory, missing files, directories, and symlinks that resolve outside the skill root are rejected.
## Prompt And Docs URIs
Prompts and general documentation retain the existing registry-backed resource surface:
1. `resource://catalog/prompts_index`
2. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
3. `resource://catalog/prompts/{prompt_id}`
4. `resource://prompts/{prompt_id}/document`
5. `resource://docs/{path*}`
Contract intent:
Prompt ids remain lowercase kebab-case. The docs wildcard accepts normalized relative POSIX Markdown paths beneath `docs/` and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.
1. Catalog URIs are discovery surfaces.
2. Skill URIs are the primary per-skill guidance surfaces.
3. Catalog query templates are additive discovery helpers for filtering and pagination.
4. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
## Discovery Order
Best-practice alignment:
For skills:
1. Resource identifiers are stable and noun-oriented.
2. Dynamic lookup variants are represented as RFC6570 templates.
3. Resources remain read-oriented and are described with explicit MIME types.
1. list resources or call FastMCP `list_skills()`
2. select a skill by name and description
3. read `skill://<skill-name>/SKILL.md`
4. read `_manifest` when supporting material may be needed
5. fetch only the supporting paths relevant to the task
## URI Semantics
For prompts, use the prompt catalog or MCP prompt-object APIs.
### `resource://catalog/skills_index`
## Compatibility Policy
1. Returns a compact list of skill records for discovery.
2. Contains one entry per `skill_id`.
3. Includes enough metadata for client-side selection, at minimum `id`, `name`, `description`, `tags`, and `capabilities`.
The native `skill://` family directly replaces the repository's former custom skill URI and catalog surfaces. No compatibility aliases or dual registrations are maintained. Prompt and general-doc URIs are unaffected.
### `resource://catalog/skills/{skill_id}`
1. Returns one normalized record for `skill_id`.
2. Includes the canonical document URI and declared reference ids.
3. Returns not found when `skill_id` does not exist.
### `resource://skills/{skill_id}/document`
1. Returns the canonical `SKILL.md` authored content for that skill.
2. `skill_id` must satisfy the stable skill id rules from the content contract.
### `resource://skills/{skill_id}/references/{ref_id}`
1. Returns one reference document declared in the skill frontmatter references manifest.
2. `ref_id` is the stable public handle for that reference document.
### `resource://docs/{path*}`
1. Returns authored markdown at a normalized relative path under `docs/`.
2. Supports nested paths via [RFC6570 wildcard expansion](https://www.rfc-editor.org/rfc/rfc6570).
3. Typical examples include `index.md`, `usage.md`, `skills/<skill-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.md`.
### `resource://catalog/prompts_index`
1. Returns a compact list of prompt records for discovery.
2. Contains one entry per `prompt_id`.
3. Includes `id`, `name`, `description`, `tags`, `version`, and canonical document URI.
### `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
1. Returns the same record family as `resource://catalog/skills_index` with optional filtering and pagination.
2. Query parameters are optional and composable.
3. Unknown query keys are ignored or rejected deterministically by server policy.
### `resource://catalog/prompts_index{?q,tag,cursor,limit}`
1. Returns the same record family as `resource://catalog/prompts_index` with optional filtering and pagination.
2. Query parameters are optional and composable.
3. Unknown query keys are ignored or rejected deterministically by server policy.
### `resource://catalog/prompts/{prompt_id}`
1. Returns one normalized record for `prompt_id`.
2. Includes prompt argument metadata when declared in frontmatter.
3. Returns not found when `prompt_id` does not exist.
### `resource://prompts/{prompt_id}/document`
1. Returns the canonical prompt markdown document.
2. `prompt_id` must satisfy lowercase kebab-case rules.
## Template Parameter And Validation Rules
### `skill_id`
1. Lowercase kebab-case.
2. Must satisfy the stable skill id rules from the content contract.
### `ref_id`
1. Lowercase kebab-case.
2. Must be declared in the skill's references manifest.
### `path*`
1. Relative POSIX path only, expressed as URI path segments under [RFC3986 path syntax](https://www.rfc-editor.org/rfc/rfc3986#section-3.3).
2. No leading slash.
3. No `..` traversal segments.
4. Resolves only inside `docs/`.
5. Markdown-only in the end state, meaning `.md` files.
6. Any reserved URI characters in path segments must be [percent-encoded](https://www.rfc-editor.org/rfc/rfc3986#section-2.1).
### `prompt_id`
1. Lowercase kebab-case.
2. Must be unique across prompt ids and must not collide with skill ids.
## URI Hygiene Rules
1. Use lowercase, human-readable path segments for stable discoverability.
2. Keep identifiers immutable once public whenever practical.
3. Keep template variables semantic (`skill_id`, `prompt_id`, `ref_id`, `path*`) and avoid overloading one variable for unrelated meanings.
4. Do not include secrets, tokens, or user-identifying data in URI paths or query strings.
5. Prefer additive query parameters for discovery over introducing parallel URI families, matching [MCP resource-template discovery patterns](https://modelcontextprotocol.io/docs/learn/server-concepts#resources).
6. Return clear not-found semantics for unknown ids and invalid template resolution.
## URI Versioning Policy
Default rule:
1. Keep URIs unversioned by default.
2. Allow URI and payload updates when they improve clarity or implementation simplicity.
Breaking-change rule:
1. Breaking changes use direct replacement of the canonical URI family.
2. No compatibility aliases or dual URI families are maintained.
FastMCP version metadata usage:
1. Resource `version` metadata may be used for implementation and version discovery.
2. URI readability and maintainability remain the primary contract.
## Reference Id Compatibility Policy
`ref_id` is the public identifier for a reference document, separate from file path.
Rules:
1. Prefer keeping `ref_id` stable when practical.
2. File paths may change without URI churn as long as the mapped `ref_id` still resolves.
3. If a reference is renamed, introduce a new `ref_id` and treat the old one as retired.
4. Avoid reusing retired `ref_id` values for unrelated content.
## Invariants
This contract guarantees:
1. One canonical URI pattern per core capability surface.
2. Fast, low-friction URI evolution through direct replacement of canonical URIs.
3. A single canonical catalog URI family with no alias maintenance overhead.
4. Reference mappings can evolve with minimal churn.
## Non-Goals
This contract does not define:
1. Implementation-specific transform wiring details, such as `VersionFilter`, mounts, or provider composition.
2. Migration script mechanics for auto-generating aliases.
3. Authorization policy design for URI-level access control.
Skill renames are breaking because the directory name is part of every native skill URI. Supporting-file renames change the corresponding manifest path and URI.
## Sources
1. [MCP Server Concepts: Resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources)
2. [MCP Architecture Overview](https://modelcontextprotocol.io/docs/learn/architecture)
3. [MCP Specification Repository](https://github.com/modelcontextprotocol/spec)
4. [RFC6570 URI Template](https://www.rfc-editor.org/rfc/rfc6570)
1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
2. [MCP resources](https://modelcontextprotocol.io/specification/latest/server/resources)
3. [RFC 3986 URI syntax](https://www.rfc-editor.org/rfc/rfc3986)
4. [RFC 6570 URI templates](https://www.rfc-editor.org/rfc/rfc6570)