How to Build a Claude Plugin from Scratch in 2026

Published 8 June 2026 by Yanni Papoutsis

TL;DR: A Claude plugin is a portable bundle of capabilities: skills (folders containing a SKILL.md), slash commands, subagents, and MCP connectors, all described by one plugin.json manifest. To build one from scratch: scaffold a plugin folder, write .claude-plugin/plugin.json with a name, version, and description, place each skill in skills/<skill-name>/SKILL.md, wire optional MCP servers in .mcp.json, then zip the folder with a .plugin extension for Cowork or push it to a Git repository and add it as a marketplace in Claude Code with /plugin marketplace add. Test by installing locally, confirm each skill triggers from its description text, and bump the version on every release. Below you will find the manifest fields, the full folder tree, packaging commands, installation steps for Cowork and Claude Code, and how marketplaces distribute your plugin to other people.

To build a Claude plugin, you create a folder with a .claude-plugin/plugin.json manifest, add the skills, commands, and MCP connectors you want to ship, then package the folder as a .plugin zip for Cowork or register it in a marketplace for Claude Code. You can build Claude plugin bundles like this in under an hour, and this guide walks through every step with working examples you can copy.

What is a Claude plugin?

A Claude plugin is a single installable package that bundles related capabilities so Claude can load them together: skills, slash commands, subagent definitions, hooks, and MCP connectors. Instead of installing ten skills one at a time, you install one plugin and get the whole toolkit in a single step.

The five component types live in predictable places inside the plugin folder:

Skills are the heart of most plugins. A skill is a folder with a SKILL.md file whose YAML frontmatter tells Claude when to load it. MCP connectors follow the open Model Context Protocol, so one plugin can teach Claude a workflow and connect it to the external services that workflow needs. The official reference for all of this lives in the Claude documentation.

Plugins shine when you have a system, not a single trick. My 21-agent product pipeline and 21-agent GTM pipeline each ship as one plugin carrying 21 sequential skills, which would be painful to install individually.

What do you need before you start?

You need access to Claude with Cowork or Claude Code, a text editor, and the zip command line tool, nothing more. Plugins are plain folders of markdown and JSON, so there is no build toolchain, no compiler, and no framework to learn.

If you plan to distribute your plugin publicly you will also want a Git hosting account for the marketplace repository. If your plugin includes MCP connectors, have the connector documentation handy, and remember the golden rule: configuration files in a plugin must only ever contain placeholders such as YOUR_API_KEY, never real credentials.

How do you build a Claude plugin step by step?

The short version: scaffold the folder, write the manifest, add skills, wire optional connectors, package the folder, install it, then publish through a marketplace. Here is each step in detail.

Step 1: Scaffold the plugin folder

Create the folder structure first. The only mandatory piece is .claude-plugin/plugin.json; everything else is optional.

mkdir -p session-tools/.claude-plugin
mkdir -p session-tools/skills/cowork-navigator/references
mkdir -p session-tools/skills/file-organization
mkdir -p session-tools/commands

The finished tree for a small productivity plugin looks like this:

session-tools/
  .claude-plugin/
    plugin.json
  skills/
    cowork-navigator/
      SKILL.md
      references/
        companions.md
    file-organization/
      SKILL.md
  commands/
    audit.md
  .mcp.json

Step 2: Write the plugin.json manifest

The manifest identifies the plugin and is the file Cowork and Claude Code read at install time.

{
  "name": "session-tools",
  "version": "1.0.0",
  "description": "Session bootstrap, file naming, and token budget skills for Claude.",
  "author": {
    "name": "Yanni Papoutsis",
    "url": "https://yanni.uk"
  },
  "keywords": ["cowork", "claude-code", "productivity"]
}

Three rules keep manifests healthy: the name must be lowercase with hyphens and unique within any marketplace you publish to, the version should follow semantic versioning so updates are detectable, and the description should say what the plugin does in one sentence because installers display it.

Step 3: Add your first skill

Each skill is a folder containing a SKILL.md with YAML frontmatter. The description field is the trigger surface: Claude reads it to decide when the skill is relevant, so write it like a precise index entry, not marketing copy.

---
name: cowork-navigator
description: Session bootstrap for Cowork. Load on the first message of every session. Loads memory, checks prior work, and auto-loads companion skills. Trigger on: new session, build, deploy, write, export, organise.
---

# Cowork Navigator

1. Read memory/index.md and load entries relevant to the task.
2. Check the working folder for prior session outputs.
3. Load the companion skills listed in references/companions.md.
4. Paraphrase the task and confirm the plan before executing.

Keep the SKILL.md body short and push long material into references/ files that Claude loads on demand; this protects your context window, a discipline I cover in the token budget skill guide. For a deeper worked example of this exact skill, see creating a Cowork navigator skill.

