* 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>
Add UC8 (Version-Adaptive Skill Content) and UC9 (Commercial
Multi-Tenant Skills) capturing Astronomer/Airflow-specific scenarios
for skills that adapt to platform versions and SaaS multi-tenancy
with RBAC and audit logging.
