experimental-ext-skills

(Note: this diff includes syncing the change that migrated the rationale text to this repo instead, since the diff was getting too large to review the spec text itself easily.)

Adding a breakdown of Agent Plugins 1.0 vs skills over MCP - open for comment. :)

Adds an entry for issue #66 — implementing discovery in VS Code and running it against a live MCP server. Docs-only. The implementation lives in tobi-oye/vscode#1; this is a docs repo, so only the write-up belongs here. Motivation and Context Issue #66 asks for a prototype of skill resource loading in a major open-source client. This is that prototype, plus what it taught us. The short version: VS Code already had almost everything needed. It has the full progressive-disclosure loop — discover skills, put just their names and descriptions in the model's context, give the model a tool to load the full text on demand. The only missing piece was that a skill could never come from an MCP server. And the loading half needed no new code at all, because is already registered with VS Code's filesystem service. So the work was small. The findings are the valuable part. Screenshots How Has This Been Tested? Against the live Hugging Face MCP server (, anonymous) from a source build of VS Code: 8 skills discovered and offered to the model with no manual attachment over VS Code's — clean 10 unit tests, including a → round trip and index parsing against verbatim live server output 112 existing promptSyntax tests still pass Not tested: the model actually choosing to load an MCP-served skill. Source builds of VS Code can't reach the Copilot service, and the available model was a small auto-routed one. Called out as open in the entry — discovery is verified by observation, loading only by mechanism. Breaking Changes None. Docs-only. Types of changes [ ] Bug fix (non-breaking change which fixes an issue) [ ] New feature (non-breaking change which adds functionality) [ ] Breaking change (fix or feature that would cause existing functionality to change) [x] Documentation update Checklist [x] I have read the MCP Documentation [x] My code follows the repository's style guidelines [x] New and existing tests pass locally [x] I have added appropriate error handling [x] I have added or updated documentation as needed Additional context Four findings that seem worth other implementers' time. 1. "Where a skill came from" is written down in more than one place. VS Code encodes it in four: a storage enum, a parallel string union, an ext-host protocol DTO, and a proposed extension API type. All four must agree. I updated two and missed two — which produced a runtime crash that broke chat entirely, while stayed perfectly green. Budget for more than a one-line enum change. 2. A server doesn't have to list its skills, and it's easy to forget. The SEP makes enumeration optional: a skill is readable by URL whether or not it appears in any index. A client that only reads will silently see nothing on a server that doesn't publish one. Try both the index and , and never read "index missing or empty" as "this server has no skills." 3. Skill names are one global namespace, and the SEP doesn't say who wins a clash. If a local skill and an MCP skill are both called , one disappears. Same if two connected servers both serve . The SEP ties a skill's URL to its name but says nothing about precedence, so every host invents its own rule. I chose local-over-MCP — a server shouldn't be able to shadow a skill on your disk — but server-vs-server ends up as whatever order discovery happened to run in. This seems worth stating explicitly in the SEP. 4. Re-running discovery on every context computation is an accidental DoS. runs each time the model's context is rebuilt, and discovery costs two round trips per server. A naive version issued 20 index reads for a single chat turn. That's the same shape as the incident behind hf-mcp-server's client denylist (#164, ~100k req/min). Cache the promise, not just the result, and key it on connection state — keying on server id alone pins an empty result from a lookup made while the server was stopped.