Where should the plugin.json file be located?

The plugin.json manifest must be located within the .claude-plugin/ directory at the root of your plugin folder to be recognized by Claude Code.

Do I need to list every command in the manifest?

No, Claude Code features an auto-discovery mechanism. Any .md files placed in the commands/ or agents/ directories at the plugin root are automatically loaded.

How do I ensure my plugin works on different operating systems?

Always use the ${CLAUDE_PLUGIN_ROOT} environment variable for all internal path references in your manifest and scripts instead of hardcoded absolute paths.

What is the correct way to structure a Skill within a plugin?

Each skill should have its own subdirectory within the 'skills/' folder, and each must contain a 'SKILL.md' file that defines its name, version, and usage instructions.

Plugin Structure Guide

Name: Plugin Structure Guide
Author: tzachbon

bytzachbon

•

144

Developer Tools

Guides the scaffolding and organization of Claude Code plugins using standardized directory layouts and manifest configurations.

About

This skill provides comprehensive architectural guidance for developers building Claude Code extensions, ensuring plugins follow strict directory conventions and metadata requirements. It simplifies the creation of commands, subagents, and skills by explaining manifest setup, auto-discovery mechanisms, and the critical use of portable path references. Whether you are bootstrapping a new project or refactoring existing logic into a plugin, this skill ensures your components are discoverable, maintainable, and cross-platform compatible.

Key Features

Standardized directory scaffolding for commands, agents, and skills
Comprehensive manifest (plugin.json) configuration guidance
144 GitHub stars
Portable path management using ${CLAUDE_PLUGIN_ROOT} variables
Best practices for organizing hooks, scripts, and MCP server definitions
Optimization of auto-discovery for seamless component loading

Use Cases

Standardizing existing scripts into a portable, shareable Claude Code plugin format
Configuring complex event hooks and MCP servers for automated developer workflows
Scaffolding a new Claude Code plugin from scratch with the correct folder hierarchy

About

Key Features

Standardized directory scaffolding for commands, agents, and skills
Comprehensive manifest (plugin.json) configuration guidance
144 GitHub stars
Portable path management using ${CLAUDE_PLUGIN_ROOT} variables
Best practices for organizing hooks, scripts, and MCP server definitions
Optimization of auto-discovery for seamless component loading

Use Cases

Standardizing existing scripts into a portable, shareable Claude Code plugin format
Configuring complex event hooks and MCP servers for automated developer workflows
Scaffolding a new Claude Code plugin from scratch with the correct folder hierarchy