Draft MCP Skills Convention v0.1

Background

The README Work Tracking table lists "MCP Skills Convention v0.1" as "Proposed, TBD champion." This is arguably the most important concrete deliverable for this IG — a documented convention (not a protocol change) that server authors can follow today to expose skills in an interoperable way.

The convention approach is described in Approach 6 and mirrors how other ecosystems (e.g., Kubernetes) graduate patterns from convention to formal spec.

Scope

Draft a convention document covering:

1. Skill Resource Discovery

Recommended URI scheme: skill:// or well-known resource naming pattern
Resource metadata: name, description, version, tags
Listing behavior: skills SHOULD appear in resources/list response

2. Skill Content Format

Alignment with agentskills.io specification
Required frontmatter fields (name, version, description)
Recommended frontmatter fields (tags, compatibility/dependencies, provenance URL)
Body format: Markdown with sections for instructions, examples, tool references

3. Control Model Guidance

Application-controlled: expose skills as resources for host-managed loading
Model-controlled: expose a list_skills / read_skill tool for agent-initiated discovery
Recommendation: support both where possible; document which to use when

4. Server Instructions Pattern

Recommended server instruction text for directing agents to discover skills
Example: "This server provides skills. Use list_skills to see available workflows, or check resources for skill:// URIs."

5. Update Notifications

Recommend resources/subscribe + notifications/resources/updated for push-based updates
Recommend tools/listChanged for dynamic tool description updates (skilljack pattern)

Format

Standalone document: docs/convention-v0.1.md
Target: 2-4 pages, concise
At least 2 concrete examples (one simple, one multi-step)
Use RFC 2119 language (MUST/SHOULD/MAY) for clarity
Reference existing implementations that already follow the convention

Acceptance Criteria

Draft document covering all 5 sections above
At least 2 concrete examples
Reviewed against existing implementations for compatibility (skilljack, NimbleBrain, FastMCP)
Reviewed by at least 2 IG facilitators before merge
Added to the README documents table

References

Approach 6
Design Principles
Implementations in docs/related-work.md
Work Tracking in README: "MCP Skills Convention v0.1 — Proposed — TBD"

Input dependencies added: The following new issues provide structured inputs for the convention draft:

Extract testable requirements from use cases and open questions #46 — Extract testable requirements from use cases and open questions
Create evaluation matrix mapping approaches to requirements #47 — Create evaluation matrix mapping approaches to requirements

The requirements document (#46) establishes the criteria the convention should satisfy, and the evaluation matrix (#47) maps how each approach performs against those criteria. Both feed directly into this convention work.

@pja-ant

Linking active PRs toward this convention:

Add draft SEP for Skills Extension #69 — @pja-ant's draft SEP for the Skills Extension covers the scope outlined here (URI scheme, content format via agentskills.io delegation, control model guidance, server instructions, and extension declaration). This is the most direct work-in-progress toward the v0.1 convention.
Update URI scheme proposal to decouple path from skill name #70 — @pja-ant's URI scheme update (decoupling path from skill name) aligns the URI proposal with the SEP draft above — addresses Section 1 (Skill Resource Discovery) of this issue's scope.

Closing — scope fulfilled and superseded by the Skills Extension SEP

This issue's scope has been addressed by the draft SEP in #69 and related PRs, though the deliverable evolved from "convention document" to "formal Extensions Track SEP." Here's how:

What changed from the original scope

Section	Original Scope	What Happened
1. URI scheme & discovery	`skill://` or well-known naming, `resources/list`	Evolved to multi-segment paths (`acme/billing/refunds/SKILL.md`), `skill://index.json` well-known index resource, optional enumeration. Scoped `resources/list` was not used.
2. Content format	Define required/recommended frontmatter in convention	Delegated entirely to agentskills.io — the SEP is a transport binding only, not a format spec.
3. Control model	App-controlled vs model-controlled guidance	Resources are primary; hosts provide `read_resource` tool for model-driven loading. No hard rules — left to implementations.
4. Server instructions	Required instruction text patterns	Documented as optional pointer pattern, not a required format.
5. Update notifications	Skill-specific subscribe/notify	Inherits standard MCP `resources/subscribe` / notify infrastructure. No skill-specific mechanism needed.

Why "convention" became "SEP"

Four independent implementations converged on skill:// without coordination, signaling that a convention was already emerging organically. The divergence between those implementations (different URI structures, discovery paths) created risk that an informal convention would lock in incompatible patterns. Since the SEP requires zero protocol changes (uses existing Resources primitive), there was no downside to formalizing sooner.

New concerns the SEP addresses that weren't in this issue

Security/trust model — skills are untrusted model input; no implicit local execution
_meta scoping — transport-only metadata, not skill semantics
No-nesting constraint — SKILL.md cannot be ancestor of another
Backward compatibility — existing clients see skills as ordinary resources

Active PRs

Add draft SEP for Skills Extension #69 — Draft SEP for Skills Extension (primary deliverable)
Update URI scheme proposal to decouple path from skill name #70 — URI scheme update aligning with the SEP
Add TypeScript SDK for the Skills Extension SEP #71 — Reference implementation demonstrating the SEP end-to-end

Update docs to reflect convention-to-SEP evolution

Navigation Menu

Repository navigation

Draft MCP Skills Convention v0.1 #43

Background

Scope

1. Skill Resource Discovery

2. Skill Content Format

3. Control Model Guidance

4. Server Instructions Pattern

5. Update Notifications

Format

Acceptance Criteria

References

Closing — scope fulfilled and superseded by the Skills Extension SEP

What changed from the original scope

Why "convention" became "SEP"

New concerns the SEP addresses that weren't in this issue

Active PRs

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Draft MCP Skills Convention v0.1 #43

Description

Background

Scope

1. Skill Resource Discovery

2. Skill Content Format

3. Control Model Guidance

4. Server Instructions Pattern

5. Update Notifications

Format

Acceptance Criteria

References

Activity

olaservo commented on Mar 3, 2026

olaservo commented on Apr 13, 2026

olaservo commented on Apr 13, 2026

Closing — scope fulfilled and superseded by the Skills Extension SEP

What changed from the original scope

Why "convention" became "SEP"

New concerns the SEP addresses that weren't in this issue

Active PRs

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions