ext-skills/docs/archive/glossary.md

Glossary

Historical document. Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the stable specification for current requirements and the archive index for context.

This glossary defines working terminology for the Skills Over MCP documents. It is descriptive rather than normative: the MCP specification and the Agent Skills specification remain the source of truth for their respective formats and protocol surfaces. Definitions are intentionally short (1–3 sentences) and note alignment or divergence with Agent Skills where relevant.

Core terms

Term	Working definition
Skill	Structured workflow context that teaches an agent how to perform a task, usually by coordinating tools, prompts, resources, or domain knowledge. This working group uses the Agent Skills directory model as the payload format — a directory with a required SKILL.md file and optional supporting files — and adds discovery, transport, URI, and host-loading conventions over MCP rather than redefining the skill format.
Instruction	In MCP, server instructions are initialization-time guidance a server returns before any individual tool or resource is used. Skill instructions are the workflow content inside SKILL.md and its supporting files, usually loaded only when a specific skill is relevant. The two are not interchangeable: they differ in scope, loading lifecycle, and size constraints.
Primitive	An MCP protocol primitive is a named capability surface with defined messages, capabilities, and client behavior, such as Tools, Resources, or Prompts. In this repository, "primitive" should not be used loosely for any convenient implementation object; when skills reuse existing Resources, "skill" is not a new MCP primitive.
Resource	MCP's URI-addressed mechanism for servers to expose data or content that clients can incorporate as context. Skills Over MCP currently uses Resources as the transport fit because skills are file-like context that can be listed, read, and progressively loaded.
Convention	A documented, interoperable pattern that implementations can adopt without changing the MCP base protocol. SEP-2640 is largely a convention — skill files served as Resources, conventionally under skill:// — plus a small extension surface (skills/list, skills/get, optional resources/directory/read) declared under the io.modelcontextprotocol/skills extension identifier.
Context	Information made available to a model or host so it can decide what to do next, especially workflow know-how exposed as resources. This is narrower than the general "LLM context window": context-as-resources focuses on addressable, selectively loadable material before it becomes model tokens, though that material eventually consumes the window.
Progressive disclosure	Staged loading of skill material: lightweight discovery metadata first, the full SKILL.md when relevant, and supporting files only when the workflow calls for them. This aligns with the Agent Skills model and maps naturally to MCP Resources, since each layer can be read on demand.
Control model	Describes who decides that content is visible or loaded — the host application, the user, the model, or some combination. MCP Resources are application-driven by default while tools are model-invoked once exposed; Skills Over MCP sits at this boundary, so designs need to state whether a skill is surfaced by the host, fetched through a model-readable resource tool, or both.
First-class primitive	A dedicated MCP protocol surface with its own capability, methods, and change notifications, on par with Tools, Resources, and Prompts — for skills, something like skills/activate plus notifications/skills/list_changed (see approaches.md and the closed SEP-2076). The Working Group declined this: in SEP-2640 a skill's content is ordinary Resources, and skills/list/skills/get are extension methods that return metadata and digests about those resources rather than a new content-delivery primitive.
Server author	The person or organization that ships and maintains an MCP server and controls the tools, resources, auth, update cadence, and transport behavior it exposes. A server author may also author skills, but in multi-server or ecosystem scenarios they often provide only one part of the system.
Skill author	The person or organization that writes a skill's SKILL.md, examples, references, and declared assumptions. This may be the server author, a platform team, or a third party documenting how to use an existing server; the distinction matters when a skill orchestrates tools from several servers or when registry metadata suggests companion skills.
Discovery	Learning that a skill exists and obtaining enough metadata to decide whether it may be relevant. Fetching or reading SKILL.md is a separate content-loading step; conflating the two can hide important control, privacy, and performance choices, and matters most for large catalogs or servers with incomplete enumeration.

Distribution and ecosystem terms

