When to Write a Skill vs an MCP Server

The Confusion Costing You Time: Why Builders Pick the Wrong Layer

You've spent three days wiring up an MCP server. It connects to your database, authenticates, streams results back to your agent. Then you discover a single SKILL.md file could have done the same thing for your use case in an afternoon.

That kind of wasted effort is now common across the agent-building community. Skills and MCP get pitched as rivals, but they're actually complementary layers of the same architecture: Skills teach an agent how to do something, while MCP servers give an agent access to external systems. Anthropic's own documentation puts it plainly: MCP connects Claude to external services and data sources, while Skills provide procedural knowledge — instructions for completing specific tasks. Block's Goose team captures the division in a single line: "Skills describe the workflow. MCP provides the runner."

The token-cost gap explains why the wrong choice hurts so much. Each Skill loads only a few dozen tokens of frontmatter metadata at session start — roughly 50 to 100 tokens — with the full SKILL.md body deferred until the model decides to trigger it. GitHub's official MCP, by contrast, famously consumes tens of thousands of tokens of context, leaving precious little room for the model to do useful work. That asymmetry has real consequences when you're stacking capabilities.

Skepticism is growing among people who have watched the space closely. Armin Ronacher, creator of Flask, put it bluntly: "many MCP servers don't need to exist. They're either bad API wrappers or they're actually truly replaceable by a skill." Simon Willison, who has tracked MCP adoption since launch, admits his own interest in MCPs has waned since he started taking coding agents seriously, noting that almost everything he might achieve with an MCP can be handled by a CLI tool instead.

So where does that leave builders? A practical triage rule emerges from the research:

• Write a Skill when the need is a repeatable workflow, output format, compliance standard, or domain expertise — and no live external data or authentication is required.
• Write an MCP server when the agent must reach external systems, manage credentials server-side, or need centralized observability and governance.
• Use both together when a Skill describes the workflow and an MCP server provides the tools that workflow references.
• Never implement a Skill as an MCP server — doing so negates progressive disclosure and adds protocol overhead to what should be a simple filesystem read.

The cost of picking the wrong layer isn't just wasted days. It's context-window bloat, security surface you didn't need, and a system that's harder to maintain six months later. If you're evaluating skills for your own agents, browsing a free, independently verified directory can save you from installing something that doesn't fit your architecture — or worse, something that carries hidden vulnerabilities.

The Triage Rule: Workflow vs Connectivity

The fastest way to waste a week is to build an MCP server for something that should have been a folder of Markdown. The consensus across Anthropic, Speakeasy, and the dev.to agent-skills guide is blunt: Skills teach an agent how to do something, while MCP servers give it the ability to reach external systems.

The triage rule is simple. Write a Skill when the need is a repeatable workflow, an output format, a compliance or brand standard, or domain expertise that should stay portable and reviewable — and when no live data or authentication is involved. Write an MCP server when the agent must talk to databases, REST APIs, or remote file systems, when credentials need to live server-side, or when you need centralized observability and governance. Block's Goose team frames it well: "Skills describe the workflow. MCP provides the runner."

Token economics reinforce the default. Skills load only a few dozen tokens of metadata at session start, according to Simon Willison's analysis, while GitHub's official MCP alone famously consumes tens of thousands of context tokens. That gap explains why so many builders reach for Skills first.

The clearest anti-pattern: never implement a Skill as an MCP server. Exposing Skills through MCP negates progressive-disclosure benefits and bolts protocol overhead onto what should be a simple filesystem read. Skills are folders, not servers.

• Repeatable process, no live data → Skill
• External system, credentials, or audit trail → MCP server
• Workflow that calls tools → Skill describing it, MCP providing them
• Skill wrapped in an MCP server → don't

At organizational scale, MCP earns its overhead for four reasons: credentials, observability, blast radius, and updates. As SkillzBench builds its free directory and verification pipeline, that same lens — what a skill touches, what it can reach — is exactly how agent capabilities should be vetted before they ship.

When Scale Changes the Answer: Credentials, Audit and Blast Radius

For a single developer, the argument that "skills plus a code sandbox equals MCP" holds up reasonably well. At organizational scale, it collapses — and Speakeasy's analysis names four reasons why: credentials, observability, blast radius, and updates.

The credential problem is the sharpest. Skills run inside a sandbox that already holds access to your environment, so every agent inherits raw secrets rather than negotiated access. As the Speakeasy team puts it, the difference between "every agent has access to raw secrets" and "no agent ever touches a credential" is the difference between a security model and a security incident. MCP servers, by contrast, manage authentication server-side and log, rate-limit, and audit every call centrally — sandbox code is a black box by comparison.

Blast radius matters just as much. MCP's defined tool schemas constrain what a prompt injection can achieve, whereas a malicious Skill can direct an agent to invoke tools or execute code in ways that don't match its stated purpose — a risk Anthropic documents directly in its Agent Skills security guidance. Tool poisoning on the MCP side is a real threat too, but it is at least a threat you can observe and revoke.

Updates complete the case. One MCP server update propagates org-wide; distributed skill files drift, silently, across every machine that copied them.

Simon Willison, who calls Skills' simplicity the reason he's excited about them, still warns that sandboxing against prompt injection remains an open problem — we haven't figured out how to limit such attacks to an acceptable amount of damage. That warning lands hardest on business owners, who carry the liability, not the developer who wrote the file.

