Claude Code plugins explained: when to bundle skills, hooks and slash commands

Slash commands shortcut what you type. Hooks fire on system events. Skills give Claude new capabilities it can choose to use. Plugins bundle all of those together so you can install a whole workflow as a unit.

What’s in a plugin

A typical plugin directory looks like this:

my-plugin/
├── plugin.json # metadata
├── CLAUDE.md # plugin-specific instructions (optional)
├── commands/ # slash commands
│ ├── deploy.md
│ └── audit.md
├── skills/ # skills
│ └── shopify-product/
│ └── SKILL.md
├── hooks/ # hooks defined in settings
│ └── settings.json
└── mcp/ # MCP server configs
 └── mcp.json

Drop the folder into .claude/plugins/ (project-scoped) or ~/.claude/plugins/ (user-scoped) and Claude Code picks it up on next session start.

When to make a plugin

• You’ve got a workflow your team repeats. Standardise it. Plugin gets versioned in git, everyone gets the same workflow.
• You operate the same kind of business across multiple repos. A client we work with has 4 separate repos that all benefit from the same Australian-business conventions. One plugin, four installs.
• You’re building tooling for a client. Ship them a plugin folder rather than a CLAUDE.md and “here’s what to copy.”

When not to make a plugin:

• One-off workflow: just use a slash command directly.
• Single project: project-scoped .claude/ folder is simpler.
• Two related commands: not enough to justify the abstraction.

A real Australian SMB plugin

Here’s the shape we use at Boring Ventures for our internal boring-ventures-au plugin:

boring-ventures-au/
├── plugin.json # name, version, description
├── CLAUDE.md # AU English rules, $AUD, DD/MM/YYYY, no em dashes
├── commands/
│ ├── standup.md # daily standup from git activity
│ ├── changelog.md # CHANGELOG entry from recent commits
│ ├── aud.md # rewrite text in Australian English
│ └── quote.md # client quote from scope brief
├── skills/
│ ├── australian-context/
│ │ └── SKILL.md # ATO, ASIC, state-rev concepts
│ └── aud-formatter/
│ └── SKILL.md # currency + date formatting
└── hooks/
 └── settings.json # date-injection hook, audit log

Installed in every DotVA and Lead Gen Empire repo. Standardises voice + conventions across 30+ repos without copy-pasting CLAUDE.md.

plugin.json shape

{
 "name": "boring-ventures-au",
 "version": "1.0.0",
 "description": "Boring Ventures conventions for Australian business work",
 "author": "Boring Ventures Pty Ltd",
 "license": "MIT"
}

Currently the only mandatory fields are name and version. The rest is metadata for humans.

Distributing plugins

No central registry yet. Three patterns work:

1. Git submodule. Add the plugin repo as a submodule under .claude/plugins/. Update with git submodule update --remote.
2. npm publish. Plugins are just folders, publish as a package and npm install into the right location.
3. Direct clone. Tell your team git clone <plugin-repo> ~/.claude/plugins/<name>. Simplest, requires manual updates.

For our internal plugin, we use git submodules across all repos. For anything we’d open-source, npm is the better path because it handles version pinning.

What to put in your first plugin

If you’re thinking about your first plugin, start with these three things bundled:

1. Your CLAUDE.md. Voice rules, language settings, project conventions.
2. One slash command you use weekly.
3. One hook, usually the date-injection or audit-log hook.

Tiny scope. Ship it. Add more as patterns surface.

What we wouldn’t put in a plugin (yet)

• Anything project-specific (kept in the project’s local .claude/)
• Anything with secrets (API keys, tokens, they go in env vars, not plugins)
• Anything you’re not sure will outlive a week (test as a local command first)