$cat skills-are-the-new-sdks.md

Skills Are the New SDKs: Teachability Is the New Moat

July 28, 202615 min readby MDflowview as .md

A small emerald wireframe card unfolding into three progressively larger layered panels streaming into a geometric AI core, beside a dark closed toolbox crate, on a black terminal-grid background

For twenty years, the way you made your product usable by other people's software was to ship an SDK: a versioned client library, an API reference, a quickstart, and a lot of hope that a developer would read enough of it to get the first call right. That contract assumed a human on the other end — someone who could skim, guess, Google the error, and try again.

In 2026, an enormous share of the traffic hitting your documentation is not a human. It is a coding agent, mid-task, with a finite context window and no ability to go look it up. That single change is why the integration artifact is being rewritten — and why the phrase from Elvin Aghammadzada's talk at the AI Engineer conference, Skills are the New SDKs, lands so hard.

TL;DR — Skills are the new SDKs: the thing you ship so other software can use your product is no longer a client library a developer installs, it is a folder of plain markdown an agent loads on demand. That flips the strategic question from how hard is it to leave my platform to how fast can an unfamiliar agent get a right answer from it — call it teachability. Products win on fluency now, not friction. MDflow is the markdown-native, agent-readable workspace where that operational knowledge lives, retrievable over MCP and an HTTP API.

What "skills are the new SDKs" means

"Skills are the new SDKs" means the unit of integration has changed shape: the same job an SDK used to do — package your product's operational knowledge so someone else's software can use it correctly — is now done by a folder containing a SKILL.md file. Same job, different reader, therefore a different artifact.

An Agent Skill is a directory with a markdown entry file: YAML frontmatter carrying a name and a description, then a body of plain instructions, plus optional scripts and reference files. Anthropic published the specification openly at agentskills.io in December 2025, and governance sits with the Agentic AI Foundation under the Linux Foundation — the same neutral body that stewards MCP. By mid-2026 roughly 32–40 platforms had adopted it, including Claude Code, OpenAI Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, Goose, and JetBrains Junie.

The comparison to an SDK is closer than it first sounds:

	SDK	Agent Skill
Reader	Human developer	AI agent
Artifact	Versioned package (npm, PyPI, Maven)	Folder with `SKILL.md` + optional scripts
Distribution	Package registry	Repo, marketplace, or a shared workspace
Load model	`install` → `import` → call	Description at startup → body on match → files on demand
Encodes	Types, methods, auth plumbing	When to act, how to think, what "correct" looks like
Failure mode	Compile error	Wrong answer, confidently

The last two rows are where the analogy earns its keep. An SDK encodes the mechanics of your API and leaves the judgment to the developer. A skill has to encode the judgment too, because there is no developer downstream to supply it.

Why an SDK is the wrong shape for an agent

Because an SDK assumes a reader who can go find what is missing, and an agent cannot. Three specific mismatches make this concrete.

Documentation is written for human intuition. Docs work because a person can skim, form a hypothesis, hit an error, search for it, and correct. An agent gets one pass at whatever fits in its window. As the talk put it, docs require intuition and follow-up questions — capabilities a model does not have unless you build a context engine around it.

Context is a budget, not a warehouse. The marketing promise of million-token windows quietly implies you can dump everything in and let the model sort it out. Chroma's context rot study tested 18 frontier models and found reliability degrades continuously as input grows — well before the window is full, on tasks as simple as retrieval and text replication. Every irrelevant file you load is not free storage; it is attention taken from the thing that matters.

Eagerly-loaded tool definitions eat the budget first. The MCP-native way to expose a product is a set of tools whose schemas are loaded up front. Community measurements on the MCP specification repository put a typical tool schema near 1,000 tokens, so a handful of connected servers can occupy tens of thousands of tokens before the user's first message. Anthropic's own code execution with MCP write-up shows a workflow dropping from 150,000 tokens to 2,000 by loading definitions on demand instead of up front.

A skill's answer to all three is progressive disclosure — its equivalent of install → import → call. The agent sees only the ~100-token name and description of every installed skill at startup; it loads the full markdown body when a task actually matches; and it reads bundled scripts or reference files later still, if the body points at them. You pay for a capability at the moment you use it, which is exactly what an import statement buys you in a language runtime and exactly what a preloaded tool schema does not.

Teachability: the new line on the evaluation checklist

Teachability is how quickly an unfamiliar agent can acquire the operational knowledge to use your product correctly — and get a right answer on its first attempt. That is the sharpest idea in the talk, and it is a strategic one, not a technical one.

