Claude Code Skills vs Plugins — What Each Does and When to Use Them | OpenAIToolsHub

Claude Code Skills vs Plugins — What Each Does and When to Use Them

Skills and plugins are both ways to extend Claude Code, but they solve different problems. A skill is a single markdown file of reusable instructions that Claude loads on demand. A plugin is a distribution unit that bundles multiple skills plus hooks, subagents, slash commands, and MCP servers into one installable package. The confusion comes from the fact that a plugin can contain zero, one, or many skills — so "skill" is never an alternative to "plugin," it's a building block inside it.

TL;DR

A skill lives as a markdown file (often ~/.claude/skills/{name}/SKILL.md) with YAML frontmatter describing when to invoke it. Claude auto-loads it when the user's request matches.

A plugin is a packaged bundle distributed via a marketplace or git repo. It can ship skills, hooks (bash scripts that run on events), subagents (specialized personas), slash commands, and MCP servers.

Build a skill when you have a repeatable workflow your team does more than twice a week that depends on project-specific knowledge.

Install a plugin when you need to integrate with an external system (GitHub, Postgres, Figma) and someone has already done the work.

A mature Claude Code setup usually has both: a handful of local skills for your team's idioms, plus a few plugins for external systems.

What a Skill Actually Is

A skill is a prompt that Claude loads on demand, gated by a trigger description. In practice:

---
name: publish-blog
description: Use when the user wants to publish a new article without deploying code. Handles slug checking, multi-locale INSERT, and IndexNow submission.
---

Read `scripts/publish_blog.py --help` first.
Then: (1) dedup check in DB, (2) parse drafts/, (3) SSH INSERT, (4) curl verify.

Claude watches the conversation. When the user says something that matches the skill's description, the body is injected into context and Claude follows it. That's the whole mechanism.

Because a skill is a markdown file, you can version it in git, diff changes, and share via a gist. There's no build step, no package manager, no installation beyond putting the file in the right directory.

When a skill shines:

Your team does the same multi-step workflow more than twice a week.
The steps depend on project-specific knowledge (file paths, internal APIs, naming conventions) that a generic tool can't know.
You want to constrain Claude's behavior to a known-good sequence.

When a skill is overkill:

You want Claude to connect to an external API. That's a plugin territory (or MCP).
The task is a one-off. Just ask Claude directly instead of formalizing it.

What a Plugin Bundles

A plugin is a packaged directory that ships to other people. The canonical shape:

my-plugin/
├── manifest.json         # plugin metadata + entry points
├── skills/              # zero or more skills
│   └── my-workflow/SKILL.md
├── hooks/               # bash scripts on events (PreToolUse, SessionStart)
├── subagents/           # specialized Claude personas
├── commands/            # slash commands (/my-command)
└── mcp-servers/         # MCP server configs

Plugins exist because distribution is a problem. You can email a teammate a skill file, but you can't email a complete GitHub integration with OAuth, webhook hooks, and a sub-agent that knows your repo conventions. Plugins solve that — install once via marketplace, get everything wired up.

When a plugin makes sense:

You need features beyond instructions — hooks that run bash on events, MCP servers that expose tools, subagents that swap in a specialized role.
You want other people to install your setup. A plugin is the distribution unit.
The setup involves external credentials or services (GitHub tokens, database connections) that benefit from a structured install flow.

Side-by-Side Decision Matrix

Situation	Use Skill	Use Plugin
"Every time I commit, lint my TypeScript"	Skill (auto-invokes on commit phrase)	Plugin (hook on PreToolUse for `git commit`) — better for deterministic enforcement
"Search my internal wiki"	Skill (if wiki is just markdown in the repo)	Plugin (if wiki requires API + auth)
"Write blog posts in our house style"	Skill (style guide markdown)	Overkill for plugin
"Deploy to staging"	Skill (if it's a script call)	Plugin (if it needs credentials + confirmation UI)
"Query our Postgres"	Both work — plugin via MCP is more ergonomic, skill calls psql directly	Usually plugin wins (MCP gives typed tools)

Real Examples From a Working Setup

I run Claude Code for a multi-site SEO agent. Here's what I have:

Skills (local, project-specific):

plan-seo-today — a 500-line markdown that drives the daily inner loop (dedup check, keyword selection via KGR, priority scoring). Too idiosyncratic to be a plugin.
publish-blog — reads drafts, INSERTs to pg, verifies. Specific to my two sites.
find-newword — KGR filtering with my opinionated rules about blue vs red ocean.

Plugins (from marketplaces):

postgres-best-practices — gives Claude structured Postgres knowledge without me writing it.
commit-commands — standard commit/PR helpers.
figma — Figma integration via MCP.

The ratio roughly matches what the Claude Code team documents: most people end up with 5-10 local skills tailored to their workflow and 3-5 plugins for external systems. Skills are the thing you write; plugins are the thing you install.

Honest caveat

The line between "too specific to be a plugin" and "generic enough to distribute" is blurry. I started publish-blog as a plugin candidate, then realized the SSH details and SQL shape are so tied to my infrastructure that packaging it would just create a confused template. It stayed a skill.

How the Runtime Actually Picks Between Them

When a user types a message:

Claude reads the active skill descriptions loaded in context.
If a skill matches, it's loaded into the prompt and followed.
Plugins with matching slash commands (/figma-use) trigger their flow.
Plugin hooks fire based on events (pre-tool-use, session-start) regardless of the user's message.

Skills are pull (Claude decides when to load). Hooks inside plugins are push (the runtime fires them on schedule). That's the structural difference that matters most — hooks enforce, skills suggest.

Frequently Asked Questions

Can a plugin contain a skill?

Yes. A plugin's skills/ directory is the canonical place to ship skills that are part of your integration.

Can I install plugins without a marketplace?

Yes — any git repo with the plugin structure works. Point Claude Code at the URL.

Do skills and plugins conflict?

Generally no. Skills activate on conversational triggers, plugins via slash commands or hooks. If two skills match the same trigger, Claude picks the more specific description.

Should I write a plugin for my team's internal tool?

Only if more than your team will use it, or if the tool requires external auth/services that benefit from a structured install. Otherwise a shared skill in a git repo is lighter-weight.

Where are skills actually stored?

User-level: ~/.claude/skills/{name}/SKILL.md. Project-level: .claude/skills/{name}/SKILL.md. Claude Code loads both, project takes priority on name conflicts.

How do I trigger a skill manually?

Slash command form: /skill-name. Or just describe what you want and Claude will match the skill's description.

What I'd Actually Build First

If you're new to this and wondering where to start: write three skills before you touch plugins. Pick three workflows your team does repeatedly — code review, release notes, test scaffolding — and capture the steps in markdown. See if Claude picks them up reliably. That exercise alone will teach you more about when to reach for a plugin than any architecture diagram.

Plugins come later, when you hit the wall: "I need hooks to enforce X" or "I need Claude to talk to our internal API." Until then, skills are the faster feedback loop.

Jim Liu runs OpenAIToolsHub, reviewing AI developer tools including Claude Code, Cursor, and Copilot. He's been building multi-agent Claude Code setups for SEO automation since early 2026 and maintains a Claude Code skills collection covering common workflows.