plugin-structure

Claude Code plugins require a standardized directory structure with plugin.json in a .claude-plugin directory at the root. This layout enables auto-discovery of components like commands, agents, skills, and hooks organized in their respective subdirectories using kebab-case naming conventions.

The plugin.json manifest specifies metadata, component loading paths, and configuration for your plugin. It defines which directories Claude Code scans for components and supports custom path definitions, allowing you to organize commands, agents, skills, and hooks according to your project structure.

Organize each component type in separate directories following kebab-case naming. Each component file requires YAML frontmatter for metadata. This structure ensures clarity, scalability, and enables Claude Code's parallel loading from both default and custom paths specified in plugin.json.

Plugin auto-discovery requires plugin.json in .claude-plugin and components in correctly named directories with YAML frontmatter. Verify kebab-case directory names, proper manifest configuration, and that component files include required metadata. Use ${CLAUDE_PLUGIN_ROOT} for portable path references.

Use ${CLAUDE_PLUGIN_ROOT} variable for all file path references instead of hardcoded absolute paths. This portable reference syntax ensures your plugin functions consistently across Windows, macOS, and Linux environments without modification.

Use kebab-case for all directory names and component files within your plugin. Include YAML frontmatter in each component for metadata. Keep plugin.json at the root inside .claude-plugin. These conventions enable reliable auto-discovery and maintainable plugin structure.