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

0•

Learning & Documentation

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

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

01Outlines standard directory structures for commands, agents, and hooks

02Defines local directory mappings for marketplaces and versioned caches

03Provides a step-by-step workflow for marketplace version synchronization

04Specifies mandatory file placement for package.json and tsconfig.json

05Explains the relationship between plugin metadata and execution environments

060 GitHub stars

Use Cases

01Bootstrapping a new Claude Code plugin with the correct internal folder hierarchy

02Managing the release lifecycle of plugins within a custom marketplace

03Troubleshooting plugin execution errors caused by missing configuration files in the cache

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add masseater/claude-code-plugin plugin-architecture

For use in Claude.ai and ChatGPT

Download Skill