Agent skill vs plugin
How a standalone agent skill differs from a plugin package, with a worked example and what we tested versus what is documentation.
- Published
- Sep 27, 2026
- Checked
- Sep 27, 2026
- Words
- 749
How far we checked this page
Signed by Arun Kumar, Sep 27, 2026. Passing one check says nothing about the next.
- FormatNot checkedThe file format was not checked for this page.
- InstallsNot checkedInstallation was not checked for this page.
- LoadsNot checkedLive loading was not checked for this page.
- HelpsNot checkedA with/without task comparison was not run.
A skill is one task-focused workflow. A plugin is an installable package that can bundle one or more skills alongside other pieces (MCP connections, subagents, rules, hooks), depending on the host. Reach for a standalone skill when you have one workflow to drop directly into a project’s or your personal skills folder. Reach for a plugin when you need a named, distributable package: several related skills, or a skill paired with the MCP server or subagent it depends on, installed and updated as one unit. As of September 2026, the manifest format and install route for a plugin are host-specific: a Claude Code plugin is not a Cursor plugin is not a Codex plugin.
Choose a standalone skill when
- It’s one self-contained workflow and nothing else needs to travel with it.
- You want to drop
SKILL.md(and anyreferences/,scripts/,assets/) into a documented skills folder, with no manifest and no install step beyond copying files. - You’re distributing it informally: a shared folder, a repo, a paste into a teammate’s project.
Choose a plugin when
- You have more than one related component to ship together, for example a skill plus the MCP server it depends on, or several skills that belong to the same workflow.
- You want a single named package with a version, installed and updated through the host’s own install route rather than by hand-copying files.
- You’re distributing through a marketplace or directory that expects a manifest, not a loose folder.
Worked example
We built a small skill called explain-error: a description of when to use it, plus instructions to name the file and line, name the error type, and give one fix, backed by a references/checklist.md. As a standalone skill, it needs nothing but the right folder: on Codex CLI 0.157.1 we copied it to .agents/skills/explain-error/ in a scratch project and it was discovered and invoked with no manifest and no plugin involved.
Packaging the same skill into a Claude Code plugin is a different shape of work, per the docs. The plugin needs its own .claude-plugin/plugin.json manifest, and the skill moves under the plugin’s own skills/explain-error/SKILL.md. Once installed, it no longer answers to a bare /explain-error: Claude Code namespaces plugin skills under a command like /plugin-name:explain-error. Claude Code plugins. We haven’t built or installed that plugin version ourselves, so this paragraph is documentation, not a test result.
At a glance
| Standalone skill | Plugin | |
|---|---|---|
| Ships | One workflow | One or more skills, plus (host-dependent) MCP connections, agents, rules, hooks |
| Install | Copy the folder to a documented skills path | Install through the host’s plugin route (manifest-based) |
| Manifest | None required | Yes, for example Claude Code’s .claude-plugin/plugin.json, or a portable root plugin.json per the Agent Plugins 1.0.0 schema |
| Invocation name | The skill’s own name | Often namespaced, e.g. /plugin-name:skill-name in Claude Code |
| Distribution | Hand-copy, repo, npx skills add | Marketplace or directory, plus local dev routes like --plugin-dir |
| Cross-host portability | The SKILL.md format travels; the folder path doesn’t | Manifest format and layout are host-specific |
What we checked
The plugin-format details above (manifest names, namespaced commands, marketplace routes) come from each host’s own docs: Claude Code plugins, Cursor plugins, and OpenAI’s plugin architecture and packaging guide, all checked September 27, 2026. We did not install a plugin in any host for this page.
What we did test hands-on, on the same date, was the standalone-skill side: our explain-error skill, hand-copied to .agents/skills/explain-error/ and the older .codex/skills/explain-error/ path, was discovered and correctly invoked on Codex CLI 0.157.1: both SKILL.md and references/checklist.md were read (visible in the tool trace), a matching prompt triggered it, and an unrelated prompt didn’t. We separately installed the skill with npx skills add <path> -a codex (skills CLI 1.7.0), which wrote a full copy, not a symlink, to .agents/skills/ (the installer doesn’t target .codex/skills/), and it loaded live the same way.
What we didn’t check: we didn’t package any skill into a plugin in any host, so every plugin-side claim above is what the docs say, not something we watched happen. We also didn’t test standalone skill loading in Claude Code (auth blocker in our test setup) or Cursor (not installed).