plugin-structure

To structure a Claude Code plugin for auto-discovery, place components like commands, agents, skills, and hooks in specific expected directories. Use a root-level SKILL.md with YAML frontmatter for skills and a valid plugin.json manifest to ensure reliable loading without guesswork.

The plugin.json manifest for a Claude Code plugin contains required and recommended fields that define the plugin's configuration. It safely specifies additional component paths and establishes how auto-discovery rules locate your commands, agents, skills, hooks, and MCP servers.

The ${CLAUDE_PLUGIN_ROOT} variable provides portable path references for Claude Code plugins. You apply it in manifest configurations and hook scripts to avoid hardcoded installation paths, ensuring your plugin components work reliably across different environments.

Claude Code plugin components fail to load when the directory layout violates auto-discovery rules, uses incorrect naming conventions like failing to enforce kebab-case, or relies on hardcoded paths instead of ${CLAUDE_PLUGIN_ROOT}. Troubleshoot by verifying manifest placement and path resolution.

Yes, Claude Code plugin skills require a root-level SKILL.md file formatted with YAML frontmatter. This specific file format satisfies the manifest placement and path rules needed for the auto-discovery mechanism to correctly identify and activate the skill component.

The best way to scaffold a Claude Code plugin with multiple component types is to organize commands, agents, skills, hooks, and MCP servers into the correct directory structure. Enforce kebab-case naming and configure the plugin.json manifest to align with auto-discovery expectations.