Claude Code Extensions vs Skills: Which to Build?

The Confusion Tax: Why the Skills-vs-Extensions Debate Is Costing You Time

The real problem isn't choosing sides — it's that nobody agrees on what the sides are. The Claude Code extension ecosystem is a layered taxonomy of CLAUDE.md files, slash commands, MCP servers, plugins, and skills, and terminology shifts depending on which source you read.

Consider: Trail of Bits' production marketplace distributes 30+ "skills" via the plugin marketplace mechanism, while freeCodeCamp's tutorial insists skills "are not plugins, extensions, or packages." Both are right in spirit and confusing in practice.

Developers stall on the wrong question — "which is better?" — when the honest answer is that these mechanisms solve different problems. Skills are instruction packages with no runtime: a SKILL.md file that tells the agent how to do something. Extensions (MCP servers, plugins) are functional code that adds what the agent can do: API calls, database queries, shell execution.

The murkiness has a specific cause. Across the research we reviewed, no source directly defines "extension" as a distinct, formal mechanism. The comparison material comes from adjacent discussions of MCP servers and plugins, which is exactly why the decision feels like wading through fog.

A quick map of the layers:

• CLAUDE.md — persistent project memory; facts, not procedures.
• Skills — SKILL.md instruction packages; the official docs now fold custom slash commands into this category.
• MCP servers — running processes that expose tools and data the agent lacks natively.
• Plugins — bundles that package skills, agents, hooks, and MCP servers together.

The cost of this confusion is measurable in wasted weeks. Teams rewrite the same workflow three times — first as a CLAUDE.md section, then as a slash command, then as a skill — before realizing custom commands have already merged into the skills mechanism. Others build an MCP server for a repeatable checklist that a 100-token skill would have handled.

Skills load via progressive disclosure — roughly 100 tokens at startup, with the body loading only when triggered — so they're the cheaper, lower-risk first build for anything procedural. Extensions earn their complexity only when the agent needs a genuinely new capability.

There's a trust dimension to the confusion too. Skills are readable and auditable; MCP servers are often opaque. But skills carry their own supply-chain risk — Snyk's ToxicSkills research found prompt injection in 36% of tested skills and 1,467 malicious payloads across the ecosystem. Whatever you build or adopt, verification before installation is non-negotiable. That's the trust layer SkillzBench is building: independent security scanning, commit-pinned versions, and sandboxed benchmarks so you can see what a skill actually does before your agent runs it.

The Real Distinction: Process Documents vs Functional Extensions

Strip away the ecosystem noise and one clean distinction remains: a plugin extends what Claude can do, while a skill defines how Claude does it. As MindStudio's framework puts it, "Skills are process documents; plugins are functional extensions."

A plugin, MCP server, or bundled extension adds capability Claude doesn't natively have: API calls, database interaction, shell commands. A skill, by contrast, is a SKILL.md instruction package with no runtime of its own. The official Claude Code documentation recommends building a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat.

The ecosystem is actually a layered taxonomy rather than a binary choice. Snyk's security analysis maps the full stack: CLAUDE.md files for persistent project memory, custom slash commands (now merged into skills), MCP servers, Claude Connectors, and plugins that bundle skills, agents, hooks, and MCP servers together.

That merger matters for anyone deciding what to build. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create the same /deploy command and work identically — so the old "should I write a slash command or a skill?" question has collapsed into one answer.

Here the apparent contradiction surfaces: sources say skills "cannot run code," yet skills can bundle executable scripts and use !command`` syntax for dynamic prompt injection. The reconciliation is that skills have no runtime but direct the agent's existing tools. freeCodeCamp's practical guide is explicit: skills are not plugins, extensions, or packages — they instruct code execution rather than perform it.

The two mechanisms are therefore complementary, not competing. A skill might use a plugin as one of its steps — the process document orchestrates, the functional extension executes. Trail of Bits demonstrates this in production, distributing 30+ skills that orchestrate subagents and intercept tool behavior for security work.

The decision framework, then, looks like this:

• Build a skill for repeatable workflows with a clear trigger and consistent output format
• Build an extension when Claude needs a genuinely new capability — API access, database queries, shell commands
• Combine them when a workflow needs both process discipline and new tools

Because skills are readable and auditable while MCP servers are often "black boxes," skills carry a transparency advantage — though Snyk's finding of prompt injection in 36% of tested skills means neither is risk-free. SkillzBench is building independent security scanning and sandboxed benchmarking precisely to close that trust gap.

Why Skills Win by Default (Until They Don't)

If you're deciding what to build first, the economics alone make the case: a skill costs almost nothing until Claude actually needs it. Thanks to progressive disclosure, a skill consumes only about 100 tokens at startup — its full body loads only when triggered, according to the official Claude Code documentation. Compare that to an MCP server, which runs as a persistent process the moment your session starts.

Portability compounds the advantage. Because skills follow the open Agent Skills standard, the same SKILL.md file works across Claude Code, Codex, Cursor, and Gemini CLI, as freeCodeCamp's skill-building guide explains. Build once, and your workflow travels with your team across whatever coding agent they prefer.

Then there's auditability. Ran Isenberg, a senior principal architect at Palo Alto Networks, argues well-written skills often beat MCP servers on transparency: "I can read the skill text, review it for security issues, and understand exactly what it tells Claude to do, while MCPs are black boxes" (Isenberg's practitioner report). Worth noting: that's one experienced practitioner's opinion, not settled consensus — but it's a perspective worth weighing.

