Can I use custom paths for my plugin components?

Yes, you can define custom paths for commands, agents, or hooks within the plugin.json manifest, which will supplement the default auto-discovery directories.

Where should the plugin.json manifest be located?

The plugin.json manifest must be placed inside a directory named .claude-plugin/ at the root of your plugin folder.

What naming convention should I use for plugin files?

It is highly recommended to use kebab-case (lowercase words separated by hyphens) for all files and directories to ensure cross-platform compatibility.

What is the purpose of the ${CLAUDE_PLUGIN_ROOT} variable?

It is an environment variable used to reference the plugin's root directory, ensuring that paths remain portable across different operating systems and installation locations.

How does Claude Code find my plugin's commands and agents?

Claude Code uses auto-discovery to scan root-level directories named commands/, agents/, and skills/ for relevant markdown files and configurations.

Plugin Architecture & Structure

Name: Plugin Architecture & Structure
Author: iButters

byiButters

•

Developer Tools

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

About

This skill provides comprehensive guidance for developers building Claude Code plugins, ensuring they adhere to the required directory structures and naming conventions for automatic component discovery. It covers essential architectural topics such as configuring the plugin.json manifest, organizing commands and agents, setting up event hooks, and implementing portable pathing using the ${CLAUDE_PLUGIN_ROOT} environment variable. By following these standardized patterns, developers can create modular, maintainable, and portable plugins that integrate seamlessly with the Claude Code environment.

Key Features

Detailed manifest (plugin.json) configuration and metadata standards
Standardized directory layout patterns for automatic component discovery
Best practices for file naming conventions and component registration
Portable path management using the ${CLAUDE_PLUGIN_ROOT} variable
Organizational guidance for commands, agents, skills, and hooks
1 GitHub stars

Use Cases

Organizing complex plugin logic into modular agents and auto-activating skills
Troubleshooting component loading issues and manifest configuration errors
Scaffolding a new Claude Code plugin from scratch with the correct hierarchy

About

Key Features

Detailed manifest (plugin.json) configuration and metadata standards
Standardized directory layout patterns for automatic component discovery
Best practices for file naming conventions and component registration
Portable path management using the ${CLAUDE_PLUGIN_ROOT} variable
Organizational guidance for commands, agents, skills, and hooks
1 GitHub stars

Use Cases

Organizing complex plugin logic into modular agents and auto-activating skills
Troubleshooting component loading issues and manifest configuration errors
Scaffolding a new Claude Code plugin from scratch with the correct hierarchy