Claude Skills and Plugins: A Technical Deep Dive on Content vs. Container

The terms “Claude skill” and “Claude plugin” are often used interchangeably, creating a fog of confusion for developers trying to extend Claude Code. The reality is they are not the same thing. Understanding the distinction is not just academic; it’s fundamental to building, installing, and debugging custom behaviors effectively.

At SkillProof, we live in these mechanics every day. We don’t just read the documentation; we install and run skills on real work, from both raw folders and plugin bundles. Of the 1877 skills we have tested to date, only 1159 (62%) passed our evaluation. Another 624 needed configuration, a companion skill, or an integration before they delivered, and 94 scored below the no-skill baseline — either they couldn’t run at all, or they ran and left you worse off than installing nothing. This experience gives us a clear, ground-truth perspective on the difference between a Claude skill and a plugin, and which you should use.

The simplest way to think about it is this: a skill is the content—the set of instructions that teaches Claude a new behavior. A plugin is a container—a distribution package that can bundle one or more skills, along with other types of extensions.

This article separates the two concepts, using the exact file paths and commands we use in our daily testing. We will cover what a skill is, what a plugin is, how they are installed, and when to build one versus the other.

What is a Claude Code Skill? The Atomic Unit of Behavior

A Claude skill is the most fundamental building block. It is, quite literally, a folder containing a file named SKILL.md. That’s it. The folder name becomes the skill’s identifier.

The SKILL.md file has a simple, two-part structure:

1. YAML Frontmatter: A block at the top of the file, enclosed by ---, that defines the skill’s metadata. The field that matters is description. name is optional and defaults to the directory name, and there are a dozen or so other optional fields (allowed-tools, when_to_use, model, paths and friends) that most skills never touch.
2. Markdown Instructions: Below the frontmatter, you write plain markdown that explains the task to Claude. This is your prompt, your set of instructions for how to perform the behavior.

Crucially, the SKILL.md format does not include complex syntax for defining tool functions, API schemas, or parameter types. There is no required block for few-shot examples. The entire system is built on natural language.

The most important field in the frontmatter is description. This is not just for human readers; it is the primary trigger for the skill. When you give Claude a task, it scans the description fields of all installed skills to find a match. If your task description aligns with a skill’s description, Claude loads that skill’s markdown instructions into its context to guide its response. Leave it out and Claude falls back to the first paragraph of the body, which is rarely written to be a trigger.

This is a frequent point of failure we document in our tests. We’ve seen many skills with brilliant instructions in the markdown body that Claude never uses because the description in the frontmatter was too vague, too specific, or missing entirely. A skill with a description like "Aids in development" will almost never be triggered. For a deeper look at what makes a good skill, see our guide on what Claude skills are.

How to Install a Raw Skill

If a skill is just a folder, installing it is as simple as copying that folder to the right place. Claude Code looks for skills in two locations:

1. Global: ~/.claude/skills/
2. Project-Specific: <your-project-directory>/.claude/skills/

Skills in the global directory are available in any project you open with Claude Code. Skills in a project-specific directory are only loaded when you are working within that project. This is useful for tasks specific to a single codebase.

To install a skill you’ve downloaded from a Git repository, the process is a direct file operation. For example, after cloning a repository containing a skill, you would run:

# Example: Installing a skill into the global directory
cp -r path/to/cloned-repo/the-skill-folder ~/.claude/skills/

Claude Code watches those skill directories, so a skill you add, edit, or remove is picked up inside the current session without a restart. The exception is a skills directory that didn’t exist when the session started; create one of those and you do need to restart so Claude Code begins watching it.

There is no special command-line interface for installing a raw skill, and no --skill flag that points Claude at a SKILL.md file for a single run. Copying the folder is the install.

This direct, file-based approach is how we install the majority of the skills listed in our catalog. It’s simple, transparent, and easy to debug. You can find more detailed installation examples in our guide to installing Claude skills.

What is a Claude Plugin? A Distribution Package

If a skill is the content, a plugin is the shipping crate. A plugin is a self-contained directory of components, usually carrying a .claude-plugin/plugin.json manifest that holds its identity metadata (name, description, version, author) and can point at where its components live.

This is the core difference between a Claude skill and a plugin: a plugin is designed to be a bundle. While it can contain a single skill, its real power is in its ability to package multiple, related extensions together. A plugin can ship:

• Skills: One or more SKILL.md folders.
• Agents: Specialized subagents the main Claude agent can hand work to.
• Slash Commands: Custom / commands you can run directly in the Claude Code chat interface.
• Hooks: Scripts that run automatically at certain points in the session lifecycle.
• MCP Servers: Connections to a Model Context Protocol server, so a plugin can wire up an external integration as part of its install instead of leaving you to configure it by hand. For more on this, see our breakdown of skills vs MCP.
• LSP Servers: Language server connections that give Claude type errors and code navigation.

A plugin is not just a wrapper for a single skill. It’s a complete toolkit. For example, a plugin for a specific testing framework might bundle a skill for writing new tests, a slash command for running them, and a hook to run tests before every commit. The skill is just one piece of the puzzle.

How Plugins and Marketplaces Work

Because plugins are more complex packages, their installation process is different. You don’t manually copy plugin folders. You go through marketplaces: a marketplace is a Git repository containing a .claude-plugin/marketplace.json file that lists the plugins it offers.

