modelcontextprotocol/ext-skills
Watch
1
0
Fork
You've already forked ext-skills
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clean and and re-organize repo docs (#146)

Browse source 
* docs: point README and AGENTS.md at the released spec and official docs

SEP-2640 is Final and the extension ships from specification/stable/skills.mdx,
so the README now leads with a Specification section linking the spec file,
the official docs page (modelcontextprotocol.io/extensions/skills/overview),
the published SEP, and the client matrix. The experimental banner is replaced
with a note that docs/ holds working documents; the charter, pulls, and issues
links move off the redirecting experimental-ext-skills / charter URLs.

AGENTS.md no longer names the SEP PR as the source of truth; it points agents
at the stable spec page and describes the decision-log flow against that file.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: accepted spec changes land in a draft revision, not the stable file

The stable specification is a released snapshot. README and AGENTS.md now say
accepted decision-log proposals go into a draft revision that ships as a new
release, matching the ext-tasks specification layout.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: move pre-release design documents to docs/archive

SEP-2640 is Final, so docs/ now holds only living working documents. Eight
historical documents move to docs/archive with an index explaining what each
was and what superseded it: the SEP baseline copy, why-and-when, use-cases,
approaches, skill-uri-scheme, glossary, client-mcp-support (superseded by the
official client matrix), and agent-plugins-analysis.

Files the published SEP links to by path (decisions, experimental-findings,
open-questions, problem-statement, rationale, related-work, skill-meta-keys)
stay in place so those links keep working. Cross-links are rewritten and
verified; the README contents table is trimmed to match.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: archive open-questions and skill-meta-keys

Both are pre-release documents whose outcomes live in the decision log and
the specification. The published SEP links to them by path; a companion
change in modelcontextprotocol/modelcontextprotocol repoints those links.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: fix sibling links inside archived open-questions and skill-meta-keys

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: keep only the decision log and rationale in docs/

threat-model, experimental-findings, findings-template, problem-statement,
and related-work move to docs/archive with index rows. The candidates
tracker and the archived client-support survey are removed in favor of the
official extension client matrix, and links to them are repointed there.

README drops the Why and Problem Statement sections, which duplicate the
SEP's Motivation and the official overview page. CONTRIBUTING routes new
implementation findings to GitHub issues.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: fix sibling links inside newly archived documents

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add a concise implementations list

One table each for servers/SDKs and hosts, one line per entry, replacing the
retired candidates tracker and the related-work implementation tables. Seeded
from those plus PR #141 and issue #144.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: put tracking links in the Status column of the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add a vendor/community category to the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: replace the interim reference package with the TypeScript SDK row

The @olaservo/ext-skills package is retired in favor of first-class skills
APIs in the TypeScript SDK (typescript-sdk#2798, phase 1 in #2818). The
archived related-work page now points at implementations.md for current
information.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: drop pre-SEP rows from the implementations list

They are already recorded in the archived related-work page; the list now
points there instead. FastMCP stays because its row tracks the migration to v1.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add official SDK progress, Tachyon, and Inspector 2.6.0 to implementations

From the WG Discord channel and the SDK repos as of 2026-09-15: Go, TypeScript,
Python, and C# SDKs all have open SEP-2640 PRs (Go passes conformance); the
conformance suite merged; Inspector 2.6.0 shipped skills verification; Tachyon
reports a server implementation. Adds an "in progress" status for open PRs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: track Goose host support via the official issue

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: only tag community rows in the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: tag MCP-project rows as official in the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: split the implementations list into SDKs, servers, and hosts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add MCPJam Inspector to hosts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Revise implementations table format and content

Updated the implementations table to include language and status columns.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Correct links and clarify documentation references

Updated links to SEP-2640 and clarified document references.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Sambhav Kothari <sambhavs.email@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Ola Hungerford 2026-09-15 21:56:20 -07:00 • committed by GitHub
commit 5adfff5952
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 115 additions and 305 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/rationale.md
View file

@ -56,7 +56,7 @@ The virtual-filesystem model this SEP builds on had a read operation (`resources
`resources/directory/read` is the readdir analog: scoped, paginated, and composable — listings mark subdirectories with `inode/directory`, so an agent descends a skill's tree exactly as it would walk a directory locally.
Two alternatives were considered. Extending `resources/list` with a scope parameter would change a core method's semantics from inside an extension, and a URI-prefix filter misstates the model anyway — prefixes are string matching, not structure. Embedding a file manifest in `SKILL.md` or the listing was rejected as the navigation mechanism: it would freeze the listing at authoring or publication time and bloat context for skills with many files, while a method keeps listings live and on demand. The `resources` enumeration ([Resources](sep-draft-skills-extension.md#resources)) is not that manifest — it is an integrity commitment consumed by the host at verification and approval time, with no need to occupy model context, and the dynamically generated skills that need live listings most are exactly the ones that carry `"dynamic"` in its place.
Two alternatives were considered. Extending `resources/list` with a scope parameter would change a core method's semantics from inside an extension, and a URI-prefix filter misstates the model anyway — prefixes are string matching, not structure. Embedding a file manifest in `SKILL.md` or the listing was rejected as the navigation mechanism: it would freeze the listing at authoring or publication time and bloat context for skills with many files, while a method keeps listings live and on demand. The `resources` enumeration ([Resources](archive/sep-draft-skills-extension.md#resources)) is not that manifest — it is an integrity commitment consumed by the host at verification and approval time, with no need to occupy model context, and the dynamically generated skills that need live listings most are exactly the ones that carry `"dynamic"` in its place.
Although introduced by this extension, the method is deliberately general — any directory resource qualifies, under any scheme — making it a candidate for promotion into the core Resources primitive if usage warrants.
@ -68,18 +68,18 @@ The listing could instead carry a curated subset of skill metadata — `name` an
An earlier revision carried one digest per entry, covering only `SKILL.md`. That left every supporting file unbound: a server could obtain approval for a benign skill, then rotate `references/GUIDE.md` — instructional content the model follows as readily as the skill body — while the approved digest stayed valid. Persisted approval covered the one file a user is least likely to be attacked through.
Enumerating every file covers both rotation and addition: the set is complete, so a new file is as detectable as a changed one. It also supports pinning — approval binds to the whole set, and each file is verified against it when read. That gives the consistency half of the atomic-snapshot property archive distribution ([Appendix: Deferred Features](sep-draft-skills-extension.md#appendix-deferred-features)) offered: a host can never unknowingly mix files from two versions. Unlike an archive it requires no unpacking surface, and no file is retrieved ahead of need ([Integrity and verification](sep-draft-skills-extension.md#integrity-and-verification)). The cost falls on dynamically generated skills, which cannot publish stable digests; they carry `"resources": "dynamic"` instead, and accept that hosts may decline them.
Enumerating every file covers both rotation and addition: the set is complete, so a new file is as detectable as a changed one. It also supports pinning — approval binds to the whole set, and each file is verified against it when read. That gives the consistency half of the atomic-snapshot property archive distribution ([Appendix: Deferred Features](archive/sep-draft-skills-extension.md#appendix-deferred-features)) offered: a host can never unknowingly mix files from two versions. Unlike an archive it requires no unpacking surface, and no file is retrieved ahead of need ([Integrity and verification](archive/sep-draft-skills-extension.md#integrity-and-verification)). The cost falls on dynamically generated skills, which cannot publish stable digests; they carry `"resources": "dynamic"` instead, and accept that hosts may decline them.
## Why Does an Enclosing Skill's Manifest Include Its Nested Skills?
An earlier revision treated a nested `SKILL.md` as a boundary: a host walking an enclosing skill stopped there rather than taking in the subtree. The shipped model treats a nested skill's files as ordinary supporting files of the enclosing skill, so they appear in both manifests ([Resources](sep-draft-skills-extension.md#resources)).
An earlier revision treated a nested `SKILL.md` as a boundary: a host walking an enclosing skill stopped there rather than taking in the subtree. The shipped model treats a nested skill's files as ordinary supporting files of the enclosing skill, so they appear in both manifests ([Resources](archive/sep-draft-skills-extension.md#resources)).
Content-bound approval binds to the `resources` set, so the set has to cover every file the skill can introduce into model context. A boundary would leave gaps in it at paths the server controls, and content in a gap could change without changing the approved set. The cost is that changing one nested skill revokes the persisted approval of every skill whose manifest encloses it.
Approval remains per skill. An enclosing skill's approval covers reading a nested `SKILL.md` as ordinary content, never activating it ([Nested skills](sep-draft-skills-extension.md#nested-skills)) — so a host does not need to detect nesting to apply the consent rule, and nothing in a listing marks the relationship.
Approval remains per skill. An enclosing skill's approval covers reading a nested `SKILL.md` as ordinary content, never activating it ([Nested skills](archive/sep-draft-skills-extension.md#nested-skills)) — so a host does not need to detect nesting to apply the consent rule, and nothing in a listing marks the relationship.
## Why Retrieve Files Only When They Are Needed?
An earlier revision let a host fetch, verify, and cache a skill's entire `resources` set at approval time and serve every later read from that copy. That is now prohibited: no file is retrieved on connection, on listing, or at approval. `SKILL.md` is fetched when the skill is loaded and a supporting file when it is read ([Integrity and verification](sep-draft-skills-extension.md#integrity-and-verification)).
An earlier revision let a host fetch, verify, and cache a skill's entire `resources` set at approval time and serve every later read from that copy. That is now prohibited: no file is retrieved on connection, on listing, or at approval. `SKILL.md` is fetched when the skill is loaded and a supporting file when it is read ([Integrity and verification](archive/sep-draft-skills-extension.md#integrity-and-verification)).
One reason for this is server load. A listing may be arbitrarily large — these are the same catalogs that make an empty or partial `skills/list` legitimate ([Why May the Listing Be Empty or Partial?](#why-may-the-listing-be-empty-or-partial)) — and a single portable skill can run to 512 files and 16 MiB ([Limits](sep-draft-skills-extension.md#limits)). A host that staged every skill it might use would put load on a server proportional to the catalog rather than to what a session reads, and every connecting host would repeat it. The same argument bounds the cost of deferring archives: a round trip per file scales with the files a session opens, not with the size of the skill.
One reason for this is server load. A listing may be arbitrarily large — these are the same catalogs that make an empty or partial `skills/list` legitimate ([Why May the Listing Be Empty or Partial?](#why-may-the-listing-be-empty-or-partial)) — and a single portable skill can run to 512 files and 16 MiB ([Limits](archive/sep-draft-skills-extension.md#limits)). A host that staged every skill it might use would put load on a server proportional to the catalog rather than to what a session reads, and every connecting host would repeat it. The same argument bounds the cost of deferring archives: a round trip per file scales with the files a session opens, not with the size of the skill.