docs: add combined skills glossary#104
Draft
olaservo wants to merge 3 commits into
Draft
Conversation
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>
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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/glossary.mdwith working definitions for Skills Over MCP terminology, and cross-references it from the README documents table. Fixes #51.This is a combined draft that takes the best of the three open glossary PRs and credits all three authors as co-authors:
Skill resourceterm, and the References section.skill://URI, skill metadata, server-skill pairing, multi-server composition, ephemeral availability, provenance).Contents
skill://URI, skill metadata, server-skill pairing, multi-server composition, ephemeral availability, provenance.Acceptance criteria (#51)
Relationship to existing PRs
This supersedes #103, #101, and #93 by merging their content. If the WG prefers this combined version, those three can be closed in favor of this one; the original authors are credited via
Co-authored-bytrailers on the commit.Verification
git diff --check🦉 Generated with Claude Code