Module 5: Plugins — Creating and Distributing

1. Module Introduction — From Local Configurations to Distributable Plugins

Description

In the previous modules you created subagents with an identity of their own, gave them persistent memory, coordinated them in parallel, and organized them into teams with a team lead and task board. Everything works. But there's a problem you probably already noticed: your configurations live in a specific project's .claude/agents/. If tomorrow you start a new project, you copy the files manually. If a colleague wants your team lead + backend-agent + frontend-agent configuration, you share a folder over Slack and tell them "put it in .claude/agents/." If you update an agent file, each project that uses it has a different version.

That's the equivalent of distributing code by copying files between machines. It worked in the '90s. Today we have package managers for a reason: versioning, distribution, dependencies, and updates. Claude Code plugins apply that same principle to your agent configurations.

A plugin is an npm package that bundles subagents, skills, hooks, and MCP servers into an installable unit. Instead of copying files, you run claude plugins add @your-org/code-quality-plugin and you have everything configured — the agents, the skills they preload, the validation hooks, all of it. If you publish an update, your colleagues receive it with an update. If you need to pin a version because the new one breaks something, you do it in the manifest.

This module teaches you to create, test, and distribute plugins. You go from "scripts on my machine" to "packages anyone can install."

⚠️ EXPERIMENTAL FEATURE

The Claude Code plugin system is an experimental feature. The claudeCodePlugin API, the directory structure, and the installation commands may change between versions. This module teaches the mental model (packaging configurations for distribution) and the practical implementation according to the specification available as of March 2026.

If the plugin system isn't accessible in your version of Claude Code, each capsule includes alternatives using manual distribution (git submodules, setup scripts). The organization patterns are transferable.

Last functionality check: March 2026

Where Are We in the Guide?

Context in the Guide

This guide has 8 modules organized into 3 phases:

Phase 1: Advanced Subagents (Modules 1-3)            ← COMPLETED
├── Module 1: Custom Subagents                        ✅
├── Module 2: Agent Memory and Scopes                 ✅
└── Module 3: Parallel Sub-Agent Delegation            ✅

Phase 2: Agent Teams and Plugins (Modules 4-6)
├── Module 4: Agent Teams                              ✅
├── Module 5: Plugins: Creating and Distributing       ← YOU ARE HERE
└── Module 6: Advanced Hooks and Headless SDK

Phase 3: Orchestration (Modules 7-8)
├── Module 7: Remote Control and CLAUDE.md for Teams
└── Module 8: Project: Complete Multi-Agent System

Total estimated duration: 8-10 hours (self-paced).

What changes with Plugins?

In module 4 you built a team of 3 agents with local agent files. They work perfectly within that project. Plugins solve what local agent files can't: distribution, versioning, and reuse across projects and teams.

The mental shift is: you stop thinking about "configuration files" and start thinking about "functionality packages." A plugin isn't a folder with agent files — it's a product: it has a version, documentation, dependencies, and a clear contract of what it provides.

The Problem: Copying Files Doesn't Scale

What you experienced in the previous modules

In module 4, you created 3 agent files:

.claude/agents/
├── team-lead.md
├── frontend-agent.md
└── backend-agent.md

They worked. But friction appears when you try to reuse:

Friction 1: New project, same configuration.

