Plugin Structure for Claude Code

Plugin Structure for Claude Code is an official skill from Anthropic's claude-plugins-official repository. It is intended for developers and coding agents that need to create a Claude Code plugin, reorganize an existing one, or understand how its components are discovered automatically. The skill is not an executable plugin, a standalone agent, or a replacement for Claude Code. It is a reusable architectural reference that helps a team make consistent decisions about plugin layout and configuration.

What the skill explains

Its central lesson is the separation between the plugin root and the .claude-plugin directory. The plugin.json manifest belongs inside .claude-plugin and defines the plugin identity. Directories for skills, agents, commands, and hooks belong at the plugin root instead. This distinction matters because Claude Code discovers components by convention. A plugin may also place MCP configuration, LSP configuration, monitors, scripts, and default settings at its root. The skill explains which pieces are optional and why a minimal manifest is often easier to maintain than configuration that repeats defaults.

According to the provider, new multi-skill plugins should use a skills directory with one subdirectory per skill. Each skill directory contains a file named SKILL.md with YAML frontmatter and a description that helps Claude decide when the skill is relevant. Commands and agents are organized as Markdown files. Hooks are defined in hooks.json, while .mcp.json can describe external MCP servers. The guidance also covers a plugin containing exactly one skill at the root and explains when a growing project should move to the skills directory layout.

Portable paths and namespaces

A practical focus is the CLAUDE_PLUGIN_ROOT variable. The skill recommends using it in hook commands, MCP arguments, scripts, and resource references rather than hardcoded absolute paths, working-directory assumptions, or home-directory shortcuts. A plugin can therefore remain portable when installed in different locations or by different methods. Claude Code also namespaces plugin skills and commands. A descriptive kebab-case name in plugin.json reduces collisions with other extensions and makes namespaced invocations easier to understand in the help interface.

Boundaries and security considerations

The skill does not scaffold an application and it does not automatically prove that a hook is safe. A plugin may execute shell scripts, change files, connect MCP servers, or start background processes. Teams must therefore review permissions, secrets, network access, prompt-injection exposure, and external state changes separately. According to the provider, local development can load a plugin through the plugin directory option, but actual activation, trust decisions, and execution still depend on the Claude Code installation and the surrounding environment. The skill is consequently useful as an architecture and review checklist, not as a security approval.

Why teams use it

The documentation supports personal experiments as well as versioned plugins shared with a team or community. It provides a path from a quick .claude customization to a self-contained extension with a reproducible layout. Anthropic publishes the skill in the official repository under Apache-2.0. Skill Road lists it as an external Anthropic skill and does not state concrete prices; any terms for Claude Code, models, hosting, or connected services must be evaluated separately from this instructional content.