prompts/.github/prompts/plan-step3.prompt.md

Step 3 Results: URI Contract and Compatibility Policy

This section finalizes Step 3 by defining the canonical resource URI contract, template parameter rules, and explicit compatibility/versioning policy for URIs and reference ids.

Step Deliverable

• Update the current docs/ directory with the finalized Step 3 URI contract and compatibility policy content from this document.

Canonical URI Surface (Normative)

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:

• Catalog URIs are discovery surfaces.
• Skill URIs are primary per-skill guidance surfaces.
• Docs wildcard URI is a direct authored-markdown access surface under docs/.

URI Semantics

resource://catalog/skills_index

• Returns a compact list of skill records for discovery.
• One entry per skill_id.
• Must include enough metadata for client-side selection (at minimum id, name, description, tags, capabilities).

resource://catalog/skills/{skill_id}

• Returns one normalized record for skill_id.
• Must include canonical document URI and declared reference ids.
• Returns not-found when skill_id does not exist.

resource://skills/{skill_id}/document

• Returns the canonical SKILL.md authored content for that skill.
• skill_id must match Step 1 stable id rules.

resource://skills/{skill_id}/references/{ref_id}

• Returns one reference document declared in the skill frontmatter references manifest.
• ref_id is the stable public handle for that reference document.

resource://docs/{path*}

• Returns authored markdown at a normalized relative path under docs/.
• Supports nested paths via RFC6570 wildcard expansion.
• Typical examples: index.md, usage.md, skills/<skill-id>/SKILL.md, skills/<skill-id>/references/<file>.md.

Template Parameter and Validation Rules

skill_id

• Lowercase kebab-case.
• Must satisfy Step 1 stable id rules.

ref_id

• Lowercase kebab-case.
• Must be declared in the skill’s references manifest.

path*

• Relative POSIX path only.
• No leading slash.
• No .. traversal segments.
• Resolves only inside docs/.
• This surface is markdown-only in end state (.md files).

URI Versioning Policy

Default rule:

• Keep URIs unversioned by default.
• Allow URI and payload updates when they improve clarity or implementation simplicity.

Breaking-change rule:

• Breaking changes use direct replacement of the canonical URI family.
• No compatibility aliases or dual URI families are maintained in this greenfield phase.

FastMCP version metadata usage:

• Resource version metadata MAY be used for implementation/version discovery.
• 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:

• Prefer keeping ref_id stable when practical.
• File paths may change without URI churn as long as the mapped ref_id resolves.
• If a reference is renamed, introduce a new ref_id and treat the old one as retired.
• Avoid reusing retired ref_id values for unrelated content.

Invariants This Contract Guarantees

• One canonical URI pattern per core capability surface.
• Fast, low-friction URI evolution through direct replacement of canonical URIs.
• A single canonical catalog URI family with no alias maintenance overhead.
• Reference mappings can evolve with minimal churn.

Non-goals For Step 3

• No implementation-specific transform wiring details (VersionFilter, mounts, provider composition).
• No migration script mechanics for auto-generating aliases.
• No authorization policy design for URI-level access control.