Think about what an enterprise checks before adopting a platform: security posture, compliance certifications, data residency and governance, SLA guarantees, logging and tracing, whether it integrates with the internal auth layer. Teachability is the new item on that list. If a team's agent harness meets your product for the first time, does it produce a correct result in seconds, or does it produce a plausible wrong one?

This reframes what a moat is. The SaaS-era moat was friction: proprietary formats, deep integrations, migration pain — make leaving expensive. That moat is eroding, and the erosion is being done by the same agents. When a coding agent can port a large codebase between languages in days, "we are hard to leave" is a depreciating asset.

Skills point at the opposite kind of moat, which the talk calls fluency. Experience is roughly the friction between intent and outcome; a good skill removes friction from that gap, and every skill you publish compounds the effect. A friction moat is defensive — people stay because leaving hurts. A fluency moat is offensive — people stay because the thing works on the first try, every time, for whatever agent they happen to be driving. One is a wall; the other is a habit.

The practical consequence for anyone building a product in 2026: your integration story is now partly a writing problem. The best-documented, most teachable product wins evaluations you never knew were happening, because the evaluation was an agent reading your surface at 2am.

Why this matters for developers and for AI agents

For developers, three things change:

You author capability instead of building agents. If a general-purpose coding agent plus a folder of skills can serve a supply-chain use case or a manufacturing one, you stop building a bespoke agent per domain and start writing skills on top of one good engine. The talk makes this point bluntly, and the industry's most-starred agent repositories are effectively demonstrations of it.
Skills are software, so treat them like software. Version them, review them, evaluate them, test them. A skill is only as good as the human who wrote it — and there is early evidence that machine-generated skills can hurt performance, burning more tokens and more reasoning time than they save. Auto-generation is not the win; curation is.
The supply chain is young. Skills execute on your machine with your agent's permissions. Marketplaces have limited verification, prompt injection is a live risk, and the whole ecosystem feels roughly like npm a decade ago. Read skills before installing them, pin what you trust, and prefer sources you can audit.

For AI agents, the change is simpler: a skill is the right amount of context, at the right moment. Instead of an agent starting each session already deep into degraded performance because fifteen servers announced themselves, it starts lean and pulls in exactly the operational knowledge the current task needs. That is context engineering expressed as a file format.

Which products benefit most from being teachable

Developer platforms and APIs. The teams whose docs are already being read by agents more than by people. A skill turns "here are 200 endpoints" into "here is how to do the five things you actually came for."
Data and analytics platforms. Query dialects, schema conventions, and metric definitions are exactly the judgment-shaped knowledge an SDK cannot carry.
Internal tooling and platform engineering. Deployment runbooks, incident procedures, environment quirks — the institutional knowledge that lives in three people's heads and one stale wiki.
Regulated and enterprise software. Where getting it approximately right is worse than not answering, and the operational knowledge is the product.
Any product with a house style. Brand voice, document templates, review standards, code conventions: the "how we do it here" that a generic model will otherwise cheerfully invent.

Skills and MCP are not competing

Both come from Anthropic, and they answer different questions. MCP defines what actions an agent can take, and gives you hosted execution, authentication, and access to resources the agent's own machine cannot reach — a GPU, a 400-terabyte index, a system behind your firewall. A skill defines how to think about a task, and runs as instructions on the agent's side.

They compose neatly. A skill can teach an agent when a particular MCP server is the right tool and how to call it well — which means the server's tool definitions arrive on demand rather than sitting in context from the first token. Use a skill when the hard part is reasoning and judgment. Use MCP when the hard part is access, authentication, or horsepower. Most serious setups need both, which is also the argument in our post on MCP and A2A as agentic interfaces.

How MDflow fits

Skills are markdown. Teachability is a writing-and-retrieval problem. MDflow is a markdown workspace that both people and agents can read and write — which makes it a natural home for the operational knowledge your skills are made of.

What already lines up today

The storage format is the artifact format. MDflow documents are plain markdown with YAML frontmatter — byte-for-byte the shape of a SKILL.md. Draft a skill in the editor, keep the canonical version in a workspace, and there is no export step between "the document we maintain" and "the file an agent reads."

Folder descriptions are progressive disclosure for a knowledge base. Every MDflow folder carries a description of what its documents are for. That description is the cheap index; the document bodies are the expensive payload. mdflow_get_context ranks folder descriptions above folder names and titles, then returns only the best-matching bodies — the same "metadata first, body on match" instinct a skill's frontmatter encodes, applied to a whole workspace. No vector database required.

