When should I package a Claude Code plugin versus a standalone SKILL.md?
TL;DR
Start with a standalone `.claude/skills/<name>/SKILL.md` folder inside one repo. Package a plugin when you need versioned distribution of skills, slash commands, hooks, subagents, and MCP servers across multiple repos or IDEs.
A standalone skill is the unit of instruction; a plugin is the unit of distribution.
Standalone SKILL.md folder
Drop a SKILL.md file inside .claude/skills/<skill-name>/ and commit it to Git. Every developer using Claude Code CLI, VS Code, JetBrains, Codex, or Cursor in that repository gets the exact same routing behavior with zero marketplace setup.
Choose a standalone skill when:
- The rules belong to a single codebase or monorepo
- You iterate on the instructions weekly alongside application code
- You want zero external version drift
Claude Code plugin (/plugin)
A plugin bundles multiple primitives—skills/, commands/, agents/, hooks/, and .mcp.json—under a plugin.json manifest so teams can install the entire bundle via /plugin marketplace add <org>/<repo>.
Choose a plugin when:
- Three or more repositories share the same engineering or brand gates
- You ship preconfigured hooks and slash commands alongside skills
- Contributors work across terminal CLI, VS Code, and JetBrains IDEs and need one-command updates
Read the full comparison and directory layout in the Claude Code plugins vs skills guide.