What is the .claude-plugin directory?

It's required at the repository root and houses either plugin.json for single-plugin repos or marketplace.json for multi-plugin repos.

How do I reference plugin resources in agents and scripts?

Use the CLAUDE_PLUGIN_ROOT environment variable to build portable paths, e.g., bash '${CLAUDE_PLUGIN_ROOT}/.support/scripts/my-script.sh'.

How should I structure components?

Organize commands/, skills/, agents/, and hooks/ under the repository and document everything in a README; follow naming conventions and keep scope focused.

claude-code-plugins

Scanned

npx machina-cli add skill chris-hendrix/claudehub/claude-code-plugins --openclaw

Files (1)

SKILL.md

3.2 KB

Creating Claude Code Plugins

Guidelines for creating and publishing Claude Code plugins with proper structure and marketplace configuration.

Official Documentation:

Repository Structure

All plugin repositories require a .claude-plugin/ directory at the repository root:

Single plugin repository: .claude-plugin/plugin.json - See references/single-plugin.md
Multi-plugin repository: .claude-plugin/marketplace.json - See references/multi-plugin.md

Plugin Components

Plugins can contain:

commands/ - User-invoked actions (/command-name)
skills/ - Domain knowledge (auto-matched)
agents/ - Autonomous specialists (Task tool)
hooks/ - Event-driven automation

Environment Variables

Claude Code provides environment variables for referencing plugin resources:

${CLAUDE_PLUGIN_ROOT} - Absolute path to the plugin's root directory

Usage in agents and scripts:

# Reference plugin scripts from agents
bash "${CLAUDE_PLUGIN_ROOT}/.support/scripts/my-script.sh"

# Reference plugin templates
TEMPLATE="${CLAUDE_PLUGIN_ROOT}/.support/templates/template.md"

Usage in hooks.json:

{
  "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh"
}

This ensures portable paths across different plugin installation locations.

Installation

Local installation:

# Single plugin
/plugin install /path/to/plugin-name

# Multi-plugin (from marketplace)
/plugin marketplace add /path/to/repo
/plugin install plugin-name@repo-name

GitHub installation:

# Add marketplace
/plugin marketplace add username/repo-name

# Install plugin (for single-plugin repos, plugin-name is the repo name)
/plugin install plugin-name@repo-name

Private repositories: Require SSH authentication.

Plugin Development Patterns

Single-purpose plugin:

One focused domain or tool
Minimal components (1-3 skills, 1-5 commands)
Example: Graphite workflow, Linear integration

Workflow plugin:

Coordinates multiple tools/domains
Multiple skills for different areas
Commands that orchestrate workflows
Example: Development workflow (git, PRs, testing)

Multi-plugin repository:

Group related plugins by audience, team, or domain

Best Practices

Start with skills (domain knowledge) before commands
Keep plugins focused on a single purpose or workflow
Use semantic versioning for plugin.json
Test locally before publishing
Document all components in README
Follow naming conventions for all components
Use marketplace.json for repos with 2+ plugins

Sources

Source

git clone https://github.com/chris-hendrix/claudehub/blob/main/.claude/skills/claude-code-plugins/SKILL.mdView on GitHub

Overview

This skill guides you through creating, scaffolding, and configuring Claude Code plugins and marketplaces. It covers repository structure, components, environment variables, installation workflows, and publishing best practices.

How This Skill Works

It describes the .claude-plugin directory layout for both single-plugin (plugin.json) and multi-plugin (marketplace.json) repositories. It defines core components (commands/, skills/, agents/, hooks/) and shows how to reference plugin resources using CLAUDE_PLUGIN_ROOT in agents and scripts, plus how to use marketplace.json for publishing.

When to Use It

Starting a new Claude Code plugin from scratch in a dedicated repository.
Scaffolding a multi-plugin repository to group related plugins.
Setting up marketplace configurations for publishing to Claude Code marketplaces.
Referencing plugin resources in agents, scripts, and hooks using CLAUDE_PLUGIN_ROOT.
Testing local installation with /plugin install and /plugin marketplace add before publish.

Quick Start

Step 1: Create .claude-plugin/ and add a plugin.json for a single-plugin repo or marketplace.json for a multi-plugin repo.
Step 2: Add components under commands/, skills/, agents/, hooks/ and write a README with usage and configuration.
Step 3: Test locally and install using Claude's CLI commands like plugin install and plugin marketplace add before publishing.

Best Practices

Start with domain skills before commands
Keep plugins focused on a single purpose or workflow
Use semantic versioning for plugin.json
Test locally before publishing
Document all components in README

Example Use Cases

A single-plugin repository with .claude-plugin/plugin.json for a focused tool.
A multi-plugin repository organized under .claude-plugin/marketplace.json to group related plugins.
A workflow plugin that coordinates commands across git, tests, and PRs.
An example referencing scripts via CLAUDE_PLUGIN_ROOT in agents.
Installing a plugin from GitHub marketplace with /plugin marketplace add and /plugin install.

Frequently Asked Questions

Add this skill to your agents