Draft MCP Skills Convention v0.1

[olaservo]

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"

[olaservo]

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.