What is the difference between the marketplace and cache folders?

The marketplaces folder contains the full cloned repository, while the cache folder contains only the specific files for a particular plugin version used during execution.

Where are Claude Code plugins stored on my machine?

Plugins are typically stored in ~/.claude/plugins/, organized into marketplaces and version-controlled cache subdirectories.

Why are my root-level configuration files not working in my plugin?

Claude Code only copies the contents of the specific plugin directory to its execution cache. Files like package.json and tsconfig.json must be located inside the plugin folder, not the repository root.

How do I ensure users receive my latest plugin updates?

You must increment the version number in both the individual plugin's plugin.json and the global .claude-plugin/marketplace.json file before pushing your changes.

Plugin Architecture Guide

Name: Plugin Architecture Guide
Author: masseater

bymasseater

Learning & Documentation

Provides comprehensive architectural guidance for building, structuring, and managing Claude Code plugins and marketplaces.

About

This skill acts as a specialized technical reference for developers creating extensions for the Claude Code ecosystem. It provides deep insights into the dual-layered installation system, explaining the critical distinction between marketplace clones and the execution cache. By following this guide, developers can ensure their plugins are structured correctly—ensuring dependencies like package.json are correctly located—and master the workflow for versioning and publishing through marketplace configuration files.

Key Features

Outlines standard directory structures for commands, agents, and hooks
Defines local directory mappings for marketplaces and versioned caches
Provides a step-by-step workflow for marketplace version synchronization
Specifies mandatory file placement for package.json and tsconfig.json
Explains the relationship between plugin metadata and execution environments
0 GitHub stars

Use Cases

Bootstrapping a new Claude Code plugin with the correct internal folder hierarchy
Managing the release lifecycle of plugins within a custom marketplace
Troubleshooting plugin execution errors caused by missing configuration files in the cache

About

Key Features

Outlines standard directory structures for commands, agents, and hooks
Defines local directory mappings for marketplaces and versioned caches
Provides a step-by-step workflow for marketplace version synchronization
Specifies mandatory file placement for package.json and tsconfig.json
Explains the relationship between plugin metadata and execution environments
0 GitHub stars

Use Cases

Bootstrapping a new Claude Code plugin with the correct internal folder hierarchy
Managing the release lifecycle of plugins within a custom marketplace
Troubleshooting plugin execution errors caused by missing configuration files in the cache