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.
“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.”
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.
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.
- 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)
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 ↗Checked
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 ↗Checked
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-structure/README.md
Supports: review.findings[0]
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/agent-development/SKILL.md
Supports: limitations[1]
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/mcp-integration/SKILL.md
Supports: limitations[2]
- plugin-dev README ↗Checked
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 ↗Checked
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE
Supports: license, limitations[3], access.cost
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json
Supports: limitations[4], install.steps[0]