Skip to content

chore: add SEP-2640 requirement-traceability YAML (Skills Extension) #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
panyam wants to merge 3 commits into
base: main
Choose a base branch
from
+77 −0
Draft

chore: add SEP-2640 requirement-traceability YAML (Skills Extension) #330

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a64d7ea
chore: add SEP-2640 requirement-traceability YAML (Skills Extension)
panyam Jun 4, 2026
2ecad13
style: apply yaml formatter pass
panyam Jun 4, 2026
4fa8b10
chore(sep-2640): record spec source provenance
panyam Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions src/seps/sep-2640.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# spec_source: modelcontextprotocol/modelcontextprotocol@b77fdfe8c6fa91442900c52357711978617ce18a seps/2640-skills-extension.md
# extracted: 2026-06-03
sep: 2640
spec_url: https://modelcontextprotocol.io/seps/2640-skills-extension#specification
requirements:
- check: sep-2640-skillmd-required
text: 'Every skill MUST contain a `SKILL.md` file at its root.'
- check: sep-2640-skillmd-frontmatter
text: '`SKILL.md` MUST begin with YAML frontmatter containing at minimum the `name` and `description` fields as defined by the Agent Skills specification.'
- check: sep-2640-skill-uri-scheme
text: 'Each file within a skill directory is exposed as an MCP resource. Servers SHOULD use the `skill://` URI scheme, under which the resource URI has the form: `skill://<skill-path>/<file-path>`'
- check: sep-2640-final-segment-equals-name
text: "The final segment of `<skill-path>` MUST equal the skill's `name` as declared in its `SKILL.md` frontmatter."
- check: sep-2640-no-nested-skills
text: 'A `SKILL.md` MUST NOT appear in any descendant directory of a skill. The skill directory is the boundary; skills do not nest inside other skills.'
- check: sep-2640-name-naming-rules
text: "The final `<skill-path>` segment, being the skill `name`, MUST satisfy the Agent Skills specification's naming rules."
- check: sep-2640-prefix-rfc3986
text: 'Prefix segments SHOULD be valid URI path segments per RFC 3986; no further constraints are imposed on them.'
- check: sep-2640-skillmd-mimetype
text: 'For each `skill://<skill-path>/SKILL.md` resource: `mimeType` SHOULD be `text/markdown`.'
- check: sep-2640-skillmd-metadata-name
text: 'For each `skill://<skill-path>/SKILL.md` resource: `name` SHOULD be set from the `name` field of the `SKILL.md` YAML frontmatter. By the path constraint above, this will equal the final segment of `<skill-path>`.'
- check: sep-2640-skillmd-metadata-description
text: 'For each `skill://<skill-path>/SKILL.md` resource: `description` SHOULD be set from the `description` field of the `SKILL.md` YAML frontmatter.'
- check: sep-2640-meta-prefix
text: 'When `_meta` keys are used for skill resources, implementations SHOULD use the `io.modelcontextprotocol.skills/` reverse-domain prefix.'
- check: sep-2640-host-load-by-uri
text: 'hosts MUST support loading a skill given only its URI'
- check: sep-2640-server-expose-index
text: 'A server SHOULD expose a resource at the well-known URI `skill://index.json` whose content is a JSON index of the skills it serves.'
- check: sep-2640-index-entry-type-enum
text: '`skills[].type` MUST be `"skill-md"`, `"archive"`, or `"mcp-resource-template"`.'
- check: sep-2640-index-name-required
text: '`skills[].name` is Required for `"skill-md"` and `"archive"`; matches the `SKILL.md` frontmatter `name` and the final segment of the skill path. Omitted for `"mcp-resource-template"`.'
- check: sep-2640-index-digest-required
text: '`skills[].digest` is Required for `"skill-md"` and `"archive"`: SHA-256 content digest of the artifact, formatted as `sha256:{hex}` (64 lowercase hexadecimal characters). Omitted for `"mcp-resource-template"`.'
- check: sep-2640-client-ignore-unrecognized
text: 'Clients SHOULD ignore unrecognized fields and SHOULD skip entries with an unrecognized `type`.'
- check: sep-2640-archive-format
text: 'the archive MUST be `.tar.gz` (gzip-compressed tar, `mimeType` `application/gzip`) or `.zip` (`mimeType` `application/zip`)'
- check: sep-2640-host-support-archive-formats
text: 'hosts MUST support both `.tar.gz` and `.zip` archive formats'
- check: sep-2640-archive-skillmd-at-root
text: 'Archive contents represent the skill directory directly — `SKILL.md` MUST be at the archive root, not nested inside a wrapper directory'
- check: sep-2640-archive-no-traversal
text: 'the archive MUST NOT contain path-traversal sequences (`..`) or absolute paths'
- check: sep-2640-host-archive-safety
text: 'Hosts unpacking an archive MUST apply the archive safety requirements of the Agent Skills specification: reject archives containing path-traversal sequences or absolute paths, reject symlinks or hard links that resolve outside the skill directory, and enforce a limit on total unpacked size / Hosts MUST validate archives per the Agent Skills archive safety requirements: reject path traversal and absolute paths, reject links resolving outside the skill directory, and bound total unpacked size to prevent decompression bombs.'
- check: sep-2640-template-resource-template-registered
text: 'A server SHOULD register the same `url` value as an MCP resource template so hosts can wire template variables to the completion API.'
- check: sep-2640-host-verify-digest
text: 'Hosts MUST verify retrieved content against the `digest` in the index / hosts MUST NOT use unverified content.'
- check: sep-2640-host-no-empty-index-assumption
text: 'Hosts MUST NOT treat an absent or empty index as proof that a server has no skills.'

