ExplainLLM LogoExplainLLM
Lesson 21Automation

Creating Plugins

Shareable extensions

How plugins work and why they matter

A plugin for Claude Code is just a folder whose root holds a .claude-plugin/ directory with a single manifest file, plugin.json, alongside the component directories commands/, agents/, hooks/, and skills/. Note that those directories sit next to .claude-plugin/, not inside it — placing them inside .claude-plugin/ is a common mistake. The plugin.json manifest shown below holds no logic and lists no components: it carries only metadata — the plugin's name, version, description, and author (plus optional homepage and license). Claude Code discovers the components automatically by their directory-name convention, so you never have to register each file by hand.

The directory tree in the "Plugin Structure" block reflects the naming convention Claude Code follows. Each command is a .md file under commands/; its YAML front matter between the --- lines sets the command name, description, and arguments, and the body is the instruction the agent runs. In the deploy.md example a required environment argument is declared, and the $1 placeholder injects the first supplied argument straight into the prompt. A plugin introduces no new language: it repackages commands, skills, and rules you already know into a single distributable module.

Reach for plugins when the same techniques are needed across many projects or your whole team: a shared review style, deploy steps, security rules. The main benefit is portability — clone or copy the folder and the command set appears for everyone. Mind the common pitfalls too: keep secrets and tokens out of the plugin (it lands in a shared repository), version changes with semver so colleagues can see what moved, and always test locally with claude --plugin-dir ./my-plugin before publishing, so you catch a broken manifest before anyone else does.

What are Plugins

Plugins are a way to package and distribute a collection of commands, skills, agents, and rules for Claude Code.

What you can include:

  • • Slash commands
  • • Agent skills
  • • Custom agents
  • • Hooks
  • • Modular rules

Use cases:

  • • Team standards
  • • CI/CD integrations
  • • Specific workflows
  • • Open source tools
Plugin Structure
my-team-tools/          # Plugin root
├── .claude-plugin/
│   └── plugin.json     # Metadata only
├── commands/           # Slash commands
│   ├── deploy.md
│   └── rollback.md
├── skills/             # Agent skills
│   ├── security-audit.md
│   └── performance-check.md
├── agents/             # Custom agents
│   └── reviewer.md
├── hooks/              # Hooks configuration
│   └── format.json
└── rules/              # Modular rules
    └── typescript.md
plugin.json (Manifest)

The plugin.json file describes the plugin and its components:

{
  "name": "my-team-tools",
  "version": "1.0.0",
  "description": "Team-specific Claude Code tools",
  "author": "Your Team",
  "homepage": "https://github.com/your-team/my-team-tools",
  "license": "MIT"
}
Example Command in Plugin

commands/deploy.md:

---
name: deploy
description: Deploy to staging or production
arguments:
  - name: environment
    description: Target environment (staging/production)
    required: true
---

Deploy the current branch to $1:

1. Run tests to ensure everything passes
2. Build the application
3. Deploy using our CI/CD pipeline
4. Verify deployment health
5. Report status with URL
Using Plugins

Plugins can be used in several ways:

Local Testing

claude --plugin-dir ./my-plugin

In Project

Place .claude-plugin/ at project root — plugin will load automatically

Globally

~/.claude/plugins/my-plugin/
Distributing Plugins

Plugins can be distributed via:

Git repository

Clone to ~/.claude/plugins/

npm package

Publish as npm package

Internal registry

For enterprise use

Direct copy

Copy plugin folder

Plugin Creation Tips

  • 1.Document each command with usage examples
  • 2.Version the plugin using semver
  • 3.Test locally before distribution
  • 4.Don't include secrets in plugins

Frequently asked questions

What is a Claude Code plugin?

A plugin is a .claude-plugin/ folder with a plugin.json manifest and subdirectories for commands, skills, agents, hooks, and rules. The manifest holds no logic — it declares the plugin's name and version and uses file globs to say where the components live. Claude Code loads everything listed at startup, so you never register each file by hand.

How do I install a Claude Code plugin?

For local testing run claude --plugin-dir ./my-plugin pointing at the plugin folder. To load it automatically in one project, place the .claude-plugin/ folder at the project root. To use it across all projects, copy or clone the plugin into ~/.claude/plugins/my-plugin/.

How is a plugin different from a single slash command?

A single slash command is one .md file. A plugin bundles several commands, agent skills, agents, hooks, and rules into one distributable module described by plugin.json. That's useful when the same set of techniques is needed across many projects or a whole team — clone the folder and the commands appear for everyone.

How do I distribute a Claude Code plugin to my team?

Distribute a plugin via a Git repository (clone into ~/.claude/plugins/), an npm package, an internal registry for enterprise, or a direct folder copy. Before publishing, version changes with semver, keep secrets and tokens out of the plugin, and test it locally with claude --plugin-dir so you catch a broken manifest early.

Lesson Quiz

1 of 1

1.How do plugins extend Claude Code functionality?

Related recipes

This lesson is part of a structured LLM course.

My Learning Path