Anthropic runs an official marketplace, claude-plugins-official, which Claude Code adds for you automatically at startup, plus a community marketplace at anthropics/claude-plugins-community that you add yourself and whose plugins have passed automated validation and safety screening. But the system is not closed: anyone can publish a marketplace by putting a marketplace.json in a repo, and nothing stops you from adding it. Inclusion in the official catalog is at Anthropic’s discretion; everything outside it carries whatever quality the maintainer chose to give it.

To install a plugin, you add its marketplace, then install the plugin by name:

1. Add the marketplace:

   /plugin marketplace add anthropics/claude-code

2. Install the plugin:

   /plugin install commit-commands@claude-code-plugins

Then run /reload-plugins to activate it in the current session.

Plugin management is not confined to the interactive interface, though. There is a claude plugin shell command group (aliased claude plugins) covering install, uninstall, enable, disable, update, list, details, init, and validate — the documented way to install without the interactive step, and what you reach for when scripting a team setup:

claude plugin install commit-commands@claude-code-plugins --scope project

There are also --plugin-dir and --plugin-url flags for loading a plugin for one session only, which is how you try something before committing to it.

The distinction between a marketplace and a curated directory matters here, and it is not the same axis as skill versus plugin. A marketplace is a distribution channel: it tells you a plugin exists and installs it. Screening, where it happens at all, is automated. None of it tells you whether the thing works on your task.

Claude Code Skills vs Plugins: A Side-by-Side Comparison

To make the distinction perfectly clear, here is a direct comparison of the key attributes:

Feature	Raw Skill	Plugin
Definition	A folder with a SKILL.md file defining a single behavior.	A self-contained directory of components, acting as a package.
Core File	SKILL.md	.claude-plugin/plugin.json
Scope	A single set of instructions for one task.	A bundle of skills, agents, commands, hooks, MCP and LSP servers.
Installation	Manual copy: cp -r ... ~/.claude/skills/	/plugin install <name>@<market>, or claude plugin install
Distribution	Direct folder sharing, Git repository.	Via a Marketplace (a Git repo with a manifest).
Use Case	Personal use, single-purpose tools, rapid prototyping.	Team distribution, complex toolkits, multi-part behaviors.

How SkillProof Tests Both

Our testing methodology is agnostic to the installation method. Whether a skill arrives as a raw folder or inside a plugin bundle, our process is the same. We install it and then evaluate the performance of the underlying SKILL.md instructions against a standardized set of tasks.

The distribution method does not change the skill’s behavior. A poorly written SKILL.md file will perform just as badly whether you copy it manually or install it with /plugin install.

In fact, a recurring failure we hit is a package that installs perfectly but contains a skill that never fires. The install completes without error, the skill shows up in the list, and then Claude never reaches for it, because the description in its SKILL.md is too thin to match anything a user would actually type. Nothing about the install reports this. You only find out by giving Claude the task the skill was meant to handle and watching it answer as if the skill weren’t there — which is exactly the test we run.

This is part of why 624 of the 1877 skills we’ve tested carry a “Works with setup” verdict rather than a pass: they deliver, but not out of the box, and packaging tends to hide the reason.

Should I Build a Skill or a Plugin?

This brings us to the practical question: when you have a new behavior for Claude, should you build a skill or a plugin?

The answer is straightforward: always start by building a skill.

1. Create your your-skill-name/SKILL.md file. Focus on writing clear, effective instructions and a precise, trigger-friendly description. Test it locally by copying it into ~/.claude/skills/.

2. Iterate on the SKILL.md until it works reliably. This is 99% of the work. The content of this file is what delivers the value.

Only after you have a proven, working skill should you consider packaging it as a plugin. The decision to create a plugin should be driven by distribution needs, not by the complexity of the skill itself.

Package as a plugin if:

• You are shipping more than one component. For example, a skill to generate API documentation and a slash command /generate-docs to trigger it for the whole project.
• You need to distribute a set of skills to a team with a single, simple installation command.
• You are building a more advanced extension that relies on hooks, subagents, or other plugin-only features.

If you have a single skill for your own personal use, creating a plugin is unnecessary overhead. A raw skill folder in ~/.claude/skills/ is simpler and more direct.

The Bottom Line: Focus on the Skill, Not the Wrapper

The central takeaway is that performance comes from the quality of the SKILL.md file, not its packaging. A plugin is a distribution mechanism, not a guarantee of quality. As our data shows, even cleanly packaged skills fail: 94 of the ones we’ve tested scored below what Claude does with no skill installed at all.

The difference between Claude skills and plugins isn’t a matter of good vs. bad, but of scope and purpose. One is the instruction; the other is the box it ships in.

Related reading: for the packaging side in depth — manifests, marketplace structure, and what to check before you add someone’s repo — see our guide to Claude Code plugins. For the content side, what Claude skills are covers how the format works before you write your first one.

Finding the 1159 skills that actually pass our tests is the reason we built SkillProof. If you want to skip the trial-and-error, our catalog of tested coding skills is a good place to start. If you’d rather install a set that’s already been tested together, we sell role-based packs of ten — Developer Toolkit, Writer Pack, Security & Code Review and five others — for $10 each at /bundles.