Skills Over MCP
skill://is a URI convention — not a mandatory part of base MCP — for exposing
agent skill content (instructions plus optional scripts, references, templates,
examples) as MCP resources, read progressively rather than all
injected into context at once.
Layered model
MCP resource protocol = standardized discovery/read/update mechanisms
URI scheme = naming and identity convention
skill:// = a convention meaning "this is skill-package content"
Agent skill package = instructions + optional scripts/references/templates/assets MCP standardizes the underlying resource mechanism (listing, reading, templates,
updates); it does not universally require skill:// as the skill URI scheme. The
Skills-over-MCP proposal from the Agentic AI Foundation uses skill:// and
progressive disclosure specifically, but it’s an evolving ecosystem convention rather
than a base-MCP requirement.
Skill package shape
A skill should be a small package, not one giant prompt:
skill://client-discovery/SKILL.md
skill://client-discovery/manifest.json
skill://client-discovery/references/discovery-questions.md
skill://client-discovery/templates/call-summary.md
skill://client-discovery/scripts/score-intake.py
skill://client-discovery/examples/good-output.md The agent reads the short entry point (SKILL.md) first, then retrieves references,
templates, scripts, and examples only when relevant — progressive disclosure, meant to
prevent hundreds of skills from being dumped into context at once. FastMCP’s skills
provider implements exactly this: skill content exposed as resources under a
skill:// scheme, including main instructions and manifest/package material.
Reading a skill resource does not execute it. The agent uses the instructions and
calls applicable tools when it needs to actually act — skills are read-oriented
context, not actions.
Recommended namespace division
| Prefix | Answers |
|---|---|
skill:// | How should the agent work? (portable instructions + bundled assets) |
thirdbrain:// (or any company namespace) | What business-domain context is it working on? |
obsidian:// | Where does this come from in the source vault? |
| tool calls | What may the agent search, calculate, or change? |
First-hand example: this vault’s own skills MCP server
This exact pattern is live, not just theoretical, in this workspace: the skills MCP
server (see KB-AI/ai-coding/* skill notes and this session’s own tool access)
implements skills_search_skills → skills_get_skill → skills_read_skill_file
against skill://<library>/<skill-name>/<file> URIs, with every file carrying a
sha256 digest. It’s described to the agent explicitly as “loaded on demand
(progressive disclosure), never all at once)” — the same rationale as above, and
confirms hosts implementing the MCP Skills extension (SEP-2640) can instead use
skills/list, skills/get, and resources/read on skill:// URIs directly.
See also
- MCP Resources — the underlying protocol mechanism this convention builds on
- Atomic (Bastani) — a “Skills” concept inside a coding-agent runtime, a related but distinct usage of the word
- Model Context Protocol