Agents read and write over MCP, an HTTP API, and raw .md twins. Claude and the ChatGPT app connect to MDflow's remote MCP server with an OAuth sign-in; Claude Code, Cursor, and Codex authenticate with a Personal Access Token. Every document also has a raw .md twin served over open CORS, so any tool, CI job, or agent that can fetch a URL gets the canonical text. And because writes are supported, an agent that learns something during a run can propose it back instead of losing it.

Version history makes skills reviewable. If a skill is software, it needs the discipline of software. Every write path — editor, API, MCP — captures the previous version, with line-by-line markdown diffs and non-destructive restore, so a skill an agent edited is a change you can read and roll back rather than a silent mutation.

MDflow practices teachability on itself. It publishes an llms.txt, an agent card, an OpenAPI spec, a plain-markdown /docs.md control guide, and .md twins of every page — including this one, at /blog/skills-are-the-new-sdks.md. That is the whole argument in miniature: an agent should be able to learn to operate MDflow correctly without a human in the loop.

Honest scope: MDflow is where the knowledge lives and how agents retrieve it. It is not a skill runtime — it does not execute bundled scripts or install skills into your agent. It stores, versions, governs, and serves the markdown; your agent harness does the running.

Where we are headed

Direction, not a dated commitment: serving a whole collection of related documents to an agent as one cross-linked bundle, so a set of related runbooks or standards retrieves together the way a skill folder does; richer typed frontmatter so shared documents carry status, owner, and version as structured metadata; and tighter round-trips for agent-proposed changes that a human reviews before they land.

The bottom line

The SDK is not dead, but it is no longer the thing that decides whether your product gets used. Skills are the new SDKs because the reader changed: a folder of plain markdown, loaded progressively, teaches an agent what a client library used to teach a developer. And once agents are the ones evaluating you, teachability — how fast an unfamiliar agent gets a right answer — becomes a line on the checklist next to SLAs and SOC 2.

Context is a budget. Longer windows do not fix that. Skills complement MCP rather than replacing it. And a skill is only as good as the human who wrote it — which means the durable investment is not the format, it is the operational knowledge you write down and keep current.

Start free · Connect an AI agent · Read the API docs

Frequently asked questions

What does "skills are the new SDKs" mean?

It means the unit you ship so other software can use your product has changed. An SDK is a versioned client library a human developer installs and writes code against. An agent skill is a folder with a SKILL.md file — plain markdown instructions, plus optional scripts and reference files — that an AI agent loads on demand and follows. The job is the same, packaging your product's operational knowledge for someone else's software, but the reader changed from a human developer to a model, so the artifact changed from compiled code to readable text.

What is teachability in the context of AI agents?

Teachability is how quickly an unfamiliar AI agent can pick up the operational knowledge needed to use your product correctly, and get a right answer on its first attempt. It is becoming a procurement criterion alongside security, compliance, SLAs, and integrations, because in 2026 a large share of the traffic evaluating your product is an agent reading your docs rather than a human following a tutorial. A skill is the concrete artifact that makes a product teachable.

Do agent skills replace MCP servers?

No. They solve different problems and both come from Anthropic. MCP defines what actions an agent can take and provides hosted execution, authentication, and access to resources the agent's own machine does not have. A skill defines how to think about a task and runs on the agent's machine as instructions. In practice they compose: a skill can teach an agent when and how to use an MCP server, so the server's tool definitions are loaded on demand rather than sitting in context from the first token.

Why do agent skills use less context than loading many MCP tools?

Progressive disclosure. A skill exposes only its name and description at startup — roughly 100 tokens — and loads the full markdown body only when a task matches, with bundled scripts and reference files read later still. MCP tool schemas are traditionally loaded up front, and community measurements on the MCP spec repository put a typical schema near 1,000 tokens per tool, so a handful of servers can occupy tens of thousands of tokens before the first user message. Anthropic's own code-execution write-up shows one workflow dropping from 150,000 tokens to 2,000 by loading definitions on demand instead.

Is Agent Skills an open standard?

Yes. Anthropic published the Agent Skills specification openly at agentskills.io in December 2025, and governance sits with the Agentic AI Foundation under the Linux Foundation — the same body that stewards MCP. Roughly 32 to 40 platforms had adopted it by mid-2026, including Claude Code, OpenAI Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, Goose, and JetBrains Junie, so a skill you write once is portable across agents.