This pull request makes a small update to the `.github/CODEOWNERS` file,
changing the default code owners group to reflect the correct team
assignment.
Publish the Skills extension as a browsable VitePress site on Cloudflare
Pages, using the same documentation theme as ext-tasks and reusing the
existing source documents.
- Follow the Tasks site's structure: a substantive overview at `/` and a
separate stable specification page. The small `index.md` uses native
VitePress includes to reuse excerpts from the released specification,
rather than duplicating its prose.
- Link to the condensed overview on the MCP website.
- Render `specification/stable/skills.mdx` through a small Markdown
include, preserving the released specification unchanged.
- Add local search, section outlines, MCP branding, source edit links,
and a Specification navigation item with a Stable sidebar entry. Keep
the full specification at `/specification/stable/skills`.
- Build pull requests, including fork contributions, in read-only GitHub
Actions CI.
- Use the existing Cloudflare Pages Git integration for publishing.
Remove the GitHub Pages deployment workflow and project-path
configuration.
## Validation
- `npm run docs:build` passed with VitePress 1.6.4.
- Checked that the build emits an overview and a separate specification
page; verified included excerpt boundaries, internal links and anchors,
specification source edit links, and the rendered MDX callout.
- `git diff --check` passed.
- The build emits the existing large-chunk warning from the diagram
dependencies.
- Cloudflare deployment itself has not been run from this workspace.
## Publishing settings
DNS and Cloudflare Pages setup are ready separately. The existing Pages
project should use:
| Setting | Value |
| --- | --- |
| Repository | `modelcontextprotocol/ext-skills` |
| Production branch | `main` |
| Root directory | Repository root |
| Build command | `npm run docs:build` |
| Build output directory | `.vitepress/dist` |
| Node.js | `22` (set `NODE_VERSION=22` in Pages) |
| Custom domain | `skills.extensions.modelcontextprotocol.io` |
Cloudflare installs dependencies and builds from the committed npm
lockfile. The site is served at the domain root with clean URLs.
Publishing is handled by Cloudflare's connected Git integration; no
GitHub Pages environment, Pages permissions, or Cloudflare deployment
secrets in GitHub Actions are required.
After merge, verify the production deployment and custom domain in the
existing Cloudflare Pages project. One-time publishing instructions stay
in this PR description, not in a checked-in setup document.
Fork PRs receive the CI build check. Automated Cloudflare previews for
forks require the separately discussed trusted artifact-publishing
workflow; this PR does not add that workflow.
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
The stable Skills page missed the final SEP's Agent Skills compatibility
clause, and its examples used abbreviated hashes and inconsistent byte
sizes. Archived drafts also retained current-sounding source-of-truth
guidance.
This corrects the stable page directly to match already-established
requirements: restores the compatibility clause, shows the resources
capability and server/discover, explains omitted request metadata, and
makes the example manifests and content consistent. It also labels
archived documents as historical and fixes the SEP domain in AGENTS.md.
This is an editorial alignment, not a new extension proposal; #142
remains separate.
Validation: all JSON examples parsed; all 13 manifest entries checked
against sample bytes for SHA-256 and size; the corrected specification
builds with the VitePress publishing site; git diff --check passed.
AI assistance: prepared with Codex.
* Initial plan
* docs: ratify three Proposed decision log entries to Accepted
Co-authored-by: olaservo <16480113+olaservo@users.noreply.github.com>
* docs: mark the 2026-09-08 stable-spec decision Accepted
Its text already shipped in specification/stable/skills.mdx via PR #139, so
the entry joins the three v1 entries this PR ratifies.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: olaservo <16480113+olaservo@users.noreply.github.com>
Co-authored-by: Ola Hungerford <olahungerford@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Mirrors the policy used in modelcontextprotocol/ext-tasks: defers to the
main MCP security policy and directs reports to GitHub Security Advisories.
Claude-Session: https://claude.ai/code/session_01Sure6Sknngow87Q6TkzTfL
Co-authored-by: Claude <noreply@anthropic.com>
* 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>
* Add specification/stable/skills.mdx for SEP-2640
Spec-format rendering of the Skills extension (io.modelcontextprotocol/skills),
following the layout used by ext-tasks' specification/draft/tasks.md.
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sure6Sknngow87Q6TkzTfL
* skills.mdx: list normative requirements as bullets
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sure6Sknngow87Q6TkzTfL
* skills.mdx: plain punctuation, drop em-dashes and rhetorical phrasing
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sure6Sknngow87Q6TkzTfL
* skills.mdx: remove Implementation Considerations section
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sure6Sknngow87Q6TkzTfL
---------
Co-authored-by: Claude <noreply@anthropic.com>
* docs: add combined skills glossary
Adds docs/glossary.md with working definitions for Skills Over MCP
terminology, addressing #51. Combines the strongest definitions from
three open glossary PRs (#103, #101, #93):
- Core terms covering all 10 terms requested in #51 (skill, instruction,
primitive, resource, convention, context, progressive disclosure,
control model, first-class primitive, server/skill author, discovery),
with Agent Skills alignment/divergence noted where relevant.
- Distribution and ecosystem terms (skill resource, skill:// URI, skill
metadata, server-skill pairing, multi-server composition, ephemeral
availability, provenance).
- Cross-referenced from the README documents table.
Co-authored-by: kiku-jw <25382531+kiku-jw@users.noreply.github.com>
Co-authored-by: luohui1 <187920557+luohui1@users.noreply.github.com>
Co-authored-by: EfeDurmaz16 <75971010+EfeDurmaz16@users.noreply.github.com>
* docs: align glossary with latest SEP-2640 and decision log
Reconcile the combined glossary against the current SEP-2640 text and
the Working Group decision log:
- First-class primitive: reflect that the WG considered and declined a
skills/list method (2026-06-05), keeping skills as Resources, rather
than framing it as a still-open option.
- Add Skill index (skill://index.json), Archive, and Directory listing
(resources/directory/read) terms — settled spec concepts that were
missing (decisions 2026-04-19, 2026-06-05, 2026-06-09).
- Skill metadata: ground in SKILL.md frontmatter and note _meta is
reserved for transport-specific keys under io.modelcontextprotocol.skills/
(decision 2026-03-16); index copies frontmatter verbatim.
- Provenance: note the WG treats it as a distribution/plugin-layer
concern, not standardized skill metadata (decision 2026-03-16).
- References: add SEP-2640 and the Decision Log.
* docs: incorporate June 16 WG meeting clarifications
From the 2026-06-16 Skills Over MCP WG meeting notes (postdates the
decision log):
- Skill metadata: distinguish the two reserved namespaces — the
io.modelcontextprotocol/ prefix inside the frontmatter metadata block
vs. the io.modelcontextprotocol.skills/ prefix on resource _meta.
- Add Compatibility term: the frontmatter compatibility field is
free-text and LLM-evaluated (not a deterministic gate); hosts screen
execution-requiring skills by convention, and the WG holds that
execution/environment signaling belongs in the Agent Skills spec.
* docs: update glossary terms to SEP-2640 v1 (skills/list, skills/get, digests; archives removed)
---------
Co-authored-by: kiku-jw <25382531+kiku-jw@users.noreply.github.com>
Co-authored-by: luohui1 <187920557+luohui1@users.noreply.github.com>
Co-authored-by: EfeDurmaz16 <75971010+EfeDurmaz16@users.noreply.github.com>
* Add standalone prototype for issue #66 (skill:// discovery/loading)
Builds a from-scratch MCP server + client per the merged SEP-2640 draft
(resources + skill://index.json, no custom methods), exercising flat and
nested skill paths, relative sub-resource references, and the
"enumeration is optional but direct read must still work" baseline.
Findings recorded in docs/experimental-findings.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Trim prototype to essentials
Inline the four skill fixture files into server.mjs (the prototype
demonstrates the transport binding, not filesystem loading) and drop the
prototype README, whose content is already in the PR description.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Add findings from VS Code SEP-2640 skill discovery implementation
Records what implementing skill:// discovery in VS Code proper surfaced:
the client already had the full progressive-disclosure loop and only
lacked an MCP source, its mcp-resource:// FS provider means the loading
half needs no code at all, and a new skill source touches more type
surfaces than expected.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Drop prototype code; keep findings only
experimental-ext-skills is a working-group docs repo, so a runnable
Node server/client pair did not belong in it. The actual client-side
implementation for issue #66 now lives in VS Code, and what belongs
here is the write-up of what that surfaced.
Folds the still-transferable observations from the removed prototype
(URI- vs metadata-based identification per #54, and the index digest
doc inconsistency) into the VS Code findings entry.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Add findings from running the VS Code integration against a live server
Records what surfaced once the implementation was run from a source
build against the Hugging Face MCP server, rather than only
type-checked: the index wire format had already moved past the
checked-in draft, per-context-computation discovery is an easy
accidental DoS, a new skill source touches four type surfaces that must
agree, and cross-server name collisions are unspecified by the SEP.
None of the three defects were caught by tsc or the unit tests.
Also corrects the previous entry, which said the work was not verified
against a running server — it now is, for discovery. Model invocation
remains undemonstrated and is called out as such.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Tighten the issue #66 findings entry
Cut ~half the words to match the length of neighbouring entries and
make it reviewable at a glance. Same findings, less prose.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Link the findings entry to the VS Code implementation PR
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Restore the #54 identification note and reframe the digest point
Issue #66 asks explicitly for a URI- vs metadata-based identification
evaluation, so that belongs in the entry. The digest note is reframed
from a doc nitpick into the actionable version: the live server sends a
digest and this client ignores it, so nothing verifies skill integrity.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: note VS Code findings were written against the pre-v1 draft
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: olaservo <olahungerford@gmail.com>
* docs(findings): add PHP MCP SDK + Symfony AI Mate skills-as-resources entry
First PHP-ecosystem implementation of SEP-2640: php-sdk#372 serves a
directory of SKILL.md files as skill:// resources, symfony/ai#2132 ships
the skill content in the Mate MCP server. Records what was verified
(serving via MCP Inspector snapshots), the spec-text frictions hit
(_meta namespace, resource name charset, empty-payload serialization),
and the Claude Code consumption gap.
* docs(findings): reframe _meta and resource-name notes per SEP-2640 review
The SEP PR specifies the io.modelcontextprotocol.skills/ _meta prefix
(our SDK independently converged on it); the resource-name point is an
SDK registration-uniqueness detail, not a spec gap. Reframe both and
note the PR-vs-repo-draft drift on the _meta sentence.
* docs: note PHP SDK findings were written against the pre-v1 draft
---------
Co-authored-by: olaservo <olahungerford@gmail.com>
* docs: add skills-extension-candidates tracker
Scaffold a candidates list for MCP servers, dev tools, SDKs, and
skills repositories that could adopt SEP-2640. Initial entries:
FastMCP 3.0 Skills, chrome-devtools-mcp, hf-mcp-server, Hugging Face
skills library, github-mcp-server (PR #2428 demo), Azure Skills Plugin.
Cross-link from related-work.md and add a row to the README docs
table.
* docs: add Issue/PR tracker column to candidates table
* docs: add client-mcp-support survey alongside candidates tracker
* docs: link Azure MCP Server source in candidates table
* docs: remove gemini-cli from client MCP support survey
* docs: verify hermes-agent, switch source refs to main-branch links, refresh takeaways
- Promote hermes-agent from first-pass to verified; note its per-server tool
pattern (`mcp_{server}_read_resource` + `mcp_{server}_list_resources`) and
confirm end-user docs exist
- Drop stale line numbers throughout; convert path refs to GitHub source-file
links on `main` (commit-pinned URLs decayed once files moved)
- Goose: PR #8989 has landed, so describe current `(extension_name, uri)`
required signature and drop the now-closed issue/PR tracking
- Takeaways: collapse to three implementation patterns (Goose now fits the
`(server, uri)` bucket), fix open-source count to fourteen, drop the
smolagents name-drop (not in survey), add strands-agents alongside mastra
for the internal-SDK-only pattern, and reframe the signature recommendation
around server-resolution reliability rather than URI portability
* docs: verify remaining first-pass clients, flip cline/Roo-Code to Yes
Verified adk-python, agent-framework, crewAI, mastra, cline, Roo-Code
against local source clones. Two corrections to prior state:
- cline and Roo-Code both expose access_mcp_resource(server, uri) as a
model-facing tool via McpHub.readResource. Flipped from No to Yes.
- adk-python's load_mcp_resource takes resource_names: array[string] in
a single call (not two-shot); opt-in via use_mcp_resources flag.
Headline count updated from six to eight of fourteen open-source clients
satisfying #2527. Cross-cutting observations and takeaways adjusted for
the new (server, uri) family members and the four-pattern signature
breakdown. Trust-model list extended.
* docs: add Figma and Adobe MCP as SEP-2640 testing candidates
* docs: update FastMCP 3.0 Skills entry with detailed notes on SEP-2640 compliance
* docs: drop unconfirmed Cursor SEP-2640 entry, track latest SEP-2640 wire-contract PRs
Remove the Cursor row + deep dive (reported WIP never confirmed). Add the
in-flight PRs realigning to the 2026-06-05/06-09 SEP-2640 schema (frontmatter +
archives[] index, resources/directory/read): hf-mcp-server#174, fast-agent#825,
huggingface/skills#172.
* docs: add Slack (interested) and Bloomberg (internal use) as SEP-2640 candidates
* docs: remove archived Roo-Code from client survey, update strands repo to harness-sdk
* docs: re-verify SEP-2640 implementations against current upstream main
Both reference implementations have migrated to the July 2026 v1 shape,
verified against fresh clones rather than the prior June commit pins:
- hf-mcp-server (d794b10, v0.4.6): skills/list + skills/get, per-file
{uri,digest} resources manifest, directoryRead:true, no index.json or
archives. Migrated in #219 (merged 2026-08-03). Also records the
snapshot/TTL model and HTTP-transport-only constraint.
- fast-agent (79b903c, 0.10.1): pins SEP-2640 revision d7490ec, treats
legacy index.json skill-md/archive entries as unsupported. Requires
--prerelease=allow (pins fastmcp-slim 4.0.0b1), per @evalstate.
Corrects the earlier note claiming implementations lagged the SEP: the
#174/#825/#172 round merged 2026-06-19 and was never in flight, and a
second realignment followed the v1 rework.
Also fixes drift found while re-checking fast-agent's resource tool:
smart_agent.py is gone (now core/harness_tools.py), get_resource is
opt-in via harness_tools (default False, was unconditional), and
server_name is now optional - the one surveyed client where the model
may omit server identity.
Runtime skill loading is still unshipped; #816 remains open.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: track SEP revision 0eb05fe and add mcpkit to the candidates tracker
The SEP moved from d7490ec to 0eb05fe (2026-08-05). The delta is
editorial for the wire contract -- skills/list, skills/get, and the
per-file resources manifest are unchanged -- so d7490ec-pinned
implementations stay compatible. Records what it does change: a soft
reg-name constraint on the first skill-path segment, the skill root URI
fixed as skill://<skill-path> with no trailing slash, whether skills/get
carries ttlMs/cacheScope reopened, and normative host obligations in the
security section.
Adds mcpkit (panyam/mcpkit, Go, v0.3.0) from #118 as a candidate. It
implements the pre-v1 index.json catalog shape with per-file digests, so
the ecosystem is now split across draft revisions rather than uniformly
caught up.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: refine mcpkit entry — deliberate tracking, partial v1 migration
Checked mcpkit's issues and PRs rather than inferring alignment from
code shape. Its lag is a tracked decision, not drift:
- #1185 (merged 2026-08-04) implements origin-tagging and per-origin
resolve citing SEP L179/L183/L185 -- the host obligations 0eb05fe made
normative -- so it is already on v1 for the security section. #1187
adds a SEP-2640 security/conformance harness as a WG demo.
- #780 is an explicit index-schema tracking issue that has absorbed the
archives removal and the resources:[{uri,digest}] direction but waits
on WG confirmation; its conformance fork pins provenance at 556154c.
- The carrier change is still unbooked: nothing references skills/list
or skills/get.
- Archives are kept as a non-spec extended surface rather than deleted,
unlike fast-agent -- a counter-case for whether deferring a feature
removes it from the ecosystem.
Sharpens the callout accordingly: the draft split runs within an
implementation, not only between them, so "which draft does X
implement" often has no single answer.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: sync SEP copy with upstream commit b405ba5
Re-syncs docs/sep-draft-skills-extension.md from the canonical
sep/skills-extension branch (twelve commits, 2026-08-11 to 2026-08-21)
and updates the pinned commit reference in the header.
Most of the removed lines are the Rationale section, which upstream
replaced with a pointer to docs/rationale.md in this repo. That text is
not lost, it now lives in one place instead of two.
The rest: per-skill limits and a `size` field, an explicit "dynamic"
marker in place of the omit-`resources` rule, (server, URI) as a skill's
identity, on-demand retrieval with write-isolated caches, the window in
which a host is acting on a skill, and `resultType` on every sample
result.
* docs: update rationale for the SEP sync
Three passages said dynamically generated skills omit `resources`, which
is no longer valid, and the per-file-digests section offered "cache the
whole set at approval time" as the pinning primitive, which the SEP now
forbids.
Adds a section on why an enclosing skill's manifest includes its nested
skills, recording the answer given on the concerns doc: content-bound
approval binds to the `resources` set, so the set has to be complete.
* docs: re-sync SEP copy to upstream commit 753b9f2
Picks up the table reformatting from 753b9f2 and updates the pinned
commit in the file header. No specification text changed between
b405ba5 and 753b9f2.
* docs: record why hosts retrieve skill files on demand
The SEP prohibits fetching a skill's files ahead of need but explains
it in one sentence, and the reasoning for the cache-integrity rule that
accompanies it is only in the upstream commit messages.
Add a rationale section covering the server-load argument, why lazy
retrieval leaves content-bound approval intact, and what it gives up
relative to staging the whole resources set at approval time.
* docs: tighten the on-demand retrieval rationale
Merges the two paragraphs that both argued late retrieval is still safe,
and drops the restatement of the cache mechanics -- write-isolation,
re-hashing on access, digest labels not counting as verification -- which
Security Implications owns. The rationale needs the shape of the trade,
not a second copy of the rules.
Also corrects the limits sentence. 512 files and 16 MiB are host-support
floors, not a cap on what a server may serve: a skill above them is not
invalid, it just loses guaranteed portability.
Drops the threat-model link. The rotation point it supported is correct,
but the document still names `install` its recommended baseline and
argues for immutability on the grounds that there is "no second live read
to diverge" -- the model this section prohibits. Restore the link after
the threat model is revised.
* docs: trim the on-demand retrieval rationale
Server load is one reason for retrieving late, not the only one. The paragraph on what late retrieval gives up restated verification rules the spec already carries.
* docs: add skill-set to related work
Adds skill-set under Specifications and Standards as related work for deterministic whole-skill and set-level hashing, receipt-time verification, and out-of-band content pins.
* docs: add integrity and verification section
Move skill-set from Specifications and Standards into a new resource integrity and verification section.
Re-syncs docs/sep-draft-skills-extension.md from the canonical
sep/skills-extension branch (Apply suggestions from code review,
2026-08-05) and updates the pinned commit reference in the header.
* docs: sync repo SEP copy with canonical v1 text
The repo-local copy of SEP-2640 had drifted well behind the canonical
text on the sep/skills-extension branch, which was a source of
confusion: it still specified the well-known skill://index.json
resource and predated skills/list, skills/get,
resources/directory/read, nested skills, and per-file digests.
Replace the body with a verbatim copy of the canonical SEP as of
d7490ec (2026-07-15) and swap the stale "not actively maintained"
notice for a disclaimer that states what this file now is: a synced
snapshot, re-synced by overwriting rather than hand-editing, with
review on the upstream PR and anything beyond v1 raised as a PR in
this repository.
Also drop "working draft" from the README and related-work references
to this file, since it is no longer where the text is drafted.
* docs: frame the SEP copy as the v1 baseline for decision-log proposals
The previous note told readers not to propose changes here at all, which
is the wrong instruction: the WG does want to propose beyond v1, just in
this repo rather than on the upstream SEP.
Reframe the file as the v1 baseline and route proposals through the
existing decision log rather than a parallel mechanism. decisions.md
already carries the ADR-lite format, the Proposed/Accepted/Superseded
status idiom, and the precedent for consolidating a version's scope into
one record (the 2026-07-16 v1 entry), so a change beyond v1 is simply the
next dated entry. The note also defines the marker that ties an amended
section back to its record, so v1 text stays distinguishable from
accepted deltas as the document accumulates them.
Align the README and related-work references to the same framing.
* docs: mark the 2026-04-16 URI decision superseded in part
Every other decision the v1 scope-down changed carries a forward pointer
in its status line (2026-04-19, 2026-06-02, 2026-06-05, 2026-06-09). The
2026-04-16 URI entry was left as plain Accepted while three of its
bullets no longer hold, so it reads as current guidance for index.json
enumeration and the no-nesting rule.
Give it the same treatment, naming which bullets changed and which parts
of the URI convention carry forward, so the entry stays useful as a
record of the structure it settled.
* docs: add AGENTS.md and make the SEP PR link prominent
Readers were landing on the repo-local SEP copy and taking it for the
spec, which is how the stale version misled people in the first place.
Say plainly, in the places they land, that the v1 spec text lives on
modelcontextprotocol#2640:
- README: a source-of-truth line at the top of the link block, above
the charter.
- The baseline copy: lead the header note with the PR rather than
mentioning it mid-paragraph.
- AGENTS.md: state the rule for agents working in this repo, along with
how to propose beyond v1 via the decision log and the repo's markdown
conventions.
CLAUDE.md is a one-line pointer to AGENTS.md rather than a symlink, so
it resolves on Windows checkouts too, where symlinks need Developer Mode
and would otherwise land as a stub.
* docs: use the @AGENTS.md import in CLAUDE.md
A markdown link is not an import — Claude Code would have loaded the
pointer line and never expanded AGENTS.md into context. The documented
syntax is @path, which the docs specifically recommend over a symlink
on Windows, where symlinks need Administrator privileges or Developer
Mode.
The maintainer note is a block-level HTML comment, which Claude Code
strips before injecting the file, so it costs no context while staying
visible to anyone opening the file.
https://code.claude.com/docs/en/memory#agents-md
* docs: tighten AGENTS.md to the source-of-truth rule
Cut the project overview and conventions sections and lead with what an
agent most needs to get right: the v1 spec text is on the PR, and the
copy here is only as current as its pinned commit. CONTRIBUTING.md
already covers participation and process.
* docs: add threat model for skills over MCP (SEP-2640)
Add docs/threat-model.md covering the delivery and host-handling layer
for skills served over MCP. Recommends the install (materialize to a
host-private, immutable store) path as the baseline over load-on-demand,
enumerates non-archive threats (T1-T7) with a full per-fixture mapping to
the dangerous-skills-mcp corpus and to SEP-2640 clauses, folds in the
mcpkit reference-implementation findings, and keeps the archive threat
model as an appendix (archives are slated for removal from this version).
Index the new doc in the README repository-contents table.
🦉 Generated with Claude Code
* docs: refine threat model by removing out-of-scope content and clarifying core boundaries
* docs: reconcile threat model with current SEP-2640 revision
Update the threat model to track the canonical sep/skills-extension
revision instead of the stale local working draft, and address review
feedback on PR #108.
- Retire skill://index.json terminology in favor of skills/list +
skills/get and the per-file `resources` digest set.
- Mark the B1 supporting-file-digest gap closed: `resources` now
enumerates every file with a digest and unlisted reads are
verification failures. Flip adv-supporting-file-digest-swap status.
- Reframe archives as a deferred feature (SEP Appendix: Deferred
Features); mark archive fixtures Deferred and `refunds` Resolved
(skills are keyed by uri, not name).
- Add T8 cross-origin name-collision impersonation, T9 nested-skill
consent, and a directory-walk subtree-escape row under T5, each
flagged as not yet exercised by the corpus.
- Add a Scope note on skill-catalog metadata confidentiality.
- Add the missing "Residual gaps and future directions" section
(previously referenced but absent), covering the unsigned-digest
trust-anchor gap and the third-party attestation direction.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: add discovery-surface grounding and enumeration-exhaustion threat
- Add a "Protocol surface" paragraph to the system model naming
skills/list, skills/get, and resources/directory/read and what each
exposes, so threats can reference them against a stated baseline.
- Add enumeration/pagination exhaustion to T6: a server returning an
unbounded skills/list or resources/directory/read stream via an
endless nextCursor exhausts the host at discovery time, before any
file is fetched. SEP bounds neither page nor entry count; flagged as
no corpus fixture yet. Reflected in the fixture map and residual gaps.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: copy-edit threat model to reduce em-dash and antithesis density
Style-only pass over prose I wrote. No change to any technical claim,
normative keyword, fixture reference, or table. Thins the em-dash habit
(convert appositive/dramatic dashes to periods, commas, or parens) and
de-duplicates the "X, not Y" closer, keeping only the load-bearing
contrasts. Definition-list and reference-list dashes left as-is.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: record SEP-2640 v1 scope-down and skills/get as decision records
Consolidates the July 2026 rework of SEP-2640 (post June 24 CM deferral
and June 30 WG scoping decision) into a single ADR for group review:
archives removed, skills/list replacing skill://index.json, per-file
resources manifest, optional directory read, non-privileged schemes,
name-collision handling, and nested-skill consent gating.
Adds a separate ADR for the skills/get method proposed by @aditya-scio
in SEP review, and updates the status lines of the four prior entries
this rework supersedes or amends (2026-04-19, 2026-06-02, 2026-06-05,
2026-06-09).
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: add Discord design-thread references to v1 scope-down ADR
Links Peter's July 8 change announcement, the supporting-file digests
thread (the design discussion behind the per-file resources manifest),
and Sambhav's June 24 method-family sketch that prefigured skills/list
and skills/get.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
* docs: refine context and rationale for skills/get method in SEP-2640 decision
* docs: link Sam Morrow's Progressive Discovery in MCP (Part 2)
* docs: link Angie Jones's "Skills Over MCP" article
* docs: mark open-questions and experimental-findings as not actively maintained
* docs: soften approaches doc and mark SEP working draft as not actively maintained
Records the 2026-06-09 decision (SEP-2640) to add a dedicated
resources/directory/read method for listing directory-like resource
children, identified by the inode/directory mimeType and returning a
paginated, metadata-only Resource list. Captures the rejected
alternatives (overloading resources/read by mimeType; adding a uri
param to resources/list) and the rationale for a dedicated verb.
Status: Proposed.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The working draft's Resource Metadata section omitted the sentence
recommending the io.modelcontextprotocol.skills/ prefix for _meta keys,
which is present in the submitted SEP-2640. Bring the repo-local copy
back in line with the PR.
* docs: add ADR for filesystem as host-side implementation detail
Record the proposed decision that skills served over MCP MUST function
without a local filesystem, while hosts MAY materialize resources as an
optimization, with unified resolution semantics required either way.
* docs: link companion archive distribution ADR (#83)
* docs: update ADR date to 2026-04-19
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: olaservo <16480113+olaservo@users.noreply.github.com>
* docs: add decision record for archive distribution type
Formalizes the April 18 decision to permit type: "archive" entries in
skill://index.json as a server-side packaging optimization, reinstating
symmetry with the Agent Skills discovery RFC.
* docs: correct decision record date to 2026-04-19
* docs: add permissions/symlinks motivation and issue #61 reference
The links pointed to anthropic-quickstarts, but the project lives at
github.com/ChromeDevTools/chrome-devtools-mcp. Also corrects the author
attribution from Anthropic to Google (ChromeDevTools).
* Update documentation for Skills Extension SEP and related resources
- Revised links and descriptions in README.md to reflect the submitted Skills Extension SEP (PR #2640).
- Updated current status in approaches.md to indicate submission of the Skills Extension SEP.
- Clarified tracking information in open-questions.md regarding the Skills Extension SEP submission.
- Adjusted related work in related-work.md to include the Skills Extension SEP and mark a rejected proposal.
- Changed status in sep-draft-skills-extension.md to 'submitted' and updated author information.
- Enhanced skill-uri-scheme.md to indicate the incorporation of feedback into the submitted Skills Extension SEP.
* Move rejected SEP-2093 to the bottom of SEPs and Proposals table
Keeps the list active-proposals-first so readers aren't distracted by the
struck-out entry.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Mark SEP-2076 as closed and move to the bottom of proposals table
PR #2076 was closed without merge on 2026-02-24.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Use SEP-2640 naming convention per MCP SEP guidelines
Per https://modelcontextprotocol.io/community/sep-guidelines, a submitted
SEP is named "SEP-<PR-number>". Rename in-repo references from "PR #2640"
to "SEP-2640" and update the draft doc heading from the "SEP-0000"
placeholder to "SEP-2640".
Also mark Approach 1's SEP-2076 status as closed (2026-02-24, no sponsor
found); approaches.md still listed it as "Draft, seeking sponsor".
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Fix SEP-2076 closure rationale
Closure followed the WG's decision to first explore a convention-based
approach using existing primitives, not a sponsor issue.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Refine SEP-2640 description in README to clarify proposal details
* Link issues and meeting notes in Open Questions README row
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Surface SEP-2640 in README and related-work table order
README: move the Skills Extension SEP from the bottom of the Repository
Contents table to sit after Approaches, matching the narrative flow
(framing → options → proposal → supporting material).
related-work.md: lead the SEPs and Proposals table with SEP-2640 (this
WG's headline proposal), followed by the prerequisite PR #2527.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add 'Open work' link to README header pointing to open PRs
Signals that alternative proposals, decisions, implementations, and
other in-flight contributions are welcome — SEP-2640 is one direction,
not the only one.
🦉 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: log URI scheme decision for skill resources
Backfills a decision-log entry for the `skill://` URI convention
adopted via PR #70. Captures the convergence signal, the key
reversal (decoupling path from skill name), and notes the month-long
open-review period on GitHub and in Discord.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: update rationale for URI scheme decision to clarify discussion context
* docs: broaden URI scheme decision to cover domain-specific schemes
Acknowledges implementations that used domain-specific URI schemes
alongside skill://, and frames the adopted pattern as a recommended
convention rather than a universal rule.
* docs: align URI scheme decision with SEP draft's final position
Updates the 2026-04-16 URI scheme entry to reflect where the draft SEP
actually landed rather than the survey's earlier recommendation:
- Final path segment MUST equal the skill's frontmatter name (not fully
decoupled). Prefix segments remain server-chosen.
- Enumeration is via the well-known skill://index.json resource, not
scoped resources/list.
- Domain-specific URI schemes are permitted when indexed, which the
earlier wording placed in Context as observed convergence rather than
as an allowed Decision point.
- No-nesting phrasing aligned with the SEP ("descendant directory of
a skill").
Context also restored to the survey's four-implementations framing.
* docs: restore Context framing on URI scheme decision
Restores the earlier "Several...etc." wording and "Resources to
represent skills" framing in Context; keeps the SEP-structural edits
(final-segment-equals-name, index.json, domain-specific schemes).
* docs: calibrate enumeration wording to match SEP SHOULD level
The SEP specifies servers SHOULD expose skill://index.json, with an
explicit escape hatch for unenumerable catalogs. Previous wording used
RFC 2119 OPTIONAL which understated the recommendation. Also notes
alignment with the Agent Skills well-known URI index format and folds
template entries into the enumeration bullet where they belong.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add draft SEP for Skills Extension
Pre-submission Extensions Track SEP defining the skill:// resource
convention: skills as MCP resources following the Agent Skills spec,
discovered via scoped resources/list (SEP-2093). Includes implementation
guidelines for host-provided read_resource tools, virtual-filesystem
unification with local skills, and SDK convenience wrappers.
* Relax URI structure and make discovery optional
- skill-path may be arbitrarily nested and need not match the
frontmatter name; the URI is a locator, identity lives in SKILL.md
- resources/list(uri="skill://") is SHOULD not MUST; response is
SKILL.md entries only, supporting files excluded
- resource templates are MAY, framed as user-facing (completion API)
- direct URI readability is the baseline; hosts must support loading
skills they have never seen listed
- SEP-2093 dependency is now conditional on whether the server
supports enumeration
* Constrain final path segment to match frontmatter name
The previous draft fully decoupled <skill-path> from the skill name,
which meant the name could not be read from the URI without fetching
and parsing SKILL.md.
Now: the final segment of <skill-path> MUST equal the frontmatter
name. Preceding segments remain an optional server-chosen prefix for
organizational hierarchy. This keeps the hierarchy capability while
making the skill name recoverable from the URI alone.
* Replace scoped resources/list enumeration with skill://index.json
Enumeration now uses a well-known skill://index.json resource whose
format mirrors the Agent Skills .well-known discovery index: same
$schema, same skills[] shape. Two deltas from the HTTP index: url
holds the full skill:// URI, and digest is omitted (transport handles
integrity over an authenticated connection). type MUST be "skill-md"
since archives don't apply when every file is individually
addressable.
This drops the SEP-2093 dependency entirely — the extension now has
zero protocol dependencies beyond resources/read.
Also includes review feedback from PR #69:
- Security: skill content MUST be treated as untrusted input; hosts
MUST NOT honor local-execution mechanisms (hooks, scripts) without
explicit opt-in; "more harm" softened to "as much harm"; user
inspection SHOULD be supported
- Cite agentskills.io parent-directory rule for the final-segment
constraint
- No-nesting constraint reworded per cliffhall suggestion
- Abstract mentions progressive disclosure as delegated concern
- Hosts section: SHOULD load frontmatter into context, SHOULD surface
skills for user enable/disable
- read_resource signature marked illustrative
- "community has explicitly pushed back" softened
* Relax skill:// scheme to SHOULD; add urlTemplate to index
The index is now the authoritative record of which resources are
skills, so the scheme prefix is no longer required for identification.
Servers SHOULD use skill:// but MAY serve skills under a
domain-native scheme (github://, etc.) provided they're listed in
skill://index.json. Structural constraints (final segment = name,
explicit SKILL.md, no nesting) apply regardless of scheme.
Index entries now carry exactly one of url or urlTemplate. type stays
"skill-md" either way — it describes what the resolved URL points to,
not whether the entry is parameterized. Template entries omit name.
Servers SHOULD register the same urlTemplate as an MCP resource
template so the completion API works.
The Resource Templates subsection is deleted; templates are now an
index feature (a "template entry") rather than a parallel discovery
mechanism. Discovery is down to two mechanisms: the index and server
instructions.
skill://index.json remains the one fixed URI.
* Use type:"mcp-resource-template" for template index entries
Template entries now reuse the url field with type as the
discriminator, rather than a separate urlTemplate field. This is
consistent with the upstream schema where type already discriminates
how to interpret url (skill-md vs archive). The mcp-resource-template
type is namespaced so upstream consumers skip it safely per the
existing unrecognized-type rule.
* docs: transition from Interest Group to Working Group
Follow-up to modelcontextprotocol/modelcontextprotocol#2586, which
converted the charter from IG to WG.
- Rename Interest Group → Working Group in headings and prose
- Update Discord (#skills-over-mcp-wg) and Discussions
(meeting-notes-skills-over-mcp-wg) references; channel renames
coordinated separately
- CONTRIBUTING.md: align meeting norms with MCP group governance
(7-day advance notice, meet.modelcontextprotocol.io) and rewrite
Decision-Making to reflect WG authority (lazy consensus → formal
vote → escalation), linking to the charter's Authority table
- Keep CODEOWNERS team at skills-over-mcp-ig pending access-repo
rename; TODO comment added
- decisions.md: update present-tense preamble, log the IG → WG
transition as a new ADR entry, and preserve historical entries
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(contributing): link to governance/charter instead of duplicating
Meetings and Decision-Making sections now point to the MCP group
governance doc and charter for canonical rules, keeping only the
repo- or group-specific bits (notes location, coordination
channels, outputs list). Also drops a leftover "rough consensus"
IG-era phrase in the Decision Log guidelines.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(codeowners): fix sentence fragment in default-owner comment
"Has day-to-day governance" read as an incomplete sentence and
overstated what CODEOWNERS actually encodes (review routing, not
governance). Replace with a direct one-liner.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Aligns the proposed convention with the draft SEP:
- skill-path is a locator of one or more segments, not the skill name;
identity lives in SKILL.md frontmatter
- authority component is the first path segment by RFC 3986 mechanics
but carries no special semantics
- add no-nesting constraint (SKILL.md cannot be ancestor of another)
- resource templates are MAY and primarily user-facing via completion
- enumeration via resources/list is optional; clients must not treat
an empty list as proof of absence
- add nested-path examples throughout
The survey section is unchanged; it's historical record.
* Reorganize related-work.md to separate IG member work from community and ecosystem
The flat implementations list mixed IG facilitator/participant work with
community adoptions and tangentially related ecosystem projects, making it
hard to see which implementations are actively shaping the group's direction.
Changes:
- Split "Implementations" into "IG Member Implementations", "Community
Implementations", and "Related Ecosystem Work" sections
- Add Organization column to IG member table for clearer attribution
- Add skillful-mcp (Kurtis Van Gent / Google Cloud) as IG member impl
- Update my-cool-proxy attribution to Jack Tysoe / Kong
- Split "External Resources" into "Specifications and Standards" and
"Background Reading"
- Move Cloudflare RFC from Open SEPs to Specifications (it's a published
spec, not a proposal to this group) and update to v0.2.0 with correct
path (/.well-known/agent-skills/)
- Update implementation notes with recent version/feature info
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Rename section header from "Community Implementations" to "Other Community Implementations" for clarity in related work documentation
* Fix my-cool-proxy attribution and move to community implementations
karashiiro (Kara) is not Jack Tysoe from Kong — incorrectly conflated
the two based on "MCP gateway" mention in meeting notes. Move
my-cool-proxy back to community implementations with correct author.
Also incorporates the section rename to "Other Community Implementations"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Move NimbleBrain to community implementations
NimbleBrain (Mathew Goldsborough) has one comment on the IG repo and was
referenced in the inaugural meeting notes, but hasn't attended meetings
or filed issues/PRs. Better categorized as a community implementation.
Kurtis Van Gent stays in IG member table — he's an MCP core maintainer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Separate IG member work by alignment with core patterns
After reviewing the actual implementations against the IG's direction
(SKILL.md frontmatter, skill:// URIs, progressive disclosure via MCP
primitives), three repos directly implement those patterns while three
take alternative approaches worth documenting separately.
Core pattern implementations:
- skilljack-mcp: full SKILL.md + skill:// + progressive disclosure + dynamic updates
- skills-over-mcp: SKILL.md + skill:// resources + Zod validation
- skillsdotnet: SKILL.md + skill:// + load_skill tool + NuGet published
Alternative approaches (still by IG members):
- skillful-mcp: progressive disclosure via tools wrapping MCP servers (no SKILL.md)
- astronomer-agents: production SKILL.md catalog via plugin marketplace (not MCP resources)
- mcpGraph: tool orchestration engine with SKILL.md as docs (not runtime skills)
Also enriched implementation notes with specific technical details from
code review rather than surface-level descriptions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Rename section to 'Alternative Approaches' — Kurtis is MCP maintainer, not IG member
skillful-mcp is by Kurtis Van Gent, an MCP core maintainer who has
commented on IG work and written a relevant blog post, but is not an
IG member. Broaden the heading to include MCP maintainers alongside
IG members.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add PR #2527 (model access to resources) to Open SEPs
This spec PR recommends clients expose resource read to models, which
is a prerequisite for the resources-based skills approach. Discussed in
the April 7 IG meeting as a primary blocker — skills as resources only
work if models can actually read them.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Update skill-meta-keys.md to reference merged URI scheme doc
Replace PR #53 links with relative references to the now-merged
skill-uri-scheme.md document.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Refactor skilljack-mcp section and update notes on `_meta` keys for clarity
* Refocus _meta doc as scoping framework, not key recommendations
Address PR feedback: remove recommended keys that duplicate
frontmatter or belong at the plugin/distribution layer. Change
namespace to io.modelcontextprotocol.skills/. Establish scoping
principles for when _meta is appropriate vs frontmatter, annotations,
or distribution-layer mechanisms.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add decision record: _meta reserved for MCP-transport concerns
Records the decision from PR #60 review that skill-level semantics
stay in frontmatter, _meta is for MCP-transport-specific metadata,
and no specific keys are recommended yet.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Add why-and-when doc explaining value proposition and decision guide
Adds docs/why-and-when.md covering why skills over MCP matters (same
channel as tools, discovery, dynamic updates, control model, multi-server
composition, enterprise distribution) and when MCP distribution adds
value vs simpler alternatives. Linked from README and problem-statement.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add why-and-when summary to README before problem statement
Gives newcomers the value proposition immediately: skills are context,
MCP is a context protocol, and remote MCP servers can serve tools and
know-how together. Links to the full doc for depth.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add portable sub-agent point to why-and-when doc
Skills over MCP replaces the pattern of independently wrapping each
MCP server in a custom sub-agent with hand-written instructions —
the server author ships orchestration guidance once, everyone benefits.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Acknowledge enterprise trust trade-offs in both directions
Address PR feedback: git-based and MCP-based skill distribution each
raise different governance concerns. Link to open question on security
and trust boundaries.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add skill URI scheme proposal with survey of existing patterns (#44)
Survey 6 existing URI patterns (NimbleBrain, skilljack-mcp, skills-over-mcp,
FastMCP 3.0, Cloudflare well-known RFC, SEP-2076) and propose a recommended
skill:// URI convention for MCP skill resources. Cross-reference from
approaches.md Approach 6.
* Fix URI structure description: skill name is the authority, not a path segment
* Add versioning deferral note and multi-server collision handling
Address PR review feedback: note that versioning is intentionally deferred,
and recommend clients provide a read_resource tool with server name for
disambiguation when multiple servers expose the same skill URI.
* Add decision log with ADR-lite format (#49)
Create docs/decisions.md seeded with 6 historical decisions reconstructed
from closed issues and meeting notes. Update CONTRIBUTING.md with guidance
on when to add decision log entries and add to README documents table.
* Address review feedback: reframe Decision 1 scope, fix relative links
* Add community insights from Discord threads and meeting notes
Distill Discord discussions (Feb 14-24) and Feb 26 office hours into
existing docs:
- New findings: NimbleBrain skill:// resource consolidation, skill
reliability/adherence issues across implementations
- Expanded approaches with distribution/provenance considerations,
resources adoption insight, and domain-level discovery (.well-known)
- Expanded open questions on dependencies and distribution trust
- Added Cloudflare Agent Skills Discovery RFC and NimbleBrain
reference implementations to related work
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Remove trust note since its already mentioned in the doc separately
* Clarify attribution for community insights on skill dependencies in open questions
* Refine findings on model skill adherence and community workarounds
* Remove outdated comparison section and streamline evaluation insights in experimental findings
* Remove unnecessary blank line in experimental findings documentation
* Add SEP-2093 proposal to related work documentation
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Add docs-as-MCP-server and plugin/powers use cases
Add two new use cases from Clare Liguori and Luca Chang (AWS) shared
in Discord after the first IG meeting:
- Documentation as MCP Server (search_docs/fetch_doc pattern)
- Skills + MCP Server Plugins (one-click bundling of skills + servers)
Add related implementations and external resources (Strands, AWS MCP,
Kiro powers, llms.txt, AWS Agent SOPs).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Add link to mcpdoc and more context
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Update meeting notes and discussion links to main MCP repo
Meeting notes are published in the main modelcontextprotocol repo
discussions, not in this IG repo. Update CONTRIBUTING.md and README.md
to reflect this and note that future meetings/surveys are posted in
the Discord channel.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Add out of scope item for plugin/bundle packaging in README
* Revert "Add out of scope item for plugin/bundle packaging in README"
This reverts commit 75b962ea59f0af0b29e3bd1fcb0994eb2ff0b73d.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
