Claude Code Skills vs Plugins vs Subagents: Which to Use When

Introduction

I’ve been building inside Claude Code for nine months, and the main question I hear from founders who’ve started tinkering is how to choose between Claude Code skills vs plugins and subagents. They want to know the difference and, more importantly, when to use which.

Picking the wrong primitive turns a 10-minute fix into a half-day rebuild. Skills, plugins, and subagents all extend what Claude Code can do, but each one solves a different problem. Use a skill when a plugin would have been cleaner, and you end up with a folder of one-offs that won’t travel. Use a subagent when a skill would have done it, and you’ve burned tokens on isolation you didn’t need.

In this post, I’ll break down what each one is, when each is the right call, and how I use them together.

Key Takeaways

• Claude’s code skills vs plugins is really a question of scope: a skill is one markdown file Claude loads on demand, a plugin packages many skills together.
• Subagents are different again, running in their own context window for parallel research or work that would otherwise bloat the main conversation.
• Reach for a skill when reusable instructions should load only when relevant, not every conversation, to keep context budgets clean.
• Reach for a plugin when bundling skills, commands, hooks, and agents into one versioned unit you can share or install on multiple machines.
• Reach for a subagent when context bloat is the real problem, or when independent work can run in parallel for a roughly 4x speed-up.
• The three primitives stack: a plugin can ship a skill that spawns a subagent, which is how real systems get built inside Claude Code.
• Picking the wrong primitive costs tokens and rebuilds, both compounding across a busy day of work.

Claude Code Skills vs Plugins vs Subagents: What Each One Is

Three different primitives. Easy to confuse because they all extend Claude Code, and the marketing language around them tends to blur the lines.

A skill is a markdown file. It lives in .claude/skills/ (or inside a plugin), and it follows a standard format: YAML frontmatter at the top with a name and a description, then the body of the file with the instructions Claude should follow when the skill triggers. The description is the magic part. Claude reads it before every turn and matches it against what you’re asking. If it fits, the skill body loads. If it doesn’t, the file stays on disk and doesn’t eat your context budget.

A plugin is a packaging format. Think of it like a zip file with a manifest. A plugin bundles skills, slash commands, hooks, subagent definitions, and MCP server connections into a single installable unit. You add a marketplace to your Claude config, install the plugin, and everything inside it shows up at once. Plugins are how skills get distributed.

A subagent is an independent Claude run with its own context window. You invoke one via the Agent tool with a subagent_type parameter, and it goes off and does work on your behalf. The crucial part: it does that work in a separate context. The subagent reads files, runs tools, thinks, and comes back with a summary. The main agent sees only the summary, not the raw exploration.

Different shapes, different jobs.

When to Use a Claude Code Skill

Skills are for instruction sets you want loaded only when they’re needed.

The two questions to ask: is this reusable, and does it need to load every conversation?

If something fires only when you’re doing a specific task (writing ad copy, doing a security review, formatting a blog post), a skill is in the right shape. The description string tells Claude when to grab it. The body holds the playbook. You skip the cost of loading 8,000 tokens of marketing-speak into every conversation when 90% of your work has nothing to do with marketing.

Inside my own workspace, the writing-style Skill handles all my prose output. It loads when I’m writing emails, copy, scripts, anything meant to be read as a human wrote it. When I’m debugging a Python script, the skill never opens. That’s the trade. Cheap when idle. Available when called.

Skills also work well for workflows that have multiple steps you don’t want to type out every time. A skilled body can describe an entire process. First, check this file; then ask the user three questions, and then write the output to this directory. Claude follows the skill like a procedure.

What skills don’t do well: anything that needs to run in the background, anything stateful, anything that needs its own context window. Those are different problems.

The bigger pattern: skills are how you teach Claude what and how, while context files teach Claude who (your business, your data, your team).

When to Use a Claude Code Plugin

Plugins are about distribution.

You’ll know it’s a plugin job when you find yourself with five or six related skills, a handful of commands, maybe a hook or two, and you want to install all of it on a different machine or share it with someone. Without a plugin, you’d copy each file manually and probably miss one.

Plugins package the lot. A plugin.json lists what’s in it, what version it is, and where to find the marketplace. Someone else installs your plugin and gets the whole bundle. They never see the individual files unless they want to.

For my own work, the plugins I’ve installed mostly come from public marketplaces. The gstack plugin gives me roughly 30 skills around shipping code, reviewing PRs, and running QA tests. It’s not a single skill; it’s a whole working philosophy bundled together. Trying to maintain that as loose files would be a nightmare.

