prompts/docs/uris.md

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*}

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.

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.

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.