---
title: "Plugin Structure for Claude Code: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/anthropic-plugin-structure/
description: "Describes the Claude Code plugin layout: the .claude-plugin/plugin.json manifest, root-level commands, agents, skills and hooks directories, .mcp.json, auto-discovery and ${CLAUDE_PLUGIN_ROOT} paths."
---

# Plugin Structure for Claude Code: review, setup & limitations · Undominated.ai

> Describes the Claude Code plugin layout: the .claude-plugin/plugin.json manifest, root-level commands, agents, skills and hooks directories, .mcp.json, auto-discovery and ${CLAUDE_PLUGIN_ROOT} paths.

[← Explore all skills](/skills/)

AGENT DEVELOPMENT / Anthropic

# Plugin Structure for Claude Code

Describes the Claude Code plugin layout: the .claude-plugin/plugin.json manifest, root-level commands, agents, skills and hooks directories, .mcp.json, auto-discovery and ${CLAUDE_PLUGIN_ROOT} paths.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/anthropics/claude-plugins-official/tree/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 7 linked sources
 Publisher Anthropic
 Licence [Apache-2.0 ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE)
 Revision 41f32e407b45
 [Read what was—and wasn’t—checked ↓](#review)

“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.”

 [Anthropic · upstream description ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - It states the layout rules a plugin loader relies on: the manifest lives at .claude-plugin/plugin.json, only its name field is required, and the commands, agents, skills and hooks directories sit at the plugin root, not inside .claude-plugin/.
- It says custom component paths in plugin.json supplement the default directories rather than replace them, must be relative and start with ./, and it gives minimal, full-featured and skill-only plugin layouts.

### A good fit for

 - Lay out a new Claude Code plugin with .claude-plugin/plugin.json and root-level commands/, agents/, skills/ and hooks/ directories
- Add custom component paths to plugin.json without losing the default directories
- Replace hardcoded paths in hook and MCP server commands with ${CLAUDE_PLUGIN_ROOT}

### Weigh up before choosing

 - Last commit touching plugins/plugin-dev/skills/plugin-structure at revision 41f32e40: 2026-02-05 (2438937b).
- Its agent file example uses description and capabilities frontmatter, while the agent-development skill of the same plugin lists name, description, model and color as required fields and has no capabilities field.
- Its MCP Servers section names .mcp.json at the plugin root or inline plugin.json as the location and gives an example format with servers under an mcpServers key, while the mcp-integration skill of the same plugin shows a .mcp.json example with server names at the top level.
- plugin-dev, which contains this skill, prints "MIT License - See repository for details" under its README's License heading; the LICENSE file beside it is the Apache License, Version 2.0. This record follows the LICENSE file.
- plugin-structure reaches users through a plugin-dev install line that names claude-code-marketplace; this repository's marketplace file is named claude-plugins-official.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - plugins/plugin-dev/skills/plugin-structure/SKILL.md
- plugins/plugin-dev/skills/plugin-structure/README.md
- plugins/plugin-dev/skills/agent-development/SKILL.md (frontmatter fields)
- plugins/plugin-dev/skills/mcp-integration/SKILL.md (.mcp.json method)
- plugins/plugin-dev/README.md
- plugins/plugin-dev/LICENSE
- .claude-plugin/marketplace.json (name and plugin-dev entry)

### Our findings

 - The skill is Markdown only: SKILL.md, README.md, two references and three example layouts; its frontmatter declares no allowed-tools.
- Auto-discovery, per the SKILL.md: Claude Code reads .claude-plugin/plugin.json, scans commands/ and agents/ for .md files and skills/ for subdirectories with SKILL.md, and loads hooks and MCP servers from hooks/hooks.json, .mcp.json or the manifest.
- It lists nine hook events: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact and Notification.
- It says never to use hardcoded absolute paths, working-directory-relative paths in commands, or ~ shortcuts for intra-plugin references.

### Not established by this review

 - No plugin was scaffolded or loaded from this guidance.
- references/component-patterns.md, references/manifest-reference.md and examples/minimal-plugin.md, standard-plugin.md and advanced-plugin.md were not opened.
- Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md)
 - Install path printed in the plugin-dev README: `/plugin install plugin-dev@claude-code-marketplace`. It points at a marketplace named claude-code-marketplace, not at this repository's claude-plugins-official, and it installs plugin-dev as a whole, of which plugin-structure is one of seven skills, so install.command is null.
- For working on the plugin locally the README prints `cc --plugin-dir /path/to/plugin-dev`.
- This review executed neither.

### Before you start

 - Claude Code (the layout is Claude Code's plugin format)

### Compatibility

Claude Code

### Markdown guidance only

 - plugin-structure has no allowed-tools entry and no script
- Scaffolding from it means creating .claude-plugin/plugin.json and component directories at the plugin root

### Cost model

Apache-2.0 per plugins/plugin-dev/LICENSE; reading it makes no network call

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [plugin-structure SKILL.md ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure/SKILL.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure/SKILL.md Supports: upstreamDescription, summary, whySelected[0], whySelected[1], bestFor[0], bestFor[1], bestFor[2], limitations[1], limitations[2], compatibility, review.findings[0], review.findings[1], review.findings[2], review.findings[3], access.permissions[0], access.permissions[1]
- [plugin-structure README ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure/README.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure/README.md Supports: review.findings[0]
- [agent-development SKILL.md, frontmatter fields summary ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/agent-development/SKILL.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/agent-development/SKILL.md Supports: limitations[1]
- [mcp-integration SKILL.md, Method 1 ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/mcp-integration/SKILL.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/mcp-integration/SKILL.md Supports: limitations[2]
- [plugin-dev README ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md Supports: install.sourceUrl, install.steps[0], install.steps[1], install.prerequisites[0], limitations[3], limitations[4], compatibility
- [plugin-dev LICENSE ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE Supports: license, limitations[3], access.cost
- [Marketplace file, name and plugin-dev entry ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json Supports: limitations[4], install.steps[0]

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Agent Development for Claude Code Plugins ↗ Explains how to write a Claude Code plugin agent file (frontmatter, trigger description, system prompt) and ships a Bash script that checks one agent file.](/skills/anthropic-agent-development/)[### Command Development for Claude Code ↗ Explains how to write Claude Code slash-command files: frontmatter fields, $ARGUMENTS and positional arguments, @file references, inline Bash and plugin command patterns.](/skills/anthropic-command-development/)[### Hook Development for Claude Code Plugins ↗ Explains how to write Claude Code plugin hooks, prompt-based and command-based, with their event list, input and output JSON and exit codes, and ships Bash utilities to validate, lint and test them.](/skills/anthropic-hook-development/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
