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

doc updates

Browse Source
This commit is contained in:
John Lancaster
2026-06-21 18:12:58 -05:00
parent 69cd9037a3
commit 1f7e63267a
10 changed files with 75 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/content.md
+88
View File
@@ -0,0 +1,88 @@
---
icon: lucide/file-text
---
# Content Contract
This page defines the authored content contract for the docs-first MCP architecture.
## Canonical Source Of Truth
1. All authored Markdown lives under `docs/`.
2. MCP resources and static docs are two distribution surfaces of the same authored files.
3. No parallel authored markdown is allowed in `src/` or other package-only paths.
## Canonical Skill Shape
Each skill is one directory under `docs/skills/`:
```text
docs/
skills/
<skill-id>/
SKILL.md
references/
... (one or more markdown files, optional nested folders)
```
Rules:
1. `SKILL.md` is required for every skill.
2. `references/` is the only place for skill-specific supporting docs.
3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
4. Skill directories are independent ownership boundaries; no cross-skill file writes.
## File Placement And Ownership Boundaries
1. Top-level project docs stay in `docs/*.md`.
2. Skill docs stay in `docs/skills/<skill-id>/...`.
3. A skill may link to other skills, but must not store content inside another skill's directory.
4. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
## 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.
## Skill Id Contract
`skill-id` is the public identifier and should satisfy all rules below:
1. Format: lowercase kebab-case only.
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.
7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
Valid examples:
1. `fastapi-uv-docker`
2. `zensical-docs`
3. `pytest-scaffolding`
Invalid examples:
1. `fastapi_uv_docker`
2. `Zensical-Docs`
3. `docs.zensical`
## Invariants
This contract guarantees:
1. One authored source tree in `docs/` for both website and MCP.
2. One skill directory maps to one skill identity per revision.
3. Namespace and slug drift is minimized by keeping directory and frontmatter ids aligned per revision.
4. Per-skill reference structure can evolve without changing cross-skill architecture.
5. Packaging for stdio is deterministic because authored content is path-stable.
## Non-Goals
This contract does not define:
1. URI versioning policy details.
2. The full frontmatter schema.
3. Migration instructions from the current architecture.
docs/contracts/frontmatter.md
+369
View File
@@ -0,0 +1,369 @@
---
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 optional typed argument metadata.
## Anthropic Frontmatter Support
Across Anthropic API and Agent Skills surfaces:
1. Required fields for custom skill bundles are `name` and `description`.
2. `name` must be 1-64 characters, lowercase letters, numbers, and hyphens only, with no XML tags, and must not use the reserved words `anthropic` or `claude`.
3. `description` must be 1-1024 characters, non-empty, and contain no XML tags.
Portable optional fields from the Agent Skills specification:
1. `license`
2. `compatibility`
3. `metadata`
4. `allowed-tools`
Claude Code-specific optional fields:
1. `when_to_use`
2. `argument-hint`
3. `arguments`
4. `disable-model-invocation`
5. `user-invocable`
6. `allowed-tools`
7. `disallowed-tools`
8. `model`
9. `effort`
10. `context`
11. `agent`
12. `hooks`
13. `paths`
14. `shell`
Repository contract decisions:
1. Treat `name` and `description` as required in all `SKILL.md` files.
2. Keep Anthropic-facing semantics in standard fields.
3. Keep MCP indexing metadata in a namespaced extension block.
4. Preserve forward compatibility by allowing additive optional metadata fields over time.
## 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>
# Optional Anthropic and Agent Skills fields
when_to_use: <extra trigger guidance>
allowed-tools: <space-separated string or YAML list>
disable-model-invocation: false
user-invocable: true
license: <optional>
compatibility: <optional>
# Repository-specific metadata
x-personal-mcp:
id: <skill-id>
version: <semver>
tags:
- <tag>
capabilities:
- resource://skills/<skill-id>/document
depends_on: []
# 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. `depends_on` is optional and lists other skill ids.
6. `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 `type`, optional `description`, optional `required`, optional `default`, and optional `enum`.
3. `type` must be one of `string`, `number`, `integer`, `boolean`, `array`, or `object`.
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:
type: string
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 model uses Pydantic v2 with change-friendly validation:
```python
from __future__ import annotations
import re
from pathlib import PurePosixPath
from typing import Any
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
SKILL_ID_RE = re.compile(r"^[a-z][a-z0-9-]*$")
SEMVER_RE = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:[-+][0-9A-Za-z.-]+)?$")
class ReferenceEntry(BaseModel):
model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
path: str
mime_type: str = "text/markdown"
title: str | None = None
@field_validator("path")
@classmethod
def validate_reference_path(cls, value: str) -> str:
p = PurePosixPath(value)
if p.is_absolute() or ".." in p.parts:
raise ValueError("reference path must be a relative in-skill path")
if not str(p).startswith("references/"):
raise ValueError("reference path must stay under references/")
if p.suffix.lower() != ".md":
raise ValueError("reference path must target a markdown file")
return str(p)
class PersonalMcpMetadata(BaseModel):
model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
id: str
version: str
tags: list[str] = Field(default_factory=list)
capabilities: list[str] = Field(min_length=1)
depends_on: list[str] = Field(default_factory=list)
references: dict[str, ReferenceEntry] = Field(default_factory=dict)
@field_validator("id")
@classmethod
def validate_id(cls, value: str) -> str:
if not SKILL_ID_RE.fullmatch(value):
raise ValueError("id must be lowercase kebab-case and start with a letter")
return value
@field_validator("version")
@classmethod
def validate_version(cls, value: str) -> str:
if not SEMVER_RE.fullmatch(value):
raise ValueError("version must be semver")
return value
@field_validator("depends_on")
@classmethod
def validate_depends_on(cls, value: list[str]) -> list[str]:
for dep in value:
if not SKILL_ID_RE.fullmatch(dep):
raise ValueError(f"invalid depends_on skill id: {dep}")
return value
@field_validator("references")
@classmethod
def validate_reference_ids(cls, value: dict[str, ReferenceEntry]) -> dict[str, ReferenceEntry]:
for ref_id in value:
if not SKILL_ID_RE.fullmatch(ref_id):
raise ValueError(f"invalid reference id: {ref_id}")
return value
@model_validator(mode="after")
def ensure_primary_capability(self) -> "PersonalMcpMetadata":
expected = f"resource://skills/{self.id}/document"
if expected not in self.capabilities:
raise ValueError(f"capabilities must include {expected}")
return self
class SkillFrontmatter(BaseModel):
model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
name: str = Field(min_length=1, max_length=64)
description: str = Field(min_length=1, max_length=1024)
when_to_use: str | None = None
allowed_tools: str | list[str] | None = Field(default=None, alias="allowed-tools")
disallowed_tools: str | list[str] | None = Field(default=None, alias="disallowed-tools")
disable_model_invocation: bool | None = Field(default=None, alias="disable-model-invocation")
user_invocable: bool | None = Field(default=None, alias="user-invocable")
argument_hint: str | None = Field(default=None, alias="argument-hint")
arguments: str | list[str] | None = None
license: str | None = None
compatibility: str | None = None
metadata: dict[str, str] | None = None
x_personal_mcp: PersonalMcpMetadata = Field(alias="x-personal-mcp")
@field_validator("name")
@classmethod
def validate_name(cls, value: str) -> str:
if not SKILL_ID_RE.fullmatch(value):
raise ValueError("name must be lowercase kebab-case and start with a letter")
if "anthropic" in value or "claude" in value:
raise ValueError("name must not contain reserved words anthropic or claude")
return value
@model_validator(mode="after")
def cross_validate(self) -> "SkillFrontmatter":
if self.x_personal_mcp.id != self.name:
raise ValueError("x-personal-mcp.id must exactly match name")
return self
def validate_skill_frontmatter(raw: dict[str, Any], skill_dir_name: str) -> SkillFrontmatter:
model = SkillFrontmatter.model_validate(raw)
if model.name != skill_dir_name:
raise ValueError("frontmatter name must exactly match skill directory name")
return model
```
Validation behavior contract:
1. Validate required core fields and relationships during registry load before FastMCP resource or tool registration.
2. Allow unknown additive fields so frontmatter can evolve without blocking startup.
3. Treat hard contract violations, including missing required fields, invalid ids, and broken required mappings, as startup errors.
4. Treat non-critical compatibility issues as warnings when possible.
5. Error messages should include the skill path and failing field 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. Serialize repository metadata into standard `metadata` as namespaced keys.
4. Preserve the canonical authored source in `x-personal-mcp`; 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. In projection mode, repository extension metadata is serialized into the standard `metadata` field as namespaced keys or JSON-encoded values, while source-of-truth authoring remains in `x-personal-mcp`.
## 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`.
7. `x-personal-mcp.depends_on` becomes catalog dependency graph metadata and validation inputs.
## 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.
docs/contracts/index.md
+15
View File
@@ -0,0 +1,15 @@
---
icon: lucide/file-check-2
---
# Contracts
This section groups the core data and contract documents for the repository.
## Pages
1. [Content Contract](./content.md)
2. [Frontmatter Contract](./frontmatter.md)
3. [URI Contract](./uris.md)
Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.
docs/contracts/uris.md
+143
View File
@@ -0,0 +1,143 @@
---
icon: lucide/link
---
# URI Contract
This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
## Canonical URI Surface
The public, preferred URIs are:
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`
Contract intent:
1. Catalog URIs are discovery surfaces.
2. Skill URIs are the primary per-skill guidance surfaces.
3. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
## URI Semantics
### `resource://catalog/skills_index`
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`.
### `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.
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/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.
2. No leading slash.
3. No `..` traversal segments.
4. Resolves only inside `docs/`.
5. Markdown-only in the end state, meaning `.md` files.
### `prompt_id`
1. Lowercase kebab-case.
2. Must be unique across prompt ids and must not collide with skill ids.
## 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.