Creating Plugins
Shareable extensions
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.
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
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.mdThe 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"
}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 URLPlugins can be used in several ways:
Local Testing
In Project
Place .claude-plugin/ at project root — plugin will load automatically
Globally
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.
This lesson is part of a structured LLM course.
My Learning Path