Your first Claude Code plugin in 60 minutes, from empty folder to installable bundle

You have a slash command only you need. A skill you copy across three repos. A hook that checks something on every edit. Solo, that works. The moment you want to hand the setup to a colleague, it tips over. Seven files in three places, every person installs differently, nobody knows which version is current.

That is exactly what plugins are for. A plugin is a container that packs slash commands, skills, hooks, sub-agents, MCP servers, LSP servers and themes into one unit. You install it once, you activate it once, you share it as a ZIP, as a Git repo or via a marketplace. Anthropic made the plugin system the standard way to distribute everything that used to be copy-pasted around.

This playbook walks from zero. You can do all 10 steps in 60 minutes and end up with an installable plugin that has one slash command, one skill and one hook. Whoever wants to, hooks up MCP servers at the end.

Step 1, empty folder and the manifest

A plugin is a folder with a fixed structure. Put the folder anywhere, the name is free. For me it lives at ~/dev/plugins/your-plugin-name. What matters is that inside there is a hidden directory .claude-plugin/ with the file plugin.json. That file is the manifest and the only required entry.

~/dev/plugins/your-plugin-name/
└── .claude-plugin/
    └── plugin.json

Content of plugin.json minimal:

{
  "name": "your-plugin-name",
  "version": "0.1.0",
  "description": "What your plugin does in one sentence."
}

That is all you need at the start. Author, homepage, license and so on come later.

Step 2, component directories at the plugin root

Beginner trap number one. You put all component folders NOT in .claude-plugin/, but right at the plugin root next to it. The .claude-plugin/ directory is for manifest and config only. Everything else lives one level up.

These folders are recognised by Claude Code at the plugin root:

• commands/ for slash commands
• skills/ for skills with SKILL.md
• agents/ for sub-agents
• hooks/hooks.json for event hooks
• output-styles/ for custom answer styles
• themes/ for color themes
• monitors/ for status line watchers
• .mcp.json for MCP server configs
• .lsp.json for language servers
• bin/ for executables that auto-join the PATH of the Bash tool when the plugin is active

You do not need all of them. For the first run, commands/, skills/ and hooks/ are enough.

Step 3, first slash command

Drop commands/hello.md. Slash commands are simple Markdown files with YAML frontmatter. The filename becomes the command, so this becomes /hello in Claude Code.

---
description: "Says hello and shows what this slash command does."
---

Write a short hello message and explain what the `your-plugin-name`
plugin suite offers. List the most important slash commands.

That is it. When /hello is invoked, Claude Code renders the file as user prompt and sends it to the model.

Step 4, first skill

Skills are different. Claude decides itself when to use a skill, based on the description in SKILL.md. They live in a sub-folder named after the skill.

skills/
└── code-review/
    └── SKILL.md

Content of SKILL.md:

---
name: code-review
description: "Used automatically when the user asks for a code review, wants to review a pull request, or asks what stands out in a code snippet. Always check security, readability and tests."
---

# Code Review Skill

On every review, check in order:

1. Security: injection vectors, hardcoded secrets, unvalidated input.
2. Readability: variable names, function length, complexity.
3. Tests: coverage for the happy path and at least two edge cases.

Write the review as Markdown with three headlines.

The description block is the most important part. Claude reads it during routing and decides whether the skill fits the current request. Write it so it is clear when the skill should help.

Step 5, first hook

Hooks are small scripts that fire on certain events. Very useful for lint checks, audit logs, memory updates. In the plugin they live in hooks/hooks.json or directly in the manifest.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date +%H:%M:%S) edit by $CLAUDE_USER\" >> ~/.claude/edits.log"
          }
        ]
      }
    ]
  }
}

That logs every file edit with timestamp into a local log file. Small, but shows the pattern. More complex hooks call bash scripts that live in bin/.

Step 6, MCP server optional on top

If your plugin should ship an MCP server, drop .mcp.json at the plugin root. Format is identical to the project-local .mcp.json you may already know.

{
  "mcpServers": {
    "your-tool": {
      "command": "node",
      "args": ["./bin/your-mcp-server.js"]
    }
  }
}