The adoption numbers suggest the market agrees. Andrej Karpathy's guidelines skill — a single CLAUDE.md file with zero runtime dependencies — racked up 210k+ GitHub stars, and the Superpowers library has passed 280k+ stars with 25k+ forks, per Firecrawl's roundup (star counts are self-reported). And skills are more sophisticated than "just prompts": Trail of Bits maintains 30+ production skills covering malware analysis and smart contract security, including skills that orchestrate subagents and intercept tool behavior.

• Near-zero cost until used (~100 tokens at startup via progressive disclosure)
• One SKILL.md file runs across Claude Code, Codex, Cursor, and Gemini CLI
• Fully readable and auditable — no opaque runtime to trust blindly

One caveat before you install someone else's skill: Snyk's ToxicSkills research found prompt injection in 36% of tested skills. Readability only helps if you actually read. That's exactly the gap SkillzBench is being built to close — independent security scanning and sandboxed benchmarking of every skill, all free at launch.

So when does the default flip? Build an extension when you need genuinely new capabilities Claude lacks — API calls, database connections, shell commands. As MindStudio frames it, a plugin extends what Claude can do; a skill defines how. If Claude can already do it, you don't need an extension — you need better instructions.

The Security Wildcard Neither Option Escapes

Whichever path you choose — a lean SKILL.md or a full MCP server — you are installing something your agent will trust enough to act on. That trust is the part of the decision most teams skip, and the numbers suggest they shouldn't.

Snyk's ToxicSkills research found prompt injection in 36% of the skills it tested, and 1,467 malicious payloads across the skills ecosystem. Their guidance is blunt: treat skills the way you would treat any third-party code you run in your environment. Skills have no runtime of their own, but they can bundle scripts and direct the agent to execute code through its existing tools — which means a "harmless" instruction file is not harmless.

The extension side offers no refuge either. Practitioners like Ran Isenberg prefer skills precisely because MCP servers are "black boxes" — running processes whose internals you often cannot inspect. You are trading readable instructions for opaque executables, and the risk simply changes shape rather than disappearing.

Before adopting anything third-party, a few minutes of vetting beats hours of cleanup:

• Read the full SKILL.md — every line, not just the description.
• Audit every bundled script in the skill's scripts/ directory before installing it.
• Watch for undocumented network calls — a known failure pattern in community skills.
• Pin the version you reviewed so a later "update" can't swap in new behavior.

This is the trust layer the ecosystem currently lacks: nobody independently scans skills for injection payloads, pins them to a verified commit SHA, and re-checks them when upstream code changes. That gap is exactly what SkillzBench is building — independent security scanning, commit-SHA-pinned versions, and sandboxed benchmarking of every listed skill, plus a free MCP connector so your agent only ever sees the skills you have explicitly vetted and toggled on.

Until independent verification is the default, assume nothing is safe by default. Your decision between skills and extensions should include a third question: not just "what does it do?" but "who checked it?"

Build Checklist: Ship the Right Thing the First Time

Build the skill first. That is the default rule the evidence supports, and it holds until you can prove you need something with a runtime.

The decision rule is clean: a plugin or MCP server extends what an agent can do, while a skill defines how it does something, according to MindStudio's breakdown of the two mechanisms. Official Claude Code guidance agrees, recommending a skill whenever you keep pasting the same instructions or a CLAUDE.md section has grown into a procedure. Skills also cost almost nothing until invoked, since only the description loads at startup, which makes them the lower-risk first build.

Here is the checklist to run before you ship:

• Default to a skill for any repeatable workflow with a clear trigger and consistent output.
• Reserve extensions for genuinely new capabilities: API calls, database access, shell commands.
• Invest disproportionately in the description field. It is the routing trigger, and agents have a natural tendency to undertrigger skills.
• Keep it lean and composable: lean SKILL.md, fat reference.md, one job per skill, deterministic work in bundled scripts, three worked examples over twenty constraints.
• Audit everything before adoption.

That last point is not optional. Snyk's ToxicSkills research found prompt injection in 36% of tested skills and 1,467 malicious payloads across the ecosystem, and MCP servers have been described as black boxes you cannot easily read. Treat any third-party skill like code you are running in your own environment.

The payoff for choosing skills is portability. One SKILL.md file works across Claude Code, Codex, Cursor, and Gemini CLI, so a single well-written skill serves your whole agent stack instead of locking you into one vendor's extension format.

SkillzBench is building exactly the trust layer this decision needs: a free directory that continuously crawls and dedupes skills from GitHub, pins every version to a commit SHA, validates, license-checks, security-scans and quality-judges each one, then benchmarks it in a sandbox with and without the skill and publishes the Lift in percentage points. A free MCP connector lets you load only the skills you choose, per agent. Everything is free, and ad revenue never touches scores or listings. Join the waitlist to test skills before you commit.