You've learned how to create Skills that customize Claude's behavior and practiced building several useful ones. Now it's time to understand how to properly package those Skills into Plugins that others can install and use. While Lesson 1 introduced the basic structure of a Plugin, this lesson focuses on the mechanics of creating a well-formed Plugin package that follows conventions and can be shared effectively.

When you create Skills in your .claude/skills/ directory, they're available only to you in that project. A Plugin transforms those local Skills into a portable package. Think of it as the difference between having notes in your personal notebook and publishing a book that others can read. The content is similar, but the packaging makes it shareable.

This lesson walks through the proper structure of a Plugin, the metadata that makes it recognizable, and how to organize your Skills for distribution. You'll also learn about the conventions that make Plugins easy to discover and use.

A Plugin lives in its own directory with a specific structure that Claude recognizes. Think of it like a filing cabinet where everything has its designated drawer. The key is the .claude-plugin/ folder, which contains information about your Plugin — like the label on the outside of the filing cabinet that tells you what's inside. Without this folder and its contents, you simply have a collection of Skills sitting in a directory. With it, you have a distributable package.

Create a directory called my-plugin somewhere on your system, separate from any existing projects. This will be your Plugin package. Inside this directory, create a .claude-plugin/ folder. This hidden folder is what marks your directory as a Plugin. The dot at the start is intentional — it's like putting files in a hidden compartment. On computers, folders starting with a dot are typically used for configuration, not regular files you work with every day.

Inside .claude-plugin/, you need exactly one file: plugin.json. This file is like an index card that describes your Plugin in a format that computers can easily read (called JSON). Here's the minimal structure:

Your Plugin's Skills live in a skills/ directory at the root of your Plugin package. Think of this like having a "Recipes" section in your cookbook — all the recipes (Skills) go in that section. This keeps everything organized and makes it clear where the Skills are located. Create this directory in your my-plugin folder, alongside .claude-plugin/.

Each Skill you want to include gets its own subfolder inside skills/, just like when you create Skills locally. The difference is that these Skills will be packaged together and installed as a unit. When someone installs your Plugin, all these Skills become available in their environment.

Let's create a practical Plugin that includes the Skills from your previous work. First, create the explain-code Skill by making a directory and adding a file:

While the basic plugin.json is sufficient, adding more information makes your Plugin more useful. You can include additional fields that provide context for users. Beyond author and repository, the manifest supports several other metadata fields like homepage, license, and keywords, as well as configuration options for various plugin components. This section covers the most commonly used fields; for a complete reference of all available fields, see the Plugin manifest schema documentation.

The author field credits the creator. This is structured information with a name and optionally an email — like a business card in digital form:

The repository field links to where the Plugin's source code lives. If you're hosting it on GitHub (a website where people share code), you include that link:

Choosing good names matters when creating Plugins. Your Plugin name becomes part of how users discover and remember your package. Follow these conventions to make your Plugin easy to find and understand.

Plugin names should describe what the Plugin does rather than being generic labels. Instead of my-plugin, use code-explainer or git-workflow. The name should hint at the Plugin's purpose. When someone sees code-explainer in a list of available Plugins, they immediately understand what it offers.

Use lowercase letters, numbers, and hyphens only. Avoid spaces, underscores, and special characters. This keeps names consistent across different systems and environments. code-explainer works everywhere, while Code Explainer! might cause problems in some contexts.

If your Plugin focuses on a specific domain, include that in the name. A Plugin with git-related could be ; one for development could be , and one for documentation could be . This helps users filter and find relevant quickly.

Version numbers communicate what has changed in your Plugin over time. Think of them like edition numbers on textbooks. When you see "3rd Edition" on a textbook, you know it's been updated twice since the original. Software versions work similarly but with more detail.

The version number has three parts separated by dots: major.minor.patch. Each part tells you something different about the changes. Understanding when to increment each part helps you communicate changes clearly to users.

Start every new Plugin at version 1.0.0. This signals that the Plugin is ready for use. Some developers start at 0.1.0 for early experimental releases, but once you're confident in your Plugin's functionality, begin at 1.0.0.

The patch number (the third digit) increases for small fixes that don't change how things work — like fixing typos or correcting small mistakes. If you fix a typo in a Skill's instructions, change 1.0.0 to 1.0.1. Think of it like fixing a spelling error in a book's reprint. The content is essentially the same, just corrected.

The minor number (the second digit) increases when you add new features. If you add a new format-output Skill to your Plugin, change to , and reset the patch number to zero. This is like adding a new chapter to a book's next edition — you're giving readers more, but what they already know still works the same way.

Before sharing your Plugin, test it locally to ensure everything works as expected. The simplest way to test your Plugin is to use a special flag when running Claude Code that says "load this plugin for this session only."

Navigate to a test directory where you want to try your Plugin. Then run Claude Code with the --plugin-dir flag pointing to your Plugin directory:

This loads your Plugin for the current session without permanently installing it — like borrowing a library book instead of buying it. Your Plugin's Skills become available, namespaced with your Plugin name.

Once loaded, verify that each Skill works. For Skills like explain-code, invoke it with /my-plugin:explain-code followed by some code, and check that it responds with the expected format. Ask it to explain a function and verify you get an analogy, diagram, step-by-step explanation, and gotcha.

You've learned how to package Skills into distributable Plugins with proper structure and metadata. Plugins use a .claude-plugin/ directory containing plugin.json to declare information like name, description, and version. Skills live in a skills/ directory, each in its own subfolder with a SKILL.md file. All Plugin Skills are invoked using namespaced commands (like /my-plugin:commit) to prevent conflicts between Plugins — similar to using full names to avoid confusion when multiple people share the same first name. The disable-model-invocation: true flag can be used for Skills that should only run when explicitly called. Good naming conventions use lowercase with hyphens and clearly describe functionality. Version numbers work like book editions to communicate changes. Testing locally with the flag before distribution catches issues early.