Step 4: Wire MCP connectors and commands (optional)

If your plugin needs external tools, declare MCP servers in .mcp.json at the plugin root. Use placeholders for every credential and tell users to substitute their own values after install.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Never commit a real token to a plugin. Anyone who installs the plugin can read every file in it, and marketplace repositories are public by design. The Model Context Protocol documentation covers server configuration in depth.

A slash command is just a markdown file in commands/:

---
description: Run the session audit checklist
---

Run the audit checklist in skills/file-organization/references/audit.md
against the current working folder and report failures.

Step 5: Package the plugin as a zip

For Cowork, zip the plugin folder and give the archive a .plugin extension. For a single standalone skill, zip the skill folder with a .skill extension instead.

zip -r session-tools.plugin session-tools -x "*.DS_Store"
zip -r cowork-navigator.skill session-tools/skills/cowork-navigator

Name the archive after the plugin and keep old versions; if version 1.1.0 breaks something, you want 1.0.0 on disk to roll back to.

Step 6: Install and test in Cowork and Claude Code

In Cowork, share the .plugin or .skill file in a session and install it when prompted, or add it through the plugin settings. In Claude Code, add a marketplace and install from it:

/plugin marketplace add yanni-uk/claude-plugins
/plugin install session-tools@yanni-uk

Then test the trigger, not just the content. Start a fresh session and phrase a task the way a real user would. If the skill does not load, the fix is almost always the frontmatter description: add the concrete nouns and verbs users actually type. The skill-authoring guidance in the Claude documentation is worth reading before you tune descriptions.

Step 7: Distribute through a marketplace

A marketplace is a Git repository with a .claude-plugin/marketplace.json file listing one or more plugins:

{
  "name": "yanni-uk",
  "owner": { "name": "Yanni Papoutsis" },
  "plugins": [
    {
      "name": "session-tools",
      "source": "./session-tools",
      "description": "Session bootstrap, file naming, and token budget skills."
    }
  ]
}

Users add your marketplace once and can then install or update any plugin in it. Treat releases like software releases: bump the version, note the changes, and never force-push over a tag people have installed.

How is a plugin different from a standalone skill?

A standalone skill is one folder with one SKILL.md, while a plugin is a manifest-led bundle that can carry many skills plus commands, agents, hooks, and MCP connectors. Ship a .skill file when you have a single capability, and a plugin when capabilities belong together or need a connector.

There is also a maintenance difference. A plugin gives you one version number and one install step for the whole system, which matters once you are shipping things like an anti-hallucination skill, a file organization skill, and an SEO checklist skill that are designed to work as a set.

What mistakes should you avoid when building plugins?

The most common failure is a vague skill description, because a skill that never triggers may as well not exist. The rest of the list:

1. Writing description fields like slogans instead of trigger phrases with concrete keywords.
2. Stuffing everything into SKILL.md instead of references/ files, which wastes context on every load.
3. Leaving a real API key or token in .mcp.json; use YOUR_API_KEY style placeholders only.
4. Shipping without a version bump, so users cannot tell whether they have your fix.
5. Duplicate plugin names across marketplaces, which makes /plugin install ambiguous.
6. Never testing in a clean session, where stale context can mask broken triggers.

Frequently asked questions

Do I need to know how to code to build a Claude plugin?

No. A plugin is markdown plus two small JSON files. Skills are written in plain English, and MCP connectors are configuration rather than code. The only command line tool you need is zip.

Can one plugin contain both skills and MCP connectors?

Yes, and that combination is the main reason plugins exist. A plugin can teach Claude a workflow through skills and connect the external services that workflow needs through .mcp.json in the same install.

How do I update a plugin people have already installed?

Bump the version in plugin.json, repackage or push to the marketplace repository, and announce the change. Marketplace installs can pull the update; .plugin file installs need the new file shared again.

Does the same plugin work in Cowork and Claude Code?

The core structure (manifest, skills, commands, MCP config) is shared, so a well-built plugin works in both. A few features such as hooks are Claude Code specific, so keep them optional if you want portability.

Where should I host the marketplace repository?

Any Git host works. Keep the repository public if you want frictionless installs, and remember that public means every file is readable, which is one more reason placeholders are mandatory.

About the author

Yanni Papoutsis builds AI products, automation pipelines, and technical documentation with Claude, and publishes free tooling and guides at yanni.uk.

Next step: Explore 1,000+ free AI tools at yanni.uk/category/all/, or browse the rest of the technical documentation library.

Sources

• Claude documentation (skills, plugins, Claude Code): https://docs.claude.com
• Anthropic: https://www.anthropic.com
• Model Context Protocol: https://modelcontextprotocol.io
• Cloudflare Pages (hosting for yanni.uk): https://developers.cloudflare.com/pages/