Skip to main content
The plugin.json file is the manifest for Claude Code plugins, defining metadata, dependencies, and plugin information.

​
File Location

Plugin manifests must be located at: 
plugin-directory/
└── .claude-plugin/
    └── plugin.json
The .claude-plugin directory is required. Claude Code looks for this directory to identify plugins.

​
Basic Structure

Minimal plugin.json:
plugin.json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A helpful plugin for Claude Code",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  }
}

​
Required Fields

​
name
string
required
Unique plugin identifier. Use kebab-case (e.g., my-awesome-plugin).
  • Must be unique across all plugins
  • Used for installation and references
  • Cannot contain spaces or special characters
​
version
string
required
Semantic version (e.g., 1.0.0, 2.1.3).Follow semver:
  • MAJOR.MINOR.PATCH
  • Breaking changes increment MAJOR
  • New features increment MINOR
  • Bug fixes increment PATCH
​
description
string
required
Brief description of what the plugin does. Shown in plugin browser and marketplace.Keep concise (< 200 characters).
​
author
object
required
Plugin author information.Fields:
  • name (string, required) - Author name
  • email (string, optional) - Contact email
  • url (string, optional) - Author website or GitHub profile

​
Optional Fields

​
displayName
string
Human-readable name shown in UI. Defaults to name field.Example: "My Awesome Plugin" (instead of my-awesome-plugin)
​
homepage
string
Plugin homepage URL (documentation, GitHub repo, etc.).
​
repository
string | object
Source code repository.String format:
"repository": "https://github.com/user/plugin"
Object format:
"repository": {
  "type": "git",
  "url": "https://github.com/user/plugin"
}
​
license
string
License identifier (e.g., "MIT", "Apache-2.0").See SPDX License List.
​
keywords
string[]
Search keywords for marketplace discoverability.
"keywords": ["git", "github", "code-review", "automation"]
​
category
string
Plugin category for marketplace organization.Suggested categories:
  • "development" - Development tools
  • "productivity" - Productivity enhancements
  • "code-quality" - Code review and quality
  • "testing" - Testing tools
  • "deployment" - Deployment and CI/CD
  • "documentation" - Documentation tools

​
Plugin Structure

A complete plugin directory: 
my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Plugin manifest (required)
├── commands/              # Slash commands
│   ├── deploy.md
│   └── review.md
├── agents/                # Custom agents
│   └── code-reviewer.md
├── hooks/                 # Lifecycle hooks
│   └── hooks.json
├── skills/                # Skills
│   └── code-analysis/
│       └── SKILL.md
├── scripts/               # Helper scripts
│   └── setup.sh
├── settings.json          # Default plugin settings
└── README.md              # Plugin documentation

​
Real-World Examples

​
Example 1: Security Guidance Plugin

.claude-plugin/plugin.json
{
  "name": "security-guidance",
  "version": "1.0.0",
  "description": "Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns",
  "author": {
    "name": "David Dworken",
    "email": "[email protected]"
  }
}
Plugin contents:
  • Hooks for security warnings
  • Pre-tool-use validation
  • Pattern matching for vulnerabilities

​
Example 2: Ralph Wiggum Plugin

.claude-plugin/plugin.json
{
  "name": "ralph-wiggum",
  "version": "1.0.0",
  "description": "Implementation of the Ralph Wiggum technique - continuous self-referential AI loops for interactive iterative development. Run Claude in a while-true loop with the same prompt until task completion.",
  "author": {
    "name": "Daisy Hollman",
    "email": "[email protected]"
  }
}
Plugin contents:
  • Commands for loop management
  • Stop hooks for loop control
  • State management scripts

​
Example 3: PR Review Toolkit

.claude-plugin/plugin.json
{
  "name": "pr-review-toolkit",
  "version": "1.0.0",
  "description": "Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification",
  "author": {
    "name": "Daisy",
    "email": "[email protected]"
  }
}
Plugin contents:
  • Multiple specialized agents
  • Review commands
  • Analysis tools

​
Default Settings

Plugins can ship with default settings:
settings.json
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(gh:*)"
    ]
  },
  "disallowedTools": []
}
Plugin settings are automatically applied when the plugin is enabled. Users can override them in their own settings.json.

​
Plugin Installation Sources

Plugins can be installed from:

​
Git Repository

claude plugin install https://github.com/user/my-plugin
Requirements:
  • Repository must contain .claude-plugin/plugin.json
  • Can specify branch, tag, or commit

​
NPM Package

claude plugin install npm:@scope/my-plugin
claude plugin install npm:[email protected]
Requirements:
  • Package must contain .claude-plugin/plugin.json
  • Supports version pinning
  • Supports custom registries

​
Local Directory

claude plugin install /path/to/my-plugin
claude plugin install ~/plugins/my-plugin

​
Marketplace

Install from configured marketplaces: 
claude plugin browse
# Select plugin from list

​
Plugin Validation

Validate your plugin before publishing: 
claude plugin validate /path/to/my-plugin
Checks:
  • plugin.json exists and is valid JSON
  • Required fields present
  • Version follows semver
  • Referenced files exist
  • Hooks configuration is valid
  • Commands have valid frontmatter

​
Marketplace Configuration

To publish to a marketplace, add your plugin to the marketplace JSON:
marketplace.json
{
  "plugins": [
    {
      "name": "my-plugin",
      "source": "https://github.com/user/my-plugin",
      "version": "1.0.0",
      "description": "A helpful plugin",
      "category": "development",
      "installCount": 42
    }
  ]
}

​
Versioning Best Practices

Follow semver strictly:MAJOR (1.0.0 → 2.0.0)
  • Breaking changes to commands
  • Removed features
  • Changed hook behavior that breaks compatibility
MINOR (1.0.0 → 1.1.0)
  • New commands or features
  • New agents or skills
  • Backward-compatible enhancements
PATCH (1.0.0 → 1.0.1)
  • Bug fixes
  • Documentation updates
  • Performance improvements
If your plugin depends on external tools:
{
  "description": "Requires: gh CLI v2.x, jq v1.6+"
}
Document in README.md and validate in Setup hook.
Maintain a CHANGELOG.md:
# Changelog

## [1.1.0] - 2026-03-03
### Added
- New `/review-pr` command
- Support for GitHub Enterprise

### Fixed
- Fixed crash when PR has no comments

## [1.0.0] - 2026-02-15
- Initial release

​
Publishing Checklist

Before publishing your plugin:
  • plugin.json has all required fields
  • Version follows semantic versioning
  • Description is clear and concise
  • README.md documents installation and usage
  • All commands have descriptions
  • Hooks are documented
  • Plugin validates without errors
  • Tested with claude plugin install /path/to/plugin
  • License file included
  • Examples and screenshots in README

​
Environment Variables

Plugin scripts have access to:
​
CLAUDE_PLUGIN_ROOT
string
Absolute path to plugin directory.
# In hook script
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate.py
​
CLAUDE_SESSION_ID
string
Current session identifier.
# Create session-specific file
STATE_FILE="${CLAUDE_PLUGIN_ROOT}/.state-${CLAUDE_SESSION_ID}.json"

​
Next Steps

Plugin Development

Learn how to create your own plugins

Command Development

Create custom slash commands

Build docs developers (and LLMs) love

Get started for freeTalk to us