Skills as a first-class MCP primitive/capability

[Reecepoulsen]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

MCP Skills Primitive — Feature Specification

Related discussions:

• #1779 skills replacing prompts
• #631 progressive disclosure
• #1576 token bloat mitigation
  This proposal takes a different angle — rather than extending prompts or compressing tool schemas, it defines skills as a distinct primitive with its own semantics, focused on the separation between expertise and execution.

Summary

This proposal introduces a first-class skills primitive to the Model Context Protocol. Skills are discrete units of expertise that a model can discover through lightweight descriptions and load on demand to shape how it approaches a task. MCP is the natural distribution layer for skills, but currently lacks the semantics to support them. Adding skills/list and skills/get fills this gap while advancing a broader case for progressive disclosure in the protocol.

Defining Skills

A skill is not a folder, a file, or a package. Those are implementation details of current local-first implementations. A skill is a contract: it promises to deliver a description for discovery and content for guidance. How it fulfills that contract — local folder, MCP server, git submodule — is an implementation choice.

The essence of a skill is: a discrete unit of expertise that a model can discover through a lightweight description and load on demand to change how it approaches a task. This definition is deliberately independent of delivery mechanism, because tying the concept to a specific packaging format limits how skills can be distributed, shared, versioned, and managed.

Skills and Tools: Expertise vs. Execution

Skills and tools solve different problems with a clean, complementary relationship.

A tool is a capability. It does something — queries an API, mutates state, authenticates against a service. Tool definitions tell the model what a tool does and what parameters it takes, but they cannot teach the model how to use it well. Tool descriptions are terse by design because they sit in context permanently.

A skill is expertise. It teaches the model when to use which tool, why, and what patterns to follow. A skill provides the rich documentation and guidance layer that tool schemas were never meant to be.

The relationship flows one direction. Skills reference tools, but tools don't reference skills. A tool is a generic capability that doesn't care whether the model was guided by a skill. This keeps tools simple while skills can be opinionated and context-specific. Multiple skills can reference the same tool differently — one teaching conservative production patterns, another teaching rapid prototyping — same tool, different expertise.

This separation becomes especially clean in MCP contexts. When a server provides both skills and tools, instructional content flows through skills/get and executable capabilities flow through tools/call. Authentication, session management, and state mutation are handled at the protocol level through tools, rather than embedded in skill content. This doesn't mean skills are inherently incapable of side effects — local skill implementations may include scripts that do all sorts of things. But MCP provides an opportunity to formalize the separation, making the boundaries between expertise and execution explicit and consistent.

Problem Statement

Today, skills are limited to local filesystem delivery. There is no standardized way to distribute, share, version, or centrally manage skills across teams or environments.

MCP is the natural distribution layer, but existing primitives fall short:

Tools (tools/list + tools/call): Every tool definition is injected into context on every request, defeating the lazy-loading property that makes skills efficient. Tool semantics also imply execution — skills are instructional.

Resources (resources/list + resources/read): Clients have no way to know a resource should be treated as instructional content rather than data. Without that semantic signal, clients cannot integrate resources into their skill-loading machinery.

Prompts (prompts/list + prompts/get): Prompts are user-facing templates. The interaction model — user selects a prompt — doesn't match the skill pattern, where the model decides when to load.

The core issue is that MCP is push-based at the discovery layer. Everything a server offers gets advertised into context whether the current conversation needs it or not. Skills require the discovery index to be present but the content to be pull-based. No existing primitive communicates this intent to the client.

Progressive Disclosure

This context bloat problem extends beyond skills. When a client connects, it calls tools/list, resources/list, and prompts/list, and everything comes back at once. Most clients include all of it in context because the protocol doesn't give them enough semantic information to be selective.

With a small tool surface this is manageable. As users connect multiple servers with dozens of tools each, thousands of tokens are consumed by definitions before the conversation starts.

The skills primitive is a natural wedge for progressive disclosure in the protocol. Skills are the clearest case where lazy loading is the entire point — the index is always present, the content is on demand. If the spec adopts this pattern for skills, it establishes a precedent that can extend to tools and resources over time.

Proposed Solution

Add a skills capability with two operations:

skills/list returns a compact index of available skills — name, description, and optional metadata. This index is injected into the system prompt by the client, occupying minimal context. Descriptions give the model enough information to decide when a skill is relevant.

skills/get returns the full content of a named skill — instructional content that the model reads and internalizes before proceeding. Fetched on demand, not preloaded.

Client Behavior

1. On connection to a server advertising the skills capability, the client calls skills/list.
2. The client incorporates the index into the system prompt, identically to how local skills are represented.
3. When the model determines it needs a skill, it signals the client.
4. The client calls skills/get, retrieves the content, and presents it as instructional context.
5. The model internalizes the guidance and proceeds, using whatever tools are available.

From the model's perspective, MCP-delivered skills and local skills are indistinguishable.

Schema

skills/list Response

{
  "skills": [
    {
      "name": "api_error_handling",
      "description": "Patterns for consistent error handling across REST API endpoints. Use when building or reviewing API error responses, retry logic, or status code conventions.",
      "version": "1.2.0"
    }
  ]
}

Required: name, description. Optional: version, metadata.

The description field is critical — it is the primary mechanism by which the model decides whether to load a skill.

skills/get Request / Response

// Request
{ "name": "api_error_handling" }

// Response
{
  "name": "api_error_handling",
  "version": "1.2.0",
  "content_type": "text/markdown",
  "content": "# API Error Handling Patterns\n\n## Overview\n\nAll API endpoints should follow consistent error handling...\n\n..."
}

Why Not Conventions on Existing Primitives?

No client support without spec backing. Clients will not implement special handling for a naming convention. A spec-level primitive gives client teams a clear contract to implement against.

Inconsistent implementations. Without a standard, every team invents it differently — different naming, metadata shapes, and trigger mechanisms, making skills non-portable.

No semantic signal. Resources say "here is data." Skills say "here is how to behave." That distinction matters for context management, observability, and client behavior. A naming convention cannot change how a client processes content.

Additional Considerations

Co-delivery of expertise and capabilities. A single MCP server can provide both the tools to interact with a system and the skills to use those tools well. This means platform vendors, teams, and open source projects can distribute capabilities and best practices together through one integration point. Users connect to a server and get not just the tools but the expertise to use them effectively — without maintaining separate skill files alongside their MCP configuration.

Versioning and caching. The version field enables clients to cache content and re-fetch only when versions change.

Observability. A dedicated primitive lets clients track which skills are loaded, how often, and whether they improve output quality.

Capability negotiation. Servers advertise skills as a capability during initialization. Clients that don't support it simply ignore it.

Authoring simplicity. Creating and publishing a skill via MCP must be as approachable as writing a markdown file today. Pointing a server at a directory of markdown files should be sufficient.

Summary

Skills are expertise. Tools are execution. Both are essential, and MCP can distribute both, but currently only has primitives for the execution side. Adding skills/list and skills/get enables model-side skill selection with no intelligence offloaded to the server, lazy content loading with zero context bloat beyond the index, portable skill distribution across teams and environments, and a foundation for progressive disclosure that can extend across the protocol.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[olaservo]

Hi @Reecepoulsen and others on this thread - wanted to link to the Skills Over MCP interest group which is actively exploring these topics: https://github.com/modelcontextprotocol/experimental-ext-skills