Plugin Structure for Claude Code
Official Anthropic skill for Claude Code plugin layout, manifests, components, and automatic discovery.
- Skill Road
- 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.
Installation instructions
This guide turns Anthropic's official plugin-structure guidance into a reviewable setup workflow. It is useful for a new plugin and for migrating an existing .claude customization into a distributable extension.
Step 1: Create the plugin root and manifest
Start with a dedicated plugin root containing the .claude-plugin directory. The plugin.json file belongs only inside that directory. Begin with a unique kebab-case name and add description, version, author, repository, and license metadata only when the team can keep those details accurate.
Place components at the correct level
Do not place skills, agents, commands, or hooks inside .claude-plugin. These directories belong directly at the plugin root. Give each skill its own directory with a SKILL.md file. One skill is enough for a small plugin. As the project grows, the skills layout makes organization clearer and preserves a predictable namespace. Create only the component types the plugin actually needs.
Keep paths portable
Review every path used by hooks, MCP configuration, and scripts. Use CLAUDE_PLUGIN_ROOT so the extension can reach its own files regardless of where it is installed. Absolute paths and assumptions about the current working directory commonly fail when a plugin is loaded from a marketplace, a local folder, or a shared team location.
Step 2: Test locally and inspect changes
Launch Claude Code for a local test with the plugin directory option and then try the namespaced skill invocation. Check the help interface, loaded components, and any reported errors. If installation asks for plugin reloading, reload the plugins. A successful load does not prove that a hook, MCP server, or script is secure or appropriate for a production workflow.
Review security before distribution
Read every hook and script before sharing the plugin. Inspect file writes, network connections, environment variables, secrets, and possible changes to external systems. Apply least privilege and require human confirmation for risky operations. Document runtime dependencies and version assumptions. This keeps the structure reproducible while making clear that an architecture guide is not an automated security guarantee.
- Provider
- Anthropic
- License
- Apache-2.0
- Last reviewed
- 09.09.2026
Repository and documentation
Categories
Compatible with
Related guides
Guides and background related to this entry.