The other reason to package as a plugin: version control. If you’re going to evolve a set of skills over time, and you want to test new versions without breaking the working set, plugins give you a clean upgrade path. Marketplace points to the new version; when you update, the old skills are replaced. In the same way, Cursor or VS Code handles extensions.

The line between “skill” and “plugin” is this: if it’s one file you’ll only ever use yourself, leave it as a skill. If it’s a system, package it.

When to Use a Claude Code Subagent

Subagents solve a different problem. Context bloat, parallelisation, and cost.

Every Claude conversation has a budget. The context window is finite. Long file reads, tool outputs, search results, all of them eat into it. The bigger your context gets, the slower Claude becomes and the more expensive each turn is. Eventually, you hit a wall.

A subagent is how you stop that. Instead of reading 40 files in your main conversation, you spawn a subagent with the question “find the place where X is defined.” The subagent reads the 40 files in its own context, returns a one-paragraph answer, and your main conversation only sees the paragraph. The 40 file reads never touch your budget.

That’s the context firewall use case, and it’s by far the most common one. Anytime I’m hunting for something across the codebase, an Explore subagent does it.

The second use is parallelisation. If you’ve got four independent things to check (the front end, the back end, the database, the deploy config), you can fire off four subagents at once instead of doing them sequentially. They run in parallel. You get results back roughly 4x faster.

The third use is model routing. Subagents can run on a different model than the main agent. Heavy reasoning stays on Opus, search and summary go to Haiku. Haiku is roughly 20x cheaper than Opus and totally capable of “go read these files and tell me what they say.” Most of my subagent calls now specify model: "haiku" by default, and the bill comes down.

What subagents don’t do: they don’t share context with the main agent. They start fresh every time. So if you need to brief them, the prompt has to be self-contained. If your subagent needs to know who the user is or what project they’re in, you have to tell it.

My Decision Rule for Claude Code Skills vs Plugins (and Subagents)

The decision tree I run, in order:

Question one: Is this thing going to do its own reading or research? If yes, it probably wants to be a subagent. Anything that pulls in a lot of files, scans a big folder, or scrapes a website should run in its own context window. Otherwise, you’re polluting your main conversation with raw data you only needed once.

Question two: Is this thing reusable across conversations? If yes, it wants to be a skill. Skills are persistent. They sit in your workspace and trigger when relevant. A skill is the right home for any “I want Claude to act this way when X” pattern.

Question three: Am I going to share this with someone, version it, or install it on more than one machine? If yes, wrap it in a plugin. Plugins are the only clean way to distribute a bundle of skills, commands, hooks, and agents together.

Often you’ll use all three. A plugin bundles skills. One of those skills might tell Claude to spawn a subagent for the heavy lifting. The three primitives stack.

The way I think about it: skills tell Claude what to do, plugins tell Claude what’s available, subagents tell Claude who else to ask.

If you find yourself building everything as a slash command (the old way), you’re probably leaving capability on the table. Skills are smarter because they trigger themselves. Plugins are cleaner because they bundle. Subagents are essential because the alternative is context bloat that kills your conversation quality after two hours of work.

Conclusion

Claude Code is now genuinely a building platform, not just an assistant. The three primitives are the building blocks. Claude’s code skills vs plugins isn’t a competitive comparison, and neither is the subagent question. They solve different problems, and you use them together.

Pick a skill when you want reusable behaviour. Pick a plugin when you want to package and share. Pick a subagent when you need a separate context window for research, parallel work, or cheaper model routing.

The real win comes when you stop thinking of Claude Code as a chat tool and start thinking of it as the substrate you run your business on. Once you’ve got context files that teach it your business, skills that handle your repeatable workflows, plugins that travel with you, and subagents that do the heavy lifting, you’ve built something closer to an AI brain plus an AI workforce. The brain thinks. The workforce does. The conversation feels different.

That’s the bigger story underneath the primitives.

Take the Next Step

If you’re already inside Claude Code and want to talk through how skills, plugins, and subagents could be put to work in your own business, book a 15-minute Discovery Call. It’s a quick chat to see where you are and what the right next step looks like. Book the Discovery Call here.

If you’d rather read more first, two posts in adjacent clusters are worth your time: Agentic workflow examples and Agentic workflow. They go deeper into the patterns these primitives are designed to support.

For the source-of-truth documentation on plugin and skill formats, the Anthropic developer docs are where I’d start.

Frequently Asked Questions

About Octavius

Titus Mulquiney is the founder of Octavius AI, where he builds AI brains and AI workforces for founder-led businesses stuck running everything out of their own head. Twenty years in marketing, ex-Sony product manager, ex-GM Zeal NZ. Based in Auckland, working with operators across NZ, Australia, and the US. Connect on LinkedIn.