How Claude Code plugins work, how to install one in two commands, and how to build your own .plugin file with skills, slash commands, and MCP servers.
Open your terminal first — here's how to find it: Mac: Cmd+Space, type "Terminal" and press Enter. Windows: Start menu → search "Terminal" or "PowerShell".
command not found, install Claude Code first.Quick install: Open Claude Code, paste this command, press Enter:
/plugin marketplace add anthropic/claude-code-plugins && /plugin install code-review@anthropicThat's it — the plugin is active in your next session.
If you've never opened a terminal before, here's exactly where to go:
On Mac:
Cmd + Space to open SpotlightTerminal and press EnterOn Windows:
Win + X → select "Terminal" (or "PowerShell")Win + R, type cmd, press EnterWhat you're looking at: The terminal is a text-based way to talk to your computer. You'll type commands and press Enter to run them. Every line that starts with > or $ is waiting for your input.
Starting a Claude Code session:
claude and press Enterclaude >)/plugin list to confirm the plugin is installedA Claude Code plugin is a single .plugin directory that bundles skills, slash commands, MCP servers, hooks, and subagents — installable in two commands and shareable like an npm package. If you've been copying skills folders between repos or rewriting the same slash command in three projects, plugins are the answer.
This guide is the tactical version. How to install one in the next five minutes, how the directory structure actually looks on disk, how to test locally before publishing, and how to build a minimal plugin from scratch. Plus the marketplace landscape — Anthropic's official repo, the community marketplaces, and how CoworKit ships Starter Kits as .plugin files.
A plugin is a directory. That's it. Inside the directory is a manifest file at .claude-plugin/plugin.json plus any of the following, in standard subdirectories Claude Code knows where to find:
SKILL.md (name, description, trigger phrases) plus any supporting scripts or templates.commands/review.md → /review).When you install a plugin, Claude Code merges these into your session. Skills become available for activation, slash commands appear in /, MCP servers connect on startup, hooks fire on the right tool events.
The whole thing is plain files on disk. No build step, no runtime, no package manager. If you can write Markdown and a small JSON file, you can ship a plugin.
Two commands:
/plugin marketplace add anthropic/claude-code-plugins
/plugin install code-review@anthropic
The first command registers a marketplace (a Git repo that contains a marketplace.json listing available plugins). The second installs a specific plugin from it. Plugins install to ~/.claude/plugins/ and become active in your next Claude Code session.
You can add multiple marketplaces and pin specific versions:
/plugin marketplace add cowork-com/plugins
/plugin install job-search-os@cowork --version 0.4.2
To uninstall: /plugin uninstall name@marketplace. To list what's installed: /plugin list. To update: /plugin update name@marketplace. The whole system is designed to feel like a package manager — because at the operational layer, it is one.
A real plugin directory looks like this:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # manifest (required)
├── skills/
│ ├── morning-prep/
│ │ ├── SKILL.md # name, description, trigger phrases
│ │ └── helpers.py # optional support scripts
│ └── email-coach/
│ └── SKILL.md
├── commands/
│ ├── review.md # becomes /review
│ └── ship.md # becomes /ship
├── agents/
│ └── security-reviewer.md
├── mcp/
│ └── servers.json
└── hooks/
└── post-edit-format.sh
The only required file is .claude-plugin/plugin.json. Everything else is optional and additive — ship a plugin with just one skill, or one slash command, or one MCP server. Claude Code reads what's there and ignores what isn't.
Here's a real plugin.json matching Anthropic's current spec:
{
"name": "job-search-os",
"version": "0.4.2",
"description": "Daily job search operating system — morning prep, call prep, email coach, evening debrief, top-15 proactive actions",
"author": {
"name": "CoworKit",
"url": "https://coworkit.online"
},
"license": "MIT",
"homepage": "https://coworkit.online/missions/job-search",
"repository": "https://github.com/cowork-com/plugins",
"claude_code": {
"min_version": "1.0.0"
},
"components": {
"skills": ["morning-prep", "call-prep", "email-coach", "evening-debrief", "top-15"],
"commands": ["plan", "debrief", "prep"],
"mcp_servers": []
}
}
The components block isn't strictly required — Claude Code auto-discovers anything in the standard directories — but listing them explicitly helps users see what they're installing and prevents accidental shipping of half-finished skills.
Before publishing, you want to test the plugin without going through the marketplace flow. The flag is --plugin-dir:
claude --plugin-dir ./my-plugin
This loads the plugin directly from the local directory for that session. Edit the files, restart the session, see your changes. Iterate fast.
Two things worth knowing. First — if you point at a directory that doesn't have .claude-plugin/plugin.json, the load silently fails. Check that file exists before debugging anything else. Second — skills only activate when their trigger phrases or description match. If your skill isn't firing, the description is probably too vague. Make it specific: "Use when the user asks to prep for a sales call or paste a meeting agenda" works. "Helps with meetings" does not.
The smallest useful plugin is a slash command that loads a checklist. Build that first; expand later.
Create the directory:
ship-check/
├── .claude-plugin/
│ └── plugin.json
└── commands/
└── ship.md
The manifest:
{
"name": "ship-check",
"version": "0.1.0",
"description": "Pre-deploy checklist as a slash command",
"author": { "name": "Your Name" },
"license": "MIT"
}
The command file commands/ship.md:
Run through this pre-deploy checklist with the user. For each item, confirm
or flag it. Don't proceed past a failed item without explicit override.
1. All tests passing on main? Run `pnpm test --run` and report the exit code.
2. Migrations applied to staging? Check `prisma migrate status`.
3. Feature flags reviewed? List flags touched in the last 7 commits.
4. On-call notified? Ask the user to confirm yes/no.
5. Rollback plan documented? Confirm the rollback steps are in the PR description.
Output a final status: READY TO SHIP or BLOCKED with reasons.
That's a working plugin. Install it locally:
claude --plugin-dir ./ship-check
Type /ship in the session. Claude runs the checklist. Done.
Adding a skill is the same pattern. Create skills/post-mortem/SKILL.md:
---
name: post-mortem
description: Use when the user wants to write a post-mortem or incident review after an outage. Triggers on "post-mortem," "incident review," "RCA," "what went wrong," or "write up the outage."
---
Walk the user through the post-mortem template:
1. Timeline of events — get specific timestamps in UTC
2. Root cause — distinguish proximate vs underlying
3. Impact — users affected, duration, revenue if known
4. What worked — what we did right during response
5. What didn't — gaps in monitoring, runbooks, handoffs
6. Action items — owner + due date for each, no vague "we should think about..."
Output as Markdown ready to paste into the team wiki.
The frontmatter description is what Claude Code matches against to decide when to activate the skill. Be specific about triggers — vague descriptions never fire.
Three places to find plugins right now:
Anthropic's official repo — anthropic/claude-code-plugins on GitHub. First-party plugins for common workflows: code review, security audits, release notes, init. Curated and well-maintained. Start here.
Community marketplaces — Several GitHub orgs maintain community-curated lists. Quality varies. The pattern is a single marketplace.json at the repo root listing plugins, each linking to its own subdirectory or external repo. Vet plugins before installing — they get your tool permissions.
Cowork plugins — CoworKit ships installable plugins as .plugin files for specific job functions. Different model from the marketplace flow: download the file, install with claude plugin install ./file.plugin. The trade-off is convenience (no marketplace registration) for a slightly less integrated update path.
If you're new to the plugin system, install one official plugin first to see the flow, then start building your own. Reading existing plugins is the fastest way to learn the conventions — most are under 200 lines of Markdown.
CoworKit's Starter Kits are full .plugin files. Each pack bundles 5–8 skills, 2–3 slash commands, and the supporting templates for a specific job function. The Job Search OS kit is the one currently in beta.
Inside the .plugin file: skills for morning prep (reads your calendar and yesterday's commitments, outputs a structured plan), call prep (researches the firm and the person, generates a fixed-layout .docx), email coach (scores drafts against a 5-criterion rubric before you send), evening debrief (reads Granola meeting notes, updates CLAUDE.md and a CRM spreadsheet, surfaces unresolved items), and a top-15 proactive actions skill that produces a weekly initiative list.
Install: download .plugin from the Starter Kits page, then claude plugin install ./job-search-os.plugin. Skills activate on natural-language triggers — "prep me for tomorrow," "review this email," "what should I work on this week." No slash command memorization needed.
The plugin assumes you have a CLAUDE.md set up for your role. If you don't, the CLAUDE.md template guide walks through building one, and the create tool generates a starting file from a short interview.
Do plugins work with Claude Code on every platform?
Plugins require Claude Code 1.0 or later and work on macOS, Linux, and Windows. The plugin format itself is OS-agnostic — anything platform-specific (shell hooks, binaries) needs to handle the OS check inside the plugin code.
Can a plugin access my files outside the project?
Plugins inherit the permissions of the Claude Code session that loaded them. They can read and write what the user has granted the session — usually the working directory and explicitly attached folders. They cannot escalate to system-wide access.
How do I version a plugin?
Use semantic versioning in plugin.json. Bumping version and pushing to the marketplace is enough — users running /plugin update will pick up the new version. Major version bumps should ship a CHANGELOG note in the plugin README.
Can plugins include MCP servers?
Yes. The mcp/ directory in a plugin can contribute server configs. When the plugin installs, those MCP servers register and connect automatically on Claude Code startup. This is the cleanest way to bundle an integration (e.g., a CRM connector) with the skills that use it.
What's the difference between a plugin skill and a CLAUDE.md instruction?
A skill is reusable, scoped, and only activates when its description matches the prompt. A CLAUDE.md instruction is always loaded for the project. Use CLAUDE.md for project-specific facts ("we use Prisma, not raw SQL") and skills for repeatable workflows ("when I ask for a post-mortem, follow these steps").
How do I publish a plugin to the official marketplace?
Open a PR to anthropic/claude-code-plugins adding your plugin to marketplace.json. Anthropic reviews and merges. For community marketplaces, the bar is lower — most accept PRs with light review. You can also self-host by publishing a Git repo with a marketplace.json and letting users /plugin marketplace add your-org/your-repo.
The Job Search OS Starter Kit ships as a single .plugin file with 5 skills built around a working job search — morning prep, call prep, email coach, evening debrief, and a top-15 proactive actions generator. It assumes a CLAUDE.md with your pipeline, target firms, and comp floor, and it reads from Granola, Gmail, and a CRM spreadsheet to keep state in sync. Free during beta. Download and install in one command at coworkit.online/missions/job-search. If you need help building the CLAUDE.md the plugin runs on, the generator walks through it.
Practical guides and prompt patterns — no fluff, unsubscribe any time.