The path is relative to the plugin root. The bin/ directory is automatically added to the PATH once the plugin is active, so a bare command name without ./bin/ prefix also works.

Step 7, activate and test locally

Before you think about distribution, test locally. In Claude Code that goes through the slash command /plugin. In the Discover tab you can install plugins from activated marketplaces. For your not-yet-published plugin you take the Manage tab and add it as a filesystem source.

Alternatively via CLI:

claude plugin install --source ~/dev/plugins/your-plugin-name

Behind the scenes Claude Code writes your activation into ~/.claude/settings.json under enabledPlugins. The entry looks like this:

{
  "enabledPlugins": {
    "local/your-plugin-name": true
  }
}

Reload, then type /hello. If the slash command shows up, the plugin is alive.

Step 8, marketplace setup or URL distribution

Two paths to distribute the plugin. First option, you build your own marketplace. That is a Git repo with a .claude-plugin/marketplace.json that lists all plugins the marketplace offers.

Minimal marketplace structure:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── your-plugin-name/
        ├── .claude-plugin/plugin.json
        ├── commands/
        ├── skills/
        └── hooks/

marketplace.json lists which plugin folders in the repo are available. Other users then add your marketplace with /plugin marketplace add github:your-handle/my-marketplace.

Second option is --plugin-url. You pack the plugin as ZIP, upload it somewhere, and colleagues start Claude Code with claude --plugin-url https://example.com/your-plugin-0.1.0.zip. That loads for a session, no permanent setup. Details in the separate playbook plugin-bundle-via-url-distribution.

For most teams, marketplace is the right choice. URL distribution is good for one-off tests or for people who do not want anything installed permanently.

Step 9, understand the trust boundaries

Important thing many overlook at the start. Plugins can run hooks and call bash scripts in bin/. That is power and that is risk. Anthropic built in two protections.

The first, plugins can NOT control the full settings.json. Only the two keys agent and subagentStatusLine are allowed. Everything else is ignored when a plugin tries to set it. Meaning a malicious plugin cannot silently register MCP servers for you or bend permissions.

The second, trust prompts. On first activation Claude Code asks whether you trust the plugin. IT admins can lock this hard via strictKnownMarketplaces as a managed setting. With pluginTrustMessage a custom trust prompt can be set, for example for compliance notices.

For your own plugins that you build yourself, all this is transparent. The moment you install plugins from third parties, read the plugin source first. Hooks that do curl | bash are red flags.

Step 10, version and commit

Last step. Your plugin is alive. Before you share it, clean up versioning. Bump version in plugin.json to 1.0.0 once the first stable variant is ready. Tag the Git commit with the same value.

What should be committed: everything except user-specific logs. What must be out: API keys in hook commands, personal paths, local test outputs. Plugins are exactly like code, read through critically once before you push.

Recommendation for versioning, semantic versioning is overkill for solo plugins. It is enough to use 0.1.0 for "first variant", 0.2.0 for "new skill added", 1.0.0 for "I have been using this daily for two weeks and nothing broke".

What's next

When your plugin stands and three people use it, the next step comes. Whoever wants to distribute the plugin as ZIP URL jumps to plugin-bundle-via-url-distribution. Whoever wants to build a full marketplace with own repo and plugin selection, looks at the Anthropic docs on plugin marketplaces (link below). Whoever wants to integrate the plugin into CI, combines it with claude-code-headless-in-ci-cd.

One thing I learned after my third plugin: keep them small. One plugin per use case, not one mega plugin with everything in it. If a plugin has seven skills and twelve slash commands, split it. Colleagues prefer to install three small plugins with clear function over one big one that half fits.

Source

Sources from the official Claude Code docs:

• Plugin manifest, component directories, hook format, trust boundaries: https://code.claude.com/docs/en/plugins-reference
• Marketplace setup and CLI commands (/plugin marketplace add etc): https://code.claude.com/docs/en/plugin-marketplaces

Verification date: 2026-05-08. If you look for plugin features that are not here, check both pages before relying on third-party sources.