Plugin Structure

To structure a Claude Code plugin, create a root .claude-plugin/plugin.json file alongside subdirectories for commands, agents, skills, and hooks. This establishes a predictable skeleton that enables the system's auto-discovery patterns to find and load your components automatically.

A SKILL.md frontmatter schema is a required metadata block at the top of each skill file that enables autonomous loading and activation. It defines naming conventions and activation criteria so the Claude Code environment can discover and trigger your skills without manual configuration.

The best way to scaffold a Claude Code plugin is to start with a root .claude-plugin/plugin.json manifest and a skills/ subdirectory containing your first SKILL.md. Following this standardized layout ensures cross-platform compatibility and maintainability across all plugin components.

Yes, a Claude Code plugin requires a root .claude-plugin/plugin.json manifest to function properly. This manifest defines the plugin's structure, enables auto-discovery for commands and agents, and enforces the standardized skeleton needed for portable path references.

Auto-discovery for Claude Code plugin components works by scanning the canonical directory layout for commands, agents, skills, and hooks. When each component follows the defined naming conventions and SKILL.md frontmatter schema, the system automatically loads and activates them without explicit registration.

Plugin skills fail to activate when the SKILL.md frontmatter schema is missing or incorrectly formatted. Ensuring each skill file contains the required frontmatter and follows the established naming conventions will satisfy the discovery and activation rules needed for autonomous loading.