cd new-project/
mkdir -p .claude/agents/
cp ../previous-project/.claude/agents/*.md .claude/agents/

You copied the files. But the team lead references teammates by name — are they still the same? The system prompt paths mention src/api/ — does it exist in the new project? You start editing the copied files and now you have two divergent versions.

Friction 2: Sharing with the team.

Slack: "Hey, copy these 3 files to .claude/agents/"
Colleague: "Where exactly do I put them?"
You: "At the project root, in .claude/agents/"
Colleague: "I already have a different frontend-agent.md there"
You: "Rename it, or merge... I don't know"

No naming conventions, no versioning, no conflict resolution. Each person ends up with a slightly different version.

Friction 3: Update.

You improved the team lead's system prompt after 2 weeks of use. Now you have 4 projects with the old version. Do you update them by hand? Which ones did you change locally and which didn't you?

The pattern is familiar

These are exactly the problems that npm solved for code libraries:

Without a package manager	With a package manager
You copy files between projects	`npm install @pkg/name`
Uncertain version	`"@pkg/name": "^1.2.0"`
Manual updates	`npm update`
Unresolved conflicts	Semver + lockfile
"Works on my machine"	Centralized registry

Claude Code plugins apply this same model to agent configurations.

What Is a Plugin

Concrete definition

A Claude Code plugin is an npm package that contains:

my-plugin/
├── package.json          # Manifest with claudeCodePlugin: true
├── agents/               # Subagent files (.md)
│   ├── reviewer.md
│   └── implementer.md
├── skills/               # Skill files (.md)
│   └── api-conventions.md
└── README.md

The package.json includes a special field:

{
  "name": "@team/code-quality-plugin",
  "version": "1.0.0",
  "claudeCodePlugin": true,
  "files": ["agents", "skills"]
}

claudeCodePlugin: true tells Claude Code: "this package contains agent configurations, load them automatically."

What a plugin can contain

┌────────────────────────────────────┐
│           PLUGIN                    │
│                                     │
│  ┌──────────┐  ┌──────────┐        │
│  │ agents/  │  │ skills/  │        │
│  │ .md      │  │ .md      │        │
│  └──────────┘  └──────────┘        │
│                                     │
│  ┌──────────┐  ┌──────────┐        │
│  │ hooks    │  │ MCP      │        │
│  │ (config) │  │ servers  │        │
│  └──────────┘  └──────────┘        │
│                                     │
│  ┌──────────────────────────┐      │
│  │ package.json (manifest)  │      │
│  └──────────────────────────┘      │
└────────────────────────────────────┘

agents/ — .md files with YAML frontmatter. Loaded as available subagents.
skills/ — .md files with domain knowledge. Preloaded to provide context.
hooks — Hook configurations (PreToolUse, PostToolUse, etc.) that activate automatically.
MCP servers — MCP servers scoped to the plugin's subagents.

Installation

From npm:

claude plugins add @team/code-quality-plugin

From a local path (for development):

claude plugins add ./my-plugin

Plugins can be scoped to a project or a user, similar to how Claude Code handles settings.

From Agent Files to Plugin: The Mental Leap

What you have (local agent files)

project-a/
└── .claude/agents/
    ├── team-lead.md
    ├── frontend-agent.md
    └── backend-agent.md

✅ Works in this project
❌ Doesn't transfer automatically
❌ No versioning
❌ No distribution

What you want (plugin)

@your-org/dev-team-plugin/
├── package.json
├── agents/
│   ├── team-lead.md
│   ├── frontend-agent.md
│   └── backend-agent.md
├── skills/
│   └── team-conventions.md
└── README.md

✅ Installable with one command
✅ Versioned with semver
✅ Updatable
✅ Shareable via npm registry

The mindset shift

BEFORE: "I have useful configuration files"
         → I share them over Slack/email/copy-paste
         → Each project has its version
         → No consistency guarantee

AFTER: "I have a tooling product"
          → I publish it to a registry
          → Anyone installs it with one command
          → Explicit versions, controlled updates

It's not about technical complexity — creating a plugin isn't harder than creating a basic npm package. It's about mindset: treating your agent configurations as a product that others (or you in the future) will consume.

Module Objective

By the end of this module you'll be able to:

✅ Explain the anatomy of a plugin: manifest, agents, skills, hooks, MCP servers
✅ Create a plugin from scratch with the correct directory structure and package.json
✅ Write agent files and skill files designed for distribution (relative paths, generic configuration)
✅ Test a plugin locally with claude plugins add ./my-plugin
✅ Understand dynamic loading: how Claude Code loads plugins at the start of a session
✅ Publish a plugin to a local registry (verdaccio) or npm
✅ Handle versioning with semver and version pinning

Professional objective

If you work on a team, plugins are the way to standardize workflows. Instead of documenting "how to configure Claude Code for our project" in a wiki nobody reads, you package the configuration into a plugin that's installed with one command. That's real team infrastructure.

Module Roadmap

Capsule map

#	Capsule	What you'll learn	Type
01	Introduction (this one)	Context, what plugins are, why they matter	Intro
02	Anatomy of a Plugin	Directory structure, package.json, agents, skills, hooks, MCP	Technical
03	Creating a Plugin from a Scaffold	Step by step: create, configure, test locally	Technical
04	Dynamic Loading and Versioning	How plugins load, semver, registries, updates	Technical
05	Project: Complete Plugin	Plugin with 2 subagents + 1 skill, published locally	Project

Learning flow

First you'll understand the anatomy of a plugin — what it contains, how the manifest is structured, and how each component (agents, skills, hooks, MCP) fits into the structure (capsule 02). Then you'll create a plugin from a scaffold — step by step, from npm init to claude plugins add ./my-plugin with verification that everything loads correctly (capsule 03). Next you'll learn dynamic loading and versioning — how Claude Code discovers and loads plugins, how semver works for plugins, and how to publish to private and public registries (capsule 04). Finally, you'll build a complete code quality plugin with reviewer + implementer + conventions skill, test it and publish it (capsule 05).

The progression is: understand the structure → create the plugin → version and distribute → build the complete product.

Each capsule builds on the previous one. You can't create a plugin (03) without understanding its anatomy (02). You can't publish it (04) without having created and tested it (03).

Estimated module duration: 1.25-1.5 hours.

Connection to the Project

Module project: Code Quality Plugin

In capsule 05 you'll create a complete plugin:

reviewer agent — Reviews code looking for quality, security, and convention problems
implementer agent — Implements changes following the team's conventions
api-conventions skill — Domain knowledge about the team's API conventions

@your-org/code-quality-plugin/
├── package.json
├── agents/
│   ├── reviewer.md       ← Reviews code, reports problems
│   └── implementer.md    ← Implements following conventions
├── skills/
│   └── api-conventions.md ← Team's API conventions
└── README.md

The plugin will be installed locally, verified that the agents load correctly, and tested with a real review + implementation scenario.

Connection to the final project (Module 8)

In module 8, the capstone project uses plugins to encapsulate the configuration of each specialized agent in the multi-agent system. Instead of configuring 5+ agents manually, you install plugins that bring all the functionality. The plugins you create here are the building blocks of the complete system.

Prerequisites

Required knowledge

✅ Modules 1-4 completed — Subagents, memory, parallel delegation, Agent Teams
✅ Agent files — You know how to create .md files with YAML frontmatter
✅ Basic npm — You know what package.json, npm init, npm install are
✅ Terminal — You navigate directories, run commands
✅ Git — You version your code (the plugin is also versioned)

Quick check

If you can answer "yes" to these questions, you're ready:

Can you create an agent file with YAML frontmatter in under 5 minutes?
Do you know the difference between npm install and npm install --save-dev?
Do you understand what semver is? (major.minor.patch)
Have you created at least one package.json before?
Can you explain why copying files between projects is fragile?

You don't need

❌ Prior experience with Claude Code plugins — covered completely here
❌ A published npm account — we'll use a local registry
❌ Knowledge of MCP servers — the necessary parts are introduced within the module
❌ Experience with monorepos or advanced workspaces

Module Setup

What you need to have ready

1. Claude Code up to date:

claude --version

Make sure you have the most recent version. The plugin system requires support for claude plugins.

2. Node.js and npm:

node --version   # v18+ recommended
npm --version    # v9+ recommended

3. Verify plugin support:

claude plugins --help

If the plugins command appears, you have support. If not, check the manual alternative section in each capsule.

4. Working directory:

mkdir -p ~/plugins-workshop
cd ~/plugins-workshop

We'll work outside an existing project to create independent plugins.

Limits: What Is NOT Covered in This Module

❌ Advanced hooks and headless SDK — Covered in Module 6. Here we use basic hooks when the plugin needs them
❌ MCP servers from scratch — We introduce how to include an MCP server in a plugin, not how to create one
❌ Publishing to public npm — We cover local and private registries. Publishing to public npm follows the same process but requires an npm account
❌ Plugin monorepos — One plugin per package is enough for this module
❌ Plugin marketplaces — If Claude Code implements a marketplace, the fundamentals of this module apply directly

Manual Alternative: If Plugins Isn't Available

If your version of Claude Code doesn't support the plugin system, you can achieve distribution with existing tools:

npm plugin               →  Git repo with agent files + setup script
claude plugins add ...   →  git clone + cp -r agents/ .claude/agents/
Semver versioning        →  Git tags (v1.0.0, v1.1.0)
npm registry             →  GitHub/GitLab as a registry
Updates                   →  git pull + re-copy

Each capsule includes a "Manual alternative" section with the equivalent. The mental model is identical — the difference is that with plugins the installation and loading are automatic, and without them you manage it with scripts.

Evidence of Success

By the end of this module, you'll know you succeeded if:

✅ You can create a plugin with the correct structure (package.json + agents/ + skills/)
✅ The plugin installs locally with claude plugins add ./path
✅ The plugin's agents appear available in a Claude Code session
✅ The plugin's skills are preloaded automatically
✅ You can explain the difference between a plugin and a folder of agent files
✅ You understand version pinning and why it matters on a team
✅ You can publish to a local registry and have another developer install it

Quick self-assessment test

If you can answer these questions by the end:

Which field in package.json marks a package as a Claude Code plugin?
What's the difference between agents/ and skills/ in a plugin?
How do you test a plugin before publishing it?
What happens if you publish a version with breaking changes without incrementing major?
Why is a plugin better than copying files?

Summary

This module marks the transition from local configurations to distributable packages — from files in .claude/agents/ to installable npm plugins
A plugin is an npm package with claudeCodePlugin: true that bundles agents, skills, hooks, and MCP servers
The problem they solve: copying files between projects doesn't scale — no versioning, no automatic distribution, no consistency
Plugins apply the npm model to agent configurations: semver versioning, registries, install/update with one command
The module project creates a code quality plugin with reviewer + implementer + conventions skill
Everything learned in modules 1-4 (subagents, memory, teams) is the content you package — plugins are the distribution vehicle
The plugin system is experimental (last check: March 2026) — the module provides manual alternatives

Additional Resources

Claude Code Sub-Agents (Anthropic Docs) — Official documentation of subagents as plugin components
Create Custom Subagents — Reference for agent files, YAML frontmatter
Claude Code CLI Reference — Plugin commands and configuration
Claude Code Settings — Permission, hooks, and scope configuration
npm Documentation — package.json — npm manifest reference
Semantic Versioning (semver.org) — The versioning standard plugins use
Claude Code Best Practices — Organization and distribution best practices
Claude Code Overview — General context of Claude Code as a platform

Next capsule: In capsule 02 you'll explore the complete anatomy of a plugin — the directory structure, the manifest in package.json, how the agent files are organized in agents/, the skills in skills/, the hooks in the configuration, and how MCP servers are scoped to the plugin's subagents. By the end you'll know exactly what goes where and why.

← Previous6. Project — Team of 3 Agents with a Task Board Next →2. Anatomy of a Plugin — Agents, Skills, Hooks, and MCP Servers