docs: align Skills corrections with the final SEP and website (#147)
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.
This commit is contained in:
Sambhav Kothari
GitHub
parent
81f55b67fe
commit
34315ab7d7
16 changed files with 92 additions and 48 deletions
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**IMPORTANT**: The source of truth for the Skills extension (`io.modelcontextprotocol/skills`) is [`specification/stable/skills.mdx`](specification/stable/skills.mdx) in this repository. It is the normative text of the extension, written against base protocol revision `2026-07-28`, and is what the official documentation at [modelcontextprotocol.io/extensions/skills/overview](https://modelcontextprotocol.io/extensions/skills/overview) summarizes.
|
||||
|
||||
[SEP-2640](https://modelcontextprotocol.org/seps/2640-skills-extension) is the accepted proposal behind the extension (Status: Final; [PR #2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) merged 2026-09-13). [`docs/archive/sep-draft-skills-extension.md`](docs/archive/sep-draft-skills-extension.md) is a copy of that SEP text pinned at the commit named in its header, kept so Working Group discussion, meeting notes, and decision records can quote and link stable text. It is a historical baseline, not the current spec.
|
||||
[SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension) is the accepted proposal behind the extension (Status: Final; [PR #2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) merged 2026-09-13). [`docs/archive/sep-draft-skills-extension.md`](docs/archive/sep-draft-skills-extension.md) is a copy of that SEP text pinned at the commit named in its header, kept so Working Group discussion, meeting notes, and decision records can quote and link stable text. It is a historical baseline, not the current spec.
|
||||
|
||||
- **Answer questions about what the extension requires from `specification/stable/skills.mdx`**, not from the SEP copy or the `docs/` folder. Where the spec page and the SEP differ, the [decision log](docs/decisions.md) records why (see the 2026-09-08 entry).
|
||||
- The `docs/` folder holds design history, rationale, experimental findings, and trackers. Treat it as context, not as normative text.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Agent Plugins x Skills Over MCP
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
## Summary
|
||||
|
||||
Agent Plugins 1.0 is a portable *packaging* format — a directory with a `plugin.json` manifest whose two component types are Agent Skills (a `skills/` directory) and MCP server configurations (`mcp.json`). It deliberately layers on top of the Agent Skills spec and MCP rather than redefining either, so it is overwhelmingly a **complement** to SEP-2640: the SEP moves skills over the wire at runtime; Agent Plugins moves them onto disk at install time. The two even compose — a plugin's `mcp.json` can point at a server that itself serves skills under the extension.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Approaches Being Explored
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> ℹ️ The design space has largely converged on the convention approach (Approach 6), now formalized as [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640). This document is kept as a map of the alternatives that were considered; for the current direction, see the SEP.
|
||||
|
||||
> These are not mutually exclusive solutions.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Experimental Findings
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> ℹ️ **This document is not actively maintained.** It captures a snapshot of early findings. Current discussion and decisions are tracked in the [meeting notes discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg), [Discord #skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084), and on the [SEP-2640 PR](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640).
|
||||
|
||||
> **Contributing findings?** Start with the [experimental findings template](findings-template.md).
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Experimental Findings Template
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
Use this template when adding an entry to [experimental-findings.md](experimental-findings.md). Include enough evidence for another contributor to evaluate the result, and write "Not documented" rather than inferring missing details.
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# 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](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
This glossary defines working terminology for the Skills Over MCP documents. It is descriptive rather than normative: the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/resources) and the [Agent Skills specification](https://agentskills.io/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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Open Questions
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> ℹ️ **This document is not actively maintained.** It captures a snapshot of early discussion. Current open questions and decisions are tracked in the [meeting notes discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg), [Discord #skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084), and on the [SEP-2640 PR](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640).
|
||||
|
||||
## 1. Is this a registry problem or an MCP server problem?
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Problem Statement
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
[Agent Skills](https://agentskills.io/home) support in AI applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives.
|
||||
|
||||
## Current Limitations
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Related Work
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
## SEPs and Proposals
|
||||
|
||||
| Proposal | Venue | Description |
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# SEP-2640: Skills Extension
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
- **Status**: Draft
|
||||
- **Type**: Extensions Track
|
||||
- **Created**: 2026-04-23
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Using `_meta` for Skill Resources
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> Guidelines for structured metadata on skill resources served over MCP.
|
||||
|
||||
**Issue:** [#55](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/55)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Skill URI Scheme Proposal
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> Proposed convention for identifying skill resources over MCP.
|
||||
|
||||
**Issue:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Threat Model: Skills Over MCP
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> ⚠️ **Experimental** — This document models threats against skills served over MCP as specified in [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) *in its current form*: the revision on the canonical [`sep/skills-extension`](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640/files) branch, which supersedes the older [`docs/sep-draft-skills-extension.md`](sep-draft-skills-extension.md) working draft. That revision **replaced the `skill://index.json` resource with the `skills/list` and `skills/get` methods, added a per-file `resources` digest array covering the whole skill, and moved archive distribution to a deferred-features appendix.** It is a Working Group reference, not a normative part of the SEP. Where it recommends behavior beyond what SEP-2640 mandates, it says so.
|
||||
|
||||
## Scope
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Use Cases
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
## 1. Complex Workflow Orchestration
|
||||
|
||||
Skills that teach agents how to perform multi-step workflows that they wouldn't know how to execute from tool descriptions alone.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Why Skills Over MCP?
|
||||
|
||||
> **Historical document.** Frozen during development of SEP-2640; statements of current status and requirements below describe that draft-era context. See the [stable specification](../../specification/stable/skills.mdx) for current requirements and the [archive index](README.md) for context.
|
||||
|
||||
> The value proposition for distributing agent skills through MCP, and a guide for when it applies.
|
||||
|
||||
## The Gap Between Tools and Know-How
|
||||
|
|
|
|||
|
|
@ -30,14 +30,17 @@ This extension is identified as: `io.modelcontextprotocol/skills`.
|
|||
|
||||
This page specifies the extension against base protocol revision `2026-07-28` or later. Type names it references without defining (`Result`, `PaginatedRequest`, `PaginatedResult`, `CacheableResult`, `Resource`, `Cursor`) are those of the base schema at that revision.
|
||||
|
||||
For brevity, request examples omit `_meta`. Every request **MUST** include the required [request metadata](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#_meta).
|
||||
|
||||
## Capability Negotiation
|
||||
|
||||
Servers declare support for this extension in the `extensions` field of their capabilities:
|
||||
Servers declare support for this extension in the `extensions` field of their capabilities in `server/discover`:
|
||||
|
||||
```jsonc
|
||||
// Server capabilities
|
||||
{
|
||||
"capabilities": {
|
||||
"resources": {},
|
||||
// Other capabilities...
|
||||
"extensions": {
|
||||
"io.modelcontextprotocol/skills": {
|
||||
|
|
@ -72,7 +75,7 @@ A skill served over MCP **MUST** conform to the [Agent Skills specification](htt
|
|||
- `SKILL.md` **MUST** begin with YAML frontmatter containing at minimum the `name` and `description` fields as defined by the Agent Skills specification.
|
||||
- A skill **MAY** contain additional files and subdirectories (references, scripts, examples, assets).
|
||||
|
||||
This extension does not redefine, constrain, or extend the skill format. Future revisions of the Agent Skills specification apply automatically.
|
||||
This extension does not redefine, constrain, or extend the skill format. Future revisions of the Agent Skills specification apply automatically. In the event that the Agent Skills specification changes in a backwards incompatible way, clients **MUST** honor any backwards compatibility mechanisms provided by the Agent Skills specification and **SHOULD** continue to support the Agent Skills specification as it existed prior to any incompatible change.
|
||||
|
||||
## Resource Mapping
|
||||
|
||||
|
|
@ -282,8 +285,8 @@ interface ListSkillsResult extends PaginatedResult, CacheableResult {
|
|||
"resources": [
|
||||
{
|
||||
"uri": "skill://git-workflow/SKILL.md",
|
||||
"digest": "sha256:a1b2c3d4...",
|
||||
"size": 2314
|
||||
"digest": "sha256:b95a384300adeea2d902f7d19cd7c04b378ef58e09759107b9c7db4dcacbaa25",
|
||||
"size": 190
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
@ -297,13 +300,13 @@ interface ListSkillsResult extends PaginatedResult, CacheableResult {
|
|||
"resources": [
|
||||
{
|
||||
"uri": "skill://acme/billing/refunds/SKILL.md",
|
||||
"digest": "sha256:b2c3d4e5...",
|
||||
"size": 3871
|
||||
"digest": "sha256:ae7bc7e45f44a6381977ef1f772cbad6e38d8ec78903ea7b87abb373815a8f89",
|
||||
"size": 175
|
||||
},
|
||||
{
|
||||
"uri": "skill://acme/billing/refunds/examples/email.md",
|
||||
"digest": "sha256:c3d4e5f6...",
|
||||
"size": 962
|
||||
"digest": "sha256:a724fa5ed3b9e39c0e731fe1f0e866eb46d23969af25ecf0d5f41982e3e36bea",
|
||||
"size": 58
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
@ -378,39 +381,23 @@ interface GetSkillResult extends CacheableResult {
|
|||
"uri": "skill://pdf-processing/SKILL.md",
|
||||
"frontmatter": {
|
||||
"name": "pdf-processing",
|
||||
"description": "Extract, fill, and assemble PDF documents",
|
||||
"metadata": { "version": "2.1.0" }
|
||||
"description": "Extract, fill, and assemble PDF documents"
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"uri": "skill://pdf-processing/SKILL.md",
|
||||
"digest": "sha256:d5e6f7a8...",
|
||||
"size": 5120
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/references/FORMS.md",
|
||||
"digest": "sha256:e6f7a8b9...",
|
||||
"size": 18433
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/scripts/extract.py",
|
||||
"digest": "sha256:f7a8b9c0...",
|
||||
"size": 4096
|
||||
"digest": "sha256:99b737495721155ece826d57521e2d66141ebdc1344a400487481ea2642ab19e",
|
||||
"size": 151
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/invoice.md",
|
||||
"digest": "sha256:a8b9c0d1...",
|
||||
"size": 1210
|
||||
"digest": "sha256:61f4ea6d2c75fde1b4977219e7e3107d491c3c26aefb6686e84d6281c088d9ee",
|
||||
"size": 29
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/purchase-order.md",
|
||||
"digest": "sha256:b9c0d1e2...",
|
||||
"size": 1388
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/regional/eu-invoice.md",
|
||||
"digest": "sha256:c0d1e2f3...",
|
||||
"size": 1472
|
||||
"digest": "sha256:f2ff774b1737ff3dec81c47946f9976f18a1a9f69dda0a81f22eabd95173c158",
|
||||
"size": 35
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
@ -613,18 +600,18 @@ Consider a host connected to a server it labels `docs-server`, which declares th
|
|||
"resources": [
|
||||
{
|
||||
"uri": "skill://pdf-processing/SKILL.md",
|
||||
"digest": "sha256:d5e6f7a8...",
|
||||
"size": 5120
|
||||
"digest": "sha256:99b737495721155ece826d57521e2d66141ebdc1344a400487481ea2642ab19e",
|
||||
"size": 151
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/invoice.md",
|
||||
"digest": "sha256:a8b9c0d1...",
|
||||
"size": 1210
|
||||
"digest": "sha256:61f4ea6d2c75fde1b4977219e7e3107d491c3c26aefb6686e84d6281c088d9ee",
|
||||
"size": 29
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/purchase-order.md",
|
||||
"digest": "sha256:b9c0d1e2...",
|
||||
"size": 1388
|
||||
"digest": "sha256:f2ff774b1737ff3dec81c47946f9976f18a1a9f69dda0a81f22eabd95173c158",
|
||||
"size": 35
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -635,6 +622,26 @@ Consider a host connected to a server it labels `docs-server`, which declares th
|
|||
}
|
||||
```
|
||||
|
||||
The supporting files in this example contain the following UTF-8 text, each ending with a newline. Their sizes and SHA-256 digests match the manifest above.
|
||||
|
||||
`invoice.md`:
|
||||
|
||||
```markdown
|
||||
# Invoice
|
||||
|
||||
Customer:
|
||||
Amount:
|
||||
```
|
||||
|
||||
`purchase-order.md`:
|
||||
|
||||
```markdown
|
||||
# Purchase order
|
||||
|
||||
Supplier:
|
||||
Items:
|
||||
```
|
||||
|
||||
The host records the entry under the identity (`docs-server`, `skill://pdf-processing/SKILL.md`), surfaces the skill's name, description, and origin to the model and the user, and fetches nothing further.
|
||||
|
||||
Later the model asks to load the skill. The host obtains user approval, binding it to the three `{uri, digest}` pairs above, then reads `SKILL.md` from `docs-server`:
|
||||
|
|
@ -660,7 +667,7 @@ Later the model asks to load the skill. The host obtains user approval, binding
|
|||
{
|
||||
"uri": "skill://pdf-processing/SKILL.md",
|
||||
"mimeType": "text/markdown",
|
||||
"text": "---\nname: pdf-processing\ndescription: Extract, fill, and assemble PDF documents\n---\n\n# PDF processing\n\nChoose the matching template from `templates/` ..."
|
||||
"text": "---\nname: pdf-processing\ndescription: Extract, fill, and assemble PDF documents\n---\n\n# PDF processing\n\nChoose the matching template from `templates/`.\n"
|
||||
}
|
||||
],
|
||||
"ttlMs": 300000,
|
||||
|
|
@ -669,7 +676,7 @@ Later the model asks to load the skill. The host obtains user approval, binding
|
|||
}
|
||||
```
|
||||
|
||||
The host checks that the content is 5120 bytes and hashes to `sha256:d5e6f7a8...`, parses the frontmatter and confirms it equals the entry's `frontmatter`, then places the content in the model's context tagged as originating from `docs-server`. The host is now acting on the skill and holds this entry.
|
||||
The host checks that the content is 151 bytes and matches the manifest's SHA-256 digest, parses the frontmatter and confirms it equals the entry's `frontmatter`, then places the content in the model's context tagged as originating from `docs-server`. The host is now acting on the skill and holds this entry.
|
||||
|
||||
The instructions reference `templates/`. The model lists the directory, and the host routes this to `docs-server`:
|
||||
|
||||
|
|
@ -713,6 +720,15 @@ The instructions reference `templates/`. The model lists the directory, and the
|
|||
|
||||
`credit-note.md` is not in the held entry's `resources`, because the server added it after the listing. The host does not surface it as a file of the skill and would treat a read of it as a verification failure. The model reads `invoice.md`, which is listed. The host issues `resources/read`, verifies size and digest against the held entry, and returns the content.
|
||||
|
||||
The newly added `credit-note.md` contains this UTF-8 text, ending with a newline:
|
||||
|
||||
```markdown
|
||||
# Credit note
|
||||
|
||||
Invoice:
|
||||
Credit amount:
|
||||
```
|
||||
|
||||
To make `credit-note.md` available, the host refreshes the entry:
|
||||
|
||||
```json
|
||||
|
|
@ -741,23 +757,23 @@ To make `credit-note.md` available, the host refreshes the entry:
|
|||
"resources": [
|
||||
{
|
||||
"uri": "skill://pdf-processing/SKILL.md",
|
||||
"digest": "sha256:d5e6f7a8...",
|
||||
"size": 5120
|
||||
"digest": "sha256:99b737495721155ece826d57521e2d66141ebdc1344a400487481ea2642ab19e",
|
||||
"size": 151
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/invoice.md",
|
||||
"digest": "sha256:a8b9c0d1...",
|
||||
"size": 1210
|
||||
"digest": "sha256:61f4ea6d2c75fde1b4977219e7e3107d491c3c26aefb6686e84d6281c088d9ee",
|
||||
"size": 29
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/purchase-order.md",
|
||||
"digest": "sha256:b9c0d1e2...",
|
||||
"size": 1388
|
||||
"digest": "sha256:f2ff774b1737ff3dec81c47946f9976f18a1a9f69dda0a81f22eabd95173c158",
|
||||
"size": 35
|
||||
},
|
||||
{
|
||||
"uri": "skill://pdf-processing/templates/credit-note.md",
|
||||
"digest": "sha256:e2f3a4b5...",
|
||||
"size": 1104
|
||||
"digest": "sha256:766bffa8d4908ce897e1727ca22e4bf0fa796620b35218ce2132a124545626f1",
|
||||
"size": 39
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in a new issue