Here's a pattern I keep seeing: a team connects their agent to an MCP server with 30 tools, points the agent at a task, and watches it flail. The agent calls the wrong tool, passes malformed parameters, retries the same failed approach three times, then hallucinates a workaround. The tools are there. The API is correct. The agent just doesn't know what it's doing.
The MCP 2026 roadmap introduces something designed to fix exactly this: Skills. And if you're building anything with agents, you need to understand why this primitive exists and what it means for how you design your integrations.
The Problem: Tool Definitions Are Not Knowledge
A tool definition tells an agent what a function does. It describes the parameters, the return type, maybe a brief description. That's fine for simple operations — get_user(id) doesn't need much explanation. But real systems aren't simple.
Consider a Jira MCP server with 40 tools. The tool schemas tell you there's a create_issue function that takes a project key, summary, issue type, and optional fields. What the schema doesn't tell you:
- That epic links require the issue type "Epic" and the
epicNamefield must be set - That story points go in
customfield_10016, not a field called "storyPoints" - That transitions must follow the workflow — you can't jump from "In Progress" to "Done" without going through "In Review" first
- That the
assigneefield needs an account ID, not a username, and that ID comes from a separate API call
Every one of these details is the difference between an agent that completes a task in one shot and an agent that burns through your token budget failing repeatedly. The tool schema says what. The agent needs to know how.
Today, teams handle this by stuffing instructions into prompts. "When creating Jira issues, always set customfield_10016 for story points. Epic links require the epicName field. Transitions must follow..." It works, sort of. Until the prompt gets too long, or the instructions go stale, or you need the same knowledge across three different agents and now you're copy-pasting paragraphs between system prompts.
What Skills Actually Are
Skills are a new MCP primitive that lets a server bundle domain-specific instructions and operational knowledge alongside its tools. Think of it as the server shipping its own documentation — not as a separate wiki page, but as structured data that the agent can query at runtime.
A tool schema says: "Here's create_issue, it takes these parameters." A skill says: "Here's how to create a well-formed Jira epic — which tool to use, what fields matter, what order to set them in, and what common mistakes to avoid."
The distinction is critical. Tools describe capabilities. Skills describe competence. An agent with access to 40 Jira tools but no skills can technically do anything in Jira. An agent with skills can actually do it correctly.
This maps directly to something I wrote about in Harness Engineering: the difference between giving an agent access to tools and giving it the context to use those tools well. The harness principle of Inform — give the agent the right context at the right time — is exactly what Skills implement at the protocol level. Instead of you manually curating context files, the server itself becomes a context provider.
Why This Matters Now
Three things are converging that make Skills more than a nice-to-have:
First, agents are moving beyond coding. The coding-agent wave of 2025 was unusually forgiving. Your agent runs locally, it can call a compiler to check its work, and a developer is sitting right there to catch mistakes. General knowledge-work agents — the ones connecting to Salesforce, SAP, Snowflake, internal wikis — don't have that luxury. A malformed API call to your CRM doesn't fail with a helpful error message; it creates a corrupted record that someone discovers three weeks later.
Second, MCP servers are getting large. The early MCP ecosystem was filesystem and database connectors — five tools, obvious parameters. Now we're seeing servers for entire platforms: Jira, Salesforce, Slack, ServiceNow, SAP. Forty-plus tools per server is becoming normal. No agent can figure out 40 tools from schema definitions alone. It needs the operational knowledge that currently lives only in the heads of experienced users.
Third, the protocol layer is settling. A2A merged with ACP under the Linux Foundation. MCP crossed 200 server implementations and was donated from Anthropic to the Linux Foundation in December 2025. The infrastructure is stabilizing, which means the bottleneck is shifting from "can we connect?" to "can the agent do useful work once connected?" Skills address the second question directly.
How to Think About Designing Skills
If you're building an MCP server — and if you're building any kind of agent integration in 2026, you probably should be — here's how to think about Skills:
Design skills around workflows, not tools. A skill shouldn't map 1:1 to a tool. It should map to something a user actually wants to do. "Create a production incident" is a skill. It might involve calling create_issue, then set_priority, then add_watcher, then send_notification. The skill bundles that sequence with the knowledge of how to compose it correctly.
Include failure modes. The most valuable knowledge isn't how things work when they work — it's what to do when they don't. A good skill includes common error patterns and recovery strategies. "If create_issue returns a 400 with 'project required', the project key format is uppercase letters followed by a number. You can list available projects with list_projects."
Keep skills composable. Skills are the atomic capability units in an agent system. They should be small enough to combine but complete enough to be useful independently. "Create an epic" and "Link an issue to an epic" should be separate skills, because not every workflow that creates an epic also links issues to it.
Treat skills as code, not docs. Skills will be versioned, tested, and updated alongside your server. If you rename a field in your API, the skill should be updated in the same commit. The alternative — maintaining prompt instructions in a separate system — is exactly the kind of staleness problem Skills are designed to solve.
Skills vs. Tools vs. Everything Else
The agent building blocks are multiplying, and the boundaries matter:
- Tools are API calls. "Here's a function, here are its parameters." Stateless, mechanical, no opinion about how to use them.
- Skills are workflow knowledge. "Here's how to accomplish X using these tools." Stateful in the sense that they encode sequences and dependencies.
- Resources are data. "Here's the current state of the system." Read-only context.
- Subagents are delegation. "Here's a specialized worker with its own context and tools." For decomposing complex tasks.
- Hooks are lifecycle control. "Before you call that tool, run this check." For guardrails and cross-cutting concerns.
The hierarchy is real: tools provide raw capability, skills provide competence, resources provide context, subagents provide parallelism, and hooks provide safety. You need all of them for a production agent. But skills are the piece that was missing — the bridge between "the agent can technically do this" and "the agent actually knows how."
The Boring Technology Angle
There's a connection here to something the OpenAI harness engineering team discovered: agents perform better with well-documented, widely-used technologies because those technologies have more representation in training data. Skills extend that principle to your own APIs.
Your internal API isn't in any training set. No amount of model improvement will teach an agent that your company's customfield_10016 is story points. Skills let you inject that knowledge at the protocol level, making your bespoke API as legible to the agent as a well-known public one.
This is also why Skills matter for local and self-hosted agents. If you're running models locally with Ollama or vLLM, you're already dealing with models that have less training data coverage than frontier models. Skills compensate by providing the domain knowledge that the model couldn't have learned during training. You get the privacy benefits of local inference without sacrificing agent competence.
What to Do This Week
Skills are on the MCP 2026 roadmap with specification work underway. The June 2026 spec cycle is expected to finalize the transport and primitive definitions. Here's what you can do now:
- Audit your MCP servers. Which ones have more than 10 tools? Those are the ones where agents are most likely to flounder. Start there.
- Document your top 5 workflows. Not tool schemas — the actual sequences of operations a knowledgeable human performs. The steps, the edge cases, the common mistakes. This documentation is the raw material for skills.
- Prototype skill definitions. Even before the spec finalizes, you can structure your workflow documentation in a skill-like format: name, description, required tools, step sequence, error recovery, and example invocations. When the spec lands, you'll be ready to convert.
- Watch the June spec cycle. Stateless transport and skills are both expected in the June 2026 specification update. Once the spec is finalized, SDK support will follow quickly.
The teams that start treating agent competence as a first-class design concern now — instead of relying on bigger prompts and hoping for the best — will be the ones shipping reliable agent integrations six months from now. Everyone else will still be debugging why their agent keeps putting story points in the wrong field.