Create a Claude Code plugin

Learn · guide · AI System

▶Start here

You are here: Learn → Guides → AI System → Create a Claude Code plugin This guide is for you if: you have an MCP server (or skill, or command) and want people to install it in one step. Worked example: the zajlibrary plugin that ships the ZajLibrary MCP server.

A bare MCP server gives an agent capability — tools it can call. But the agent doesn’t know when to reach for them. A plugin solves both: it bundles the MCP connection and a skill that teaches the trigger, so one install wires up the whole experience.

graph LR
  Install["claude plugin install"] --> MCP[".mcp.json<br/>→ tools (capability)"]
  Install --> Skill["SKILL.md<br/>→ when to use (judgment)"]
  Install --> Cmd["/command<br/>→ one-shot entry"]

---

Anatomy of a plugin

A Claude Code plugin is a directory with a manifest and conventional component folders. Auto-discovery does the rest — you only create folders for what you ship.

• Directoryzajlibrary-plugin/

  • Directory.claude-plugin/

    • plugin.json required — name + metadata
  • .mcp.json registers the MCP server
  • Directoryskills/

    • Directoryzajlibrary/

      • SKILL.md when + how to use it
  • Directorycommands/

    • library.md the /library command
  • README.md

Two rules catch most mistakes:

1. The manifest must live in .claude-plugin/plugin.json.
2. Component folders (skills/, commands/, .mcp.json) live at the plugin root, not inside .claude-plugin/.

---

Build it

1. The manifest

plugin.json needs only a kebab-case name; everything else is recommended metadata (version, description, author, repository, keywords).

2. Bundle the MCP server

A plugin’s .mcp.json uses the same schema as any MCP config. For a hosted server it’s just a URL:

{ "mcpServers": { "zajlibrary": { "type": "http", "url": "https://library.zajapps.com/api/mcp" } } }

3. Add a skill so the agent knows when

The skill’s description is the trigger — write it as “use when…”. This is the difference between an agent that can search your library and one that does, unprompted, at the right moment.

4. (Optional) a slash command

A one-shot entry point — e.g. /library <query> that searches and summarizes. Commands are Markdown files in commands/; $ARGUMENTS carries the user’s input.

5. Make it installable — the marketplace manifest

A repo becomes an installable marketplace with a .claude-plugin/marketplace.json at its root listing the plugin(s) by relative source path. Then anyone can add the marketplace and install.

---

Install and verify

claude plugin marketplace add your-org/your-repo
claude plugin install zajlibrary@zajlibrary
claude mcp list          # → plugin:zajlibrary:zajlibrary  ✓ Connected

Verify the real install path

Test the documented flow, not just a local shortcut. ZajLibrary’s plugin was verified end-to-end: marketplace add → install → plugin enabled → bundled MCP ✓ Connected → skill + command resolved in the plugin cache. A marketplace points at a repo’s default branch, so the plugin must be on main (or the branch you tell users) for the public install to work.

---

MCP vs. skill vs. plugin — when to use which

You want…	Ship a…
Tools an agent can call	MCP server
Guidance on when/how to act	Skill
Both, installable in one step	Plugin (bundles MCP + skill + command)

---

Next

Build an MCP server for your docs site The server this plugin wraps — build-time index + one Vercel function.

Install the ZajLibrary plugin The worked-example plugin in the repo's zajlibrary-plugin/.

→Next step

Back to Guides, or read Build an MCP server for the server side.