- text: 'Hosts SHOULD surface template entries in their UI as interactive discovery points: the user fills in variables via completion, selects a skill, and the host passes the resolved URI into the conversation.'
excluded: 'UI affordance: surfacing template entries as interactive discovery points is not protocol-observable on the wire.'
- text: 'Per RFC 3986, the first segment of `<skill-path>` occupies the authority component. This carries no special semantics under this convention and clients MUST NOT attempt DNS or network resolution of it.'
excluded: 'DNS and network resolution sit below the MCP wire layer; the harness cannot observe whether the client performed name lookups on URI authority components.'
- text: "[Hosts] SHOULD determine the format from the resource's `mimeType`, falling back to the URL suffix"
excluded: 'Internal decision logic: when `mimeType` and URL suffix agree, the harness cannot distinguish a host that branched on `mimeType` from one that fell back to the suffix.'
- text: 'Hosts MUST treat MCP-served skill content as untrusted model input, subject to the same prompt-injection defenses applied to any server-provided text. A server being connected does not make its skill content authoritative.'
excluded: 'Internal host policy: "treats as untrusted" is an assertion about how content is reasoned over downstream of the read, not about wire traffic.'
url: https://modelcontextprotocol.io/seps/2640-skills-extension#security-implications
- text: 'Hosts MUST NOT honor mechanisms in skill content that would cause local code execution without explicit user opt-in. This includes, non-exhaustively: hook declarations, pre/post-invocation scripts, shell commands embedded in frontmatter, or any field that a filesystem-sourced skill might use to register executable behavior on the host.'
excluded: 'Local code execution and explicit user opt-in are host-side filesystem and UX behaviors; not protocol-observable on the wire.'
url: https://modelcontextprotocol.io/seps/2640-skills-extension#security-implications
- text: 'Hosts MUST either ignore such fields entirely when the skill arrives over MCP, or gate them behind an explicit per-skill user approval that states what will execute and where.'
excluded: 'Either branch (silent ignore vs. UI-gated approval) is a host-internal handling choice; not protocol-observable.'
url: https://modelcontextprotocol.io/seps/2640-skills-extension#security-implications
- text: 'Hosts MUST NOT treat skill resources as higher-authority than other context. Explicit user policy governs whether a skill is loaded at all.'
excluded: 'Context-authority ordering is an internal prompting decision; not protocol-observable.'
url: https://modelcontextprotocol.io/seps/2640-skills-extension#security-implications
- text: "Hosts SHOULD indicate which server a skill originates from when presenting it, SHOULD let users inspect a skill's content before it is loaded into model context"
excluded: 'UI presentation requirements (origin indicator, pre-load inspection); the harness cannot observe what the host displays to users.'
url: https://modelcontextprotocol.io/seps/2640-skills-extension#security-implications