Term	Working definition
Skill resource	A skill file exposed through MCP's Resources primitive, such as skill://git-workflow/SKILL.md or a supporting reference file under the same skill path. The resource URI is the transport locator; the skill's semantic metadata still lives in SKILL.md frontmatter as defined by the Agent Skills specification. Relative references inside a skill resolve against the skill's root directory, as on a filesystem.
skill:// URI	The URI scheme servers SHOULD use for skill resources, of the form skill://<skill-path>/<file-path> where the last segment of <skill-path> equals the skill's frontmatter name. No scheme is privileged: a server may serve skills under a domain-native scheme, and a host MUST NOT conclude a resource is a skill from its scheme alone — skill identity comes from a skills/list entry or a skills/get answer. See skill-uri-scheme.md for the history.
Skill metadata	Structured fields that describe a skill, carried in its SKILL.md YAML frontmatter (name and description are required; license, metadata, and future Agent Skills fields pass through). A skill entry returned by skills/list or skills/get copies this frontmatter verbatim so a host can build its skill registry without reading each SKILL.md. MCP reserves two distinct extension points: keys under io.modelcontextprotocol/ inside the frontmatter metadata object (skill-level metadata defined by MCP extensions), and the io.modelcontextprotocol.skills/ prefix on a resource's _meta (transport-specific metadata). Skill-level semantics stay in frontmatter rather than _meta.
Compatibility	A free-text compatibility field in SKILL.md frontmatter describing the environment a skill expects. By design it is evaluated by a model against its runtime rather than checked deterministically, so it is not a machine-readable capability gate. Hosts that must screen skills — e.g. a non-sandbox agent filtering out skills that require code execution — apply their own conventions today (such as treating a scripts/ directory as execution-requiring); the Working Group's position is that execution/environment signaling belongs in the Agent Skills specification, since it applies to skills from any source, not only MCP.
Skill entry	The record skills/list and skills/get return for one skill: the SKILL.md uri, the verbatim frontmatter, and a resources array listing every file in the skill with its digest. resources is complete — an unlisted file is a change to the skill — and MAY be omitted only for dynamically generated skills, which hosts MAY decline to load.
skills/list	The enumeration method every server declaring the extension MUST implement. The result MAY be empty or partial when a catalog is large, generated, or unenumerable, so an absent skill is not proof a server does not serve it. Replaced the earlier skill://index.json resource (decision log, 2026-07-16).
skills/get	The retrieval method every server declaring the extension MUST implement: given a SKILL.md URI, it returns that skill's entry, including for skills absent from the listing, and errors for URIs the server does not serve as a skill. This is how a URI handed over by server instructions, another skill, or the user becomes a verifiable, approvable skill (decision log, 2026-07-15).
Digest	The content hash (sha256:…) carried per file in an entry's resources. Hosts MUST verify fetched content against it and MUST NOT use content that mismatches; a changed resources set revokes any content-bound approval. Digests also let hosts cache verified copies and detect changes without re-reading.
Archive	A pre-packed form of an entire skill directory (e.g. application/gzip) that earlier drafts listed in an archives array so a host could fetch a multi-file skill in one round trip. Removed from v1 (decision log, 2026-07-16); per-file resources with digests cover integrity, and a batch resource read is the proposed follow-up for round trips. The threat model appendix records the constraints for any reintroduction.
Directory listing	The optional resources/directory/read method (gated by the extension's directoryRead capability) that returns the direct children of a directory resource (mimeType: inode/directory) — metadata only, like ls, not a recursive read — letting an agent walk a skill's supporting files without knowing every URI in advance. Not skill-specific: a server MAY support it on any directory resource.
Server-skill pairing	The pattern where an MCP server ships skills that explain how to use its own tools effectively, with skill and tools versioned and distributed together as a single unit.
Multi-server composition	A workflow where a skill coordinates tools from more than one MCP server, useful when a task spans services such as a database, ticketing system, and deployment platform.
Ephemeral availability	The property that a skill is available while its MCP server is connected, without requiring a separate permanent install on the client machine.
Provenance	Information about where a skill came from and which server, organization, or artifact produced it — supporting trust, review, and debugging, and tied to the server-author vs. skill-author distinction. The Working Group has treated provenance as a distribution/plugin-layer concern rather than standardized skill frontmatter or resource _meta.

References

• SEP-2640: Skills Extension — the extension these terms describe (v1 copy at sep-draft-skills-extension.md)
• Decision Log — Working Group decisions that ground several definitions
• Agent Skills specification
• MCP Resources specification
• MCP Tools specification
• Open Questions
• Approaches
• Skill URI Scheme Proposal