Claude Code plugins and marketplaces: install, create, and share

The manifest at .claude-plugin/plugin.json gives the plugin its name and can add a version, description, and other metadata. Only plugin.json goes inside .claude-plugin/; components sit in the plugin root next to it.

• skills/: each skill is a folder with a SKILL.md file. Plugin skills are prefixed with the plugin name, such as /my-plugin:hello.
• agents/: subagent definitions Claude can delegate to.
• hooks/hooks.json: commands Claude Code runs at points in its lifecycle.
• .mcp.json: MCP servers Claude Code connects to while the plugin is enabled.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "YOUR_NAME"
  }
}

Only name is required. Test a plugin without a marketplace by loading it for one session, and check it with the validate command.

claude plugin validate ./my-first-plugin
claude --plugin-dir ./my-first-plugin

Run /plugin in a terminal session to open the plugin panel, where the Discover tab lists plugins from your marketplaces. Claude Code adds Anthropic's official marketplace, claude-plugins-official, the first time you start an interactive terminal session. Any other marketplace must be added first; it can be a GitHub owner/repo (add #ref to pin a branch or tag), a git URL, a local path starting with ./ or ../, or a hosted marketplace.json URL.

/plugin marketplace add YOUR_ORG/YOUR_REPO
/plugin install PLUGIN_NAME@MARKETPLACE_NAME

In a session, /plugin install opens the plugin's details so you can review it and pick a scope: user (you, every project), project (everyone in the repository, through .claude/settings.json), or local (you, this repository only). The shell commands do the same without a session.

claude plugin marketplace add YOUR_ORG/YOUR_REPO
claude plugin install PLUGIN_NAME@MARKETPLACE_NAME --scope project
claude plugin list

A marketplace is a directory with a .claude-plugin/marketplace.json file plus the plugins it lists. The file requires a name, an owner, and a plugins array, and each plugin entry needs a name and a source. Write relative sources from the marketplace root (the directory that contains .claude-plugin/), and keep each entry name the same as the name in that plugin's plugin.json.

{
  "name": "my-marketplace",
  "description": "Plugins for my team",
  "owner": {
    "name": "YOUR_NAME"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "A greeting plugin to learn the basics"
    },
    {
      "name": "other-plugin",
      "source": {
        "source": "github",
        "repo": "YOUR_ORG/other-plugin"
      }
    }
  ]
}

claude plugin validate ./my-marketplace
claude plugin marketplace add ./my-marketplace
claude plugin install my-first-plugin@my-marketplace

Other plugin source types include git-subdir, url, archive, npm, and command. Once it works locally, push the directory to a git host so teammates can add it by owner/repo or URL.

Commit these keys to .claude/settings.json. extraKnownMarketplaces registers marketplaces for everyone who opens the repository, and enabledPlugins turns plugins on or off, keyed by plugin-name@marketplace-name.

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "YOUR_ORG/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true
  }
}

• Project marketplaces apply only after each teammate accepts the workspace trust dialog for the folder.
• Enabling a plugin in project settings does not download it; each collaborator still installs it on their own machine, for example with claude plugin install PLUGIN_NAME@MARKETPLACE_NAME --scope project.
• To opt out of a project-enabled plugin, set it to false in .claude/settings.local.json; setting false in user settings does not override the project.
• In managed settings, a plugin set to false is blocked at every scope, and organizations can also allowlist or block marketplaces.