Claude Code Plugin Structure Guide
A practical guide to organizing, configuring, and troubleshooting Claude Code plugins.
The skill recommends relative paths and ${CLAUDE_PLUGIN_ROOT}, reducing hardcoded-path risk. It also discusses secrets and external MCP integrations, but does not systematically define permission boundaries, user confirmation, data flows, sensitive-data handling, external effects, or rollback, so 10 points are deducted.
Directory, manifest, component, and troubleshooting guidance are fairly complete and include diagnosable common errors. However, there is no executed test evidence or CI coverage for key paths, and several discovery, reload, and path behaviors are asserted without proof; scored 8 within the static ceiling.
Trigger phrases, target scenarios, and component categories are clear for plugin creation, scaffolding, and organization. Non-fit boundaries, input/output contracts, version compatibility, and Chinese-language usage are insufficiently defined, so 5 points are deducted.
The material has layered information architecture, progressive-disclosure guidance, naming conventions, examples, references, and maintenance steps. License, release history, changelog, maintenance ownership, and update path remain incomplete; some README resource claims are also not verifiable from the supplied material, so the score is 6.
The skill supplies directly reusable guidance and examples for directory layout, plugin.json, component organization, and path references, covering the core advisory task. Execution verification is absent and users must still validate some examples and behaviors against their installed version; static maximum yields 7.
The evidence includes revision-pinned source material, manifest examples, reference documents, and repository CI snippets, but CI does not cover this skill's key paths and no third-party execution results or independent corroboration are provided; scored 4.
- Claims about auto-discovery, nested-directory support, reload timing, default paths, and custom-path merge behavior are not validated by tests or corroborating official evidence within the skill.
- Examples include MCP, environment variables, Slack, PagerDuty, Datadog, Terraform, and Kubernetes integrations without clearly specifying permissions, secret exposure, data destinations, user confirmation, or failure rollback.
- The skill lacks an explicit skill-level license, changelog, maintenance owner, and compatibility matrix; verify the plugin specification for the target Claude Code version before relying on it.
What it does & when to use it
Plugin Structure is one skill in the Claude Code plugin-development collection. It explains the standard plugin layout, plugin.json metadata, component organization, and automatic discovery for commands, agents, skills, hooks, and MCP servers. It also documents portable intra-plugin paths through ${CLAUDE_PLUGIN_ROOT}, naming conventions, and common loading failures. It is a strong fit for Claude Code plugin authors, but its guidance is tied to Claude Code’s plugin architecture.
Provides directory layouts, plugin.json examples, custom component-path configuration, Markdown formats for commands and agents, SKILL.md organization, hook and MCP JSON examples, and naming conventions. It explains how Claude Code scans and loads plugin components and gives patterns for minimal, full-featured, and skill-focused plugins. It also supplies troubleshooting guidance for missing components, path-resolution errors, failed auto-discovery, and naming conflicts.
- A developer creating a Claude Code plugin from scratch uses it to place the manifest and component directories correctly.
- A team adding slash commands or agents uses it to check file formats and auto-discovery locations.
- A plugin author organizing multiple skills uses it to structure skills/<skill-name>/SKILL.md directories.
- A developer configuring hooks or MCP servers uses it to follow the JSON examples and plugin-root path conventions.
- A team maintaining an existing plugin uses it to review naming, paths, versioning, and portability practices.
Pros & cons
- Covers layout, manifests, components, path references, discovery, and troubleshooting in one guide.
- Includes concrete patterns for minimal, full-featured, and skill-focused plugins.
- Clearly distinguishes default directories from supplemental custom paths and promotes portable path references.
- It is specific to Claude Code’s plugin architecture and requires adaptation elsewhere.
- The source does not provide a standalone installation or release process for this skill.
- The README provides no evidence of a test suite or platform validation for this individual skill.
- MCP servers, hooks, and scripts are optional components; the skill does not require every plugin to use them.
How to install
The source does not document a standalone installation command for this individual skill. It is located at plugins/plugin-dev/skills/plugin-structure/SKILL.md in the repository; the README documents installation of Claude Code itself. On macOS/Linux, run curl -fsSL https://claude.ai/install.sh | bash; on Windows, run irm https://claude.ai/install.ps1 | iex; then run claude from a project directory.
How to use
In a Claude Code environment where the skill is available, ask for plugin-structure help using prompts such as “create a plugin,” “scaffold a plugin,” “set up plugin.json,” or “organize plugin components.” It provides guidance on layouts, manifests, paths, and discovery. The source does not document a separate command for enabling this individual skill.