plugin-structure

This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.

20,213stars2,508forksUpdated 5/20/2026

Documentation #commands-agents-skills-hooks #claude-code #manifest-configuration #documentation #directory-structure #plugin-development

Security Assessment

Medium Risk(60/100)

Detected risks:

Privilege Escalation([examples/advanced-plugin.md] runAs)

Security Score60/100

About plugin-structure

The `plugin-structure` skill provides comprehensive guidance for creating, organizing, and maintaining Claude Code plugins. It addresses the challenge developers face in understanding the proper layout, configuration, and component integration required for plugins to function seamlessly within the Claude Code ecosystem. By following the recommended structure, users can ensure their plugins are discoverable, maintainable, and compatible with automated tools and the Claude Code runtime.

This skill covers essential aspects of plugin development, including the standardized directory hierarchy, manifest configuration in `.claude-plugin/plugin.json`, and organization of core components such as commands, agents, skills, and hooks. It emphasizes best practices like using kebab-case for naming, leveraging `${CLAUDE_PLUGIN_ROOT}` for portable path references, and understanding the differences between explicit and auto-discovered components. Additionally, it provides guidance on customizing component paths, versioning using semantic versioning, and including optional metadata for author, repository, and licensing information.

Targeted at developers building Claude Code plugins, this skill is ideal for both newcomers seeking to scaffold a plugin from scratch and experienced users aiming to refine their plugin architecture. Use cases include setting up new plugins with proper manifests, organizing component directories for clarity and maintainability, configuring auto-discovery mechanisms, and adhering to naming conventions and manifest rules for plugin compatibility. The skill ensures that plugins are well-structured, easy to navigate, and ready for integration with Claude Code's automated systems.

FAQ

Where should the plugin manifest `plugin.json` be located?

The `plugin.json` manifest must be placed inside the `.claude-plugin/` directory at the root of the plugin.

Can I nest component directories like commands or agents inside `.claude-plugin/`?

No, all component directories must be at the plugin root level, not nested inside `.claude-plugin/`. Only the manifest belongs inside `.claude-plugin/`.

Are custom component paths allowed in the manifest?

Yes, you can specify custom relative paths for components in `plugin.json`. These paths supplement the default directories and must be relative to the plugin root, starting with `./`.