Map out the end-to-end discovery path (well-known + skills over MCP + configuration)

[olaservo]

Context

From the April 7, 2026 Office Hours, there's a need to fully map out the end-to-end discovery path — how does skill discovery actually work from domain resolution through configuration to runtime loading?

Currently, several pieces exist independently:

• Well-known URIs — the Agent Skills Discovery RFC defines /.well-known/agent-skills/index.json for domain-level discovery. Vercel/Mintlify already supports npx skills add <domain> pulling from well-known URIs.
• Skills over MCP — the skill:// URI scheme and skill://index.json resource for MCP-level discovery (SEP in progress via Skills Extension SEP — spec, URI scheme, and reference implementation #75).
• Configuration — how clients are configured to connect to skill servers and load skills at runtime.

What's missing is a clear picture of how these layers compose into a single coherent path.

Deliverable

A document or diagram mapping the complete discovery pathway:

1. Domain resolution — user provides a domain → well-known URI lookup
2. Manifest/index retrieval — index.json content and structure
3. MCP server connection — how the well-known URI leads to an MCP server endpoint
4. Skill resource loading — skill:// resource discovery and reading at runtime
5. Client configuration — how this gets wired into a client's settings

Using modelcontextprotocol.io as a dog-fooding example was discussed. Currently Mintlify controls the well-known URI for that domain, so hosting custom MCP skills there would require either Mintlify adding that feature or using a separate subdomain.

Related

• Agent Skills Discovery RFC
• Skills Extension SEP — spec, URI scheme, and reference implementation #75 — Skills Extension SEP
• Mintlify-generated SKILL.md at well-known URI
• April 7 meeting notes, section 5

🦉 Generated with Claude Code

[olaservo]

Adding a few preliminary diagrams:

• Well-Known HTTP Discovery: https://drive.google.com/file/d/14G2BAyVmf5BJ8dJeaPCo_5y-eW6vCFX_/view?usp=sharing
• Well-Known HTTP to MCP Runtime Bridge: https://drive.google.com/file/d/14stXSx7DbLKsN7pvj-78S5uzY3gOWn7z/view?usp=sharing
• MCP-Native Discovery via skill://index.json: https://drive.google.com/file/d/1ImYzMKQvisrA6rezGuLI5H8Ec6XC7ukI/view?usp=sharing