• Credentials: MCP keeps secrets server-side; sandboxes hand them to every agent
• Observability: MCP calls are logged and auditable; sandbox execution is not
• Blast radius: defined schemas constrain injection damage that Skills cannot
• Updates: one server update propagates; copied skill files drift

None of this makes Skills the wrong choice — it makes them the wrong choice for anything touching credentials, audit, or organizational risk. For everything else, they remain the leaner option, and vetting them like software is the baseline. SkillzBench is building a free directory and MCP connector around exactly that discipline: pinning versions, security-scanning, and benchmarking every skill before it reaches an agent.

Better Together: Combining Skills and MCP in Real Architectures

The strongest agent architectures don't choose between Skills and MCP — they layer them. Anthropic's own documentation puts it plainly: MCP connections give agents access to tools, while Skills teach agents how to use those tools effectively. Block's Goose team compresses the same idea into one line: "Skills describe the workflow. MCP provides the runner."

Three patterns recur in real architectures. The first is Skills as MCP orchestrators. A "deploy and notify" Skill, for example, doesn't need its own connectivity — it drives MCP connections to GitHub, your CI/CD pipeline, and Slack, sequencing them into a repeatable release ritual. The MCP servers supply reach; the Skill supplies judgment about what order to do things in and what "done" looks like.

The second pattern is Skills that encode organizational standards for MCP tool use. A GitHub MCP server will happily create branches and open pull requests, but it won't know your branch-naming convention or your PR checklist. A Skill bundles those house rules so every agent invocation follows them consistently — the kind of compliance and formatting knowledge that analysis of Skills vs MCP architectures identifies as squarely Skill territory.

The third is the hybrid: a Skill with embedded scripts that call MCP servers directly, combining procedural knowledge with live access in one package.

The clearest worked example is a database. An MCP server exposes a run_query tool against PostgreSQL — that's the capability. But the tool alone knows nothing about your schema, your edge cases, or what "safe SQL" means for your data. Pair it with a database-query Skill that documents safe query patterns and schema-specific pitfalls, and the agent suddenly uses that tool well. As the Speakeasy author puts it: "The MCP servers give agents access. The skills give agents judgment."

• Orchestrator Skills sequence multiple MCP tools into one repeatable workflow.
• Standards Skills teach agents your conventions for using shared MCP tools.
• Hybrid Skills embed code that calls MCP servers directly.

One caution applies across all three patterns: vet any Skill before wiring it to live systems. Anthropic warns that a malicious Skill can direct Claude to invoke tools in ways that don't match its stated purpose — a bigger risk when those tools touch real infrastructure. SkillzBench is building exactly this vetting layer: a free directory where every skill is security-scanned, version-pinned, and benchmarked, plus a free MCP connector so you can equip agents with only the skills you've chosen. The combination — access plus judgment, both layers verified — is where agent architectures are headed.

Your Action Plan: Triage, Build, and Vet Before You Install

Before you write a single line of a Skill or spin up an MCP server, run one triage question: does this capability need live external data, authentication, or centralized auditing? If yes, you're looking at an MCP server. If it's a repeatable workflow, output format, or domain expertise, a Skill is almost always the better fit — a framework echoed across both the Speakeasy decision framework and independent analyses of when each layer makes sense.

When in doubt, default to a Skill. The token math is hard to argue with: each Skill costs only a few dozen tokens at session start, while GitHub's official MCP server famously consumes tens of thousands of tokens of context on its own. Anthropic's official documentation puts Skill metadata loading at roughly 100 tokens per Skill at startup. One clear anti-pattern: never implement a Skill as an MCP server, since the protocol overhead negates the progressive disclosure that makes Skills efficient in the first place.

If you do build a Skill, follow Anthropic's authoring best practices:

• Start from evaluation — identify capability gaps from real task runs, then build incrementally.
• Treat the Skill like an onboarding guide for a new hire, not a code module.
• Split SKILL.md into separate files when it gets unwieldy, keeping mutually exclusive contexts apart to save tokens.
• Iterate with the agent itself, asking it to capture successful approaches and mistakes into reusable content.

Then comes the step most teams skip: vetting. Anthropic's security model treats installing a Skill like installing software, warning that "a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose." Published research found roughly 26% of skills carry at least one vulnerability — and Simon Willison notes that sandboxing against prompt injection remains an open problem. So vet third-party Skills the way you'd vet any software: security-scan the code, check the license, and pin the exact version so upstream changes can't silently alter behavior.

That's precisely the gap SkillzBench is being built to close. It's a free, independent directory of agent skills that continuously crawls GitHub, pins every version to a commit SHA, runs security scans and license checks, and benchmarks each skill in a sandbox — with and without the skill — to publish the Lift in percentage points. A trust score from 0 to 100 combines security, quality, license, maintenance, and community signals, with Lift always shown separately so ratings and money never touch the numbers. Everything — the directory, the free MCP connector, benchmarks, and change alerts — stays free, funded by ads around the blog rather than user fees.

SkillzBench is pre-launch, so the practical move today is simple: apply the workflow-versus-connectivity triage before building anything, default to Skills for token efficiency, and join the waitlist at skillzbench.com to get vetted, benchmarked skills the moment the directory goes live.