Skills Field Notes

Skills vs plugins in Claude Code

A skill is instructions in a folder. A plugin is a bundle you install. Most people need only the first one.

Mechanics checked on 2026-10-19. No install or run test, so no timings.

The 30-second version2026-10-19
What it changes

It stops the guessing. One file for a procedure, a bundle only when several components must install and update together.

Who should skip it

Anyone who has not written the procedure three times by hand. Packaging a rough process just makes it reproduce faster.

Where it breaks

A plugin's skills ignore skillOverrides, so you cannot switch off one piece. Project scope enables a plugin but does not install it for anyone else.

One file or one bundle?

The two words get used as if they were alternatives on the same shelf. They are not even on the same shelf. A skill is the unit of instructions: a folder with a SKILL.md, some reference files, sometimes a script. A plugin is the unit of distribution: a directory with a manifest, usually .claude-plugin/plugin.json, that can carry skills, subagents, hooks, MCP servers and hook modules.

Anthropic's plugin page says it plainly: skills, subagents, hooks and MCP servers all work independently, with no plugin involved. A plugin is what you reach for when you want to install someone's whole setup in one command, hand it to a team, or publish it as a versioned release. So the question is never "skill or plugin" as rival features. It is "one procedure, or a package of several parts".

Six differences that decide it

Dimension Skill Plugin
What it is Instructions in a folder, with optional reference files and scripts. Becomes a command and can also auto-load when relevant. A package of components, installed as one unit. Its skills are called as /plugin-name:skill-name.
Where it installs Personal: ~/.claude/skills/<name>/SKILL.md. Project: .claude/skills/<name>/SKILL.md. Also managed, added directories, inside plugins, or synced from claude.ai. Fetched from a marketplace into ~/.claude/plugins/, enabled by user, project or local scope. Cloud sessions do not load local plugins.
Team sharing Commit .claude/skills/ to the repo, or push it out through managed settings. Cloning the repo is the whole install. Publish a marketplace, or use the official one. Project scope enables it through committed settings; each collaborator still installs it locally.
Permission boundary allowed-tools pre-approves tools for the invoking turn only, cleared on your next message. It applies even in a workspace you never trusted. Whatever it runs, runs as you. Plugin subagents ignore hooks, mcpServers and permissionMode. Plugin skills are managed through /plugin, not skillOverrides.
Updates Edit the file and it takes effect; the directories are watched. Run /reload-skills if you created a top-level folder mid-session. Managed through /plugin, refreshed with /plugin marketplace update. Changes to hooks, .mcp.json or agents need /reload-plugins.
Shipped code Text by default, but not inert: scripts in scripts/ are executed, and a command line in the body runs before Claude reads the skill. Treat an unknown skill like an unknown script. Often yes, and without asking: hooks fire on lifecycle events, MCP servers run beside every session, hook modules are JavaScript. That is why the docs have a dedicated security and trust page.

The row people skip

Permission boundary. A skill's allowed-tools keeps working in a workspace that was never trusted, so a repository can hand itself broad pre-approved tools. Before you add someone's skill folder to a project, read its frontmatter. The grant clears when you send your next message, but the first turn is already paid for.

When to use a plugin instead of a skill

  • Skill only: one repository, one procedure

    Write the folder, commit it, done. Nothing runs in the background and every change is visible in a diff. Fits a small team, a half-formed process, or anyone who wants the same instructions to work in Cursor or Codex as well, since the format follows the cross-agent Agent Skills standard.

  • Plugin only: someone else's ready-made setup

    Install a maintained bundle, for example /plugin install skill-creator@claude-plugins-official, and take updates from the marketplace. Fits people who do not want to write instructions, and teams standardising a review flow, a set of subagents and MCP connections at once. Accept that installing means loading, every session.

  • Both layers: bundle for the base, skills for the specifics

    Let a plugin supply the subagents, hooks and MCP servers, and keep the project's own conventions in .claude/skills/ next to the code. Names do not collide: plugin skills live under /plugin-name:skill-name. This is the setup that survives multiple repositories, and the one that requires restraint about how many plugins you enable.

What each wrong choice costs

  1. A bundle for one instruction, paid per turn. Once a plugin is enabled, each of its skills, agents and auto-invocable commands keeps its name and description in context on every turn, even when nothing runs. Anthropic shows the estimate in the marketplace precisely because this is easy to forget.
  2. Editing a plugin's skill and expecting it to be yours. skillOverrides does not apply to plugin skills, so there is no per-item switch: disable or uninstall the plugin, or copy the skill into your repository as a project skill and keep control of it.
  3. Using a skill where you needed enforcement. A skill works by the model following it, and compression keeps only recent calls, first 5,000 tokens each within a 25,000-token budget. Rules that must always hold belong in a hook, which fires on its event regardless.
  4. Assuming project scope installs for teammates. It only enables the plugin through committed settings. A new clone gets the setting, not the files, so the command is missing until that person installs it. A committed skills folder does not have this gap.
  5. Filling the description budget. Subagent descriptions have their own ceiling: past 15,000 tokens of combined description for non-built-in agents, Claude Code warns at startup. Loading more does not mean paying nothing.

A four-question test

  1. Is it one procedure? Then it is a skill. Personal folder if only you need it, project folder if the team does.
  2. Does it need to fire every time, or reach another system? Then it is not a skill problem: a hook for enforcement, an MCP server for the connection. A plugin is only how you would ship those together.
  3. Are three or more components shipping and updating as one thing? Then package it, publish a marketplace entry, and budget for the context it adds.
  4. Does it have to run outside Claude Code? Then keep it a skill. The plugin mechanism is Claude Code's own; a skill written to the standard travels.

What this page does not know

Scope of this page

Nothing was installed for this page and no comparison was run, so there are no measured costs, no timings and no token counts beyond the documented budgets above. I could not fetch the anthropics/skills README, so no per-skill claims are made here. The official skills page arrived with a large section missing, which is why dynamic injection is described in one clause rather than with syntax. Whether a plugin update overwrites a local edit is undocumented, so I do not assert either behaviour.

Sources

  • Claude Code docs: plugins: components, standalone versus packaged, context cost, scopes, marketplaces and trust.
  • Claude Code docs: skills: file structure, locations and precedence, allowed-tools and workspace trust, content lifecycle and compression, the scope of skillOverrides.
  • Claude Code docs: subagents: definitions, the 15,000-token description budget, the fields plugin subagents ignore.
  • Claude Code docs: MCP: server processes and transports, deferred tool definitions, prompt injection warnings.

Mechanism descriptions were checked on 2026-10-19. Star counts and folder counts quoted on the companion page come from the GitHub API on the same date.