Claude Code marketplace: the wiring, and the two things that break it

On this page#

• What the integration actually does
• The wiring
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

A Claude Code marketplace is a catalog and distribution layer for plugins. It tells Claude Code where plugin packages live and gives engineers a consistent installation path. It does not make repository instructions portable, validate plugin behavior, resolve conflicting hooks, or guarantee that another developer receives the same operating environment.

That distinction matters. Engineers often expect a marketplace to behave like a package manager with a lockfile:

| Assumption | Reality | |---|---| | The marketplace contains the plugin | It usually points Claude Code to the plugin source | | Installation configures the repository | It exposes the plugin’s commands, agents, skills, hooks, or integrations | | Everyone gets identical behavior | Behavior still depends on repository state and local configuration | | A successful install proves correctness | It proves discovery and loading, not execution | | Updating the catalog updates every user | Installed copies and local caches can remain behind |

A plugin is a packaged extension that adds reusable behavior to Claude Code; the authoritative starting point is the Claude Code documentation. The marketplace is the index above those packages, not the execution environment beneath them.

This is why putting repository invariants only inside a marketplace plugin is the wrong design. Rules required for every contributor should remain in the repository. The plugin can supply reusable workflows, but the repository must retain the facts that make those workflows safe.

Photo by cottonbro studio on Pexels.

The wiring#

The reliable setup has three explicit layers: a marketplace manifest, a plugin manifest, and the plugin content. Keep them separate. When those layers are blurred together, discovery failures look like execution failures and engineers debug the wrong file.

1. Create the marketplace manifest#

The marketplace repository needs a .claude-plugin/marketplace.json file. Its job is to name the marketplace and map plugin names to their source directories.

{
  "name": "engineering-marketplace",
  "owner": {
    "name": "Engineering"
  },
  "plugins": [
    {
      "name": "repo-guardrails",
      "source": "./plugins/repo-guardrails",
      "description": "Repository-aware checks and implementation workflows"
    }
  ]
}

Treat source as an address, not decoration. It must point to the plugin root—the directory containing that plugin’s .claude-plugin/plugin.json—rather than directly to a command, skill, or manifest file.

The marketplace manifest should remain boring. Do not duplicate operating instructions there or turn descriptions into prompts. Catalog metadata answers “what can I install?” while the plugin answers “what behavior is available?” That boundary follows Claude Code’s documented extension model in the official overview.

2. Create the plugin manifest#

Inside plugins/repo-guardrails, add .claude-plugin/plugin.json. This manifest identifies the package Claude Code will load.

{
  "name": "repo-guardrails",
  "description": "Repository-aware checks and implementation workflows",
  "author": {
    "name": "Engineering"
  }
}

Keep the plugin name identical across both manifests. A marketplace entry called repo-guardrails that points to a differently named plugin creates needless ambiguity during installation and diagnosis.

A practical directory layout is:

.claude-plugin/
  marketplace.json
plugins/
  repo-guardrails/
    .claude-plugin/
      plugin.json
    skills/
      verify-repository/
        SKILL.md

This structure also makes ownership visible in code review: the top-level manifest owns discovery; the nested package owns behavior.

3. Add one narrow, testable capability#

Start with a capability whose success can be observed without interpretation. A skill is a reusable instruction package that Claude Code can invoke for a defined task; broader concepts and operating boundaries are covered in the Claude Code documentation.

Create plugins/repo-guardrails/skills/verify-repository/SKILL.md:

---
name: verify-repository
description: Identify repository checks before implementation or handoff.
---

Read the repository's committed instructions and existing automation.

Return:

- the relevant validation commands already defined by the repository;
- the files that establish those commands;
- any check that cannot be run safely;
- no invented command, tool, or configuration.

Notice what this does not contain: repository-specific commands. Those belong in the repository that owns them. Hard-coding one project’s test command into a shared marketplace plugin silently exports a local assumption as a company-wide default.

For a fuller reusable operating layer, PairFoundry’s Agent Operating Kit is the relevant packaged option. Engineers who want the underlying model before adopting a pack should start with the free foundations track.

4. Add and install the marketplace#

From Claude Code, add the marketplace source and then install the plugin:

/plugin marketplace add OWNER/REPOSITORY

/plugin install repo-guardrails@engineering-marketplace

Replace OWNER/REPOSITORY with the repository that contains .claude-plugin/marketplace.json. The install selector combines the plugin name with the marketplace name, so both identifiers must match the manifests exactly.

Do not document only these commands. Record the marketplace source, install selector, ownership, and rollback path in the repository or team runbook. The official Claude Code overview explains the product surface; your repository still has to define how that surface is governed.

The two things that break it#

Two failures account for most broken marketplace setups: Claude Code cannot resolve the plugin package, or it loads the package without the behavior engineers expected. The first is catalog wiring. The second is content layout or activation. Reinstalling repeatedly does not distinguish them.

1. The marketplace entry points at the wrong directory#

Symptom: the marketplace can be added, but the plugin cannot be installed or recognized from the advertised selector.

Cause: source points to a file, a nonexistent path, or a directory that does not contain .claude-plugin/plugin.json.

Wrong:

{
  "name": "repo-guardrails",
  "source": "./plugins/repo-guardrails/.claude-plugin/plugin.json"
}

Correct:

{
  "name": "repo-guardrails",
  "source": "./plugins/repo-guardrails"
}

Fix the source path, confirm the nested manifest exists, then refresh the marketplace before reinstalling. Do not compensate by copying plugin files into the marketplace root. That erases the package boundary and makes the next plugin harder to reason about.

2. The plugin installs but its capability is absent or stale#

Symptom: installation appears successful, yet the expected skill, command, agent, or hook is missing—or an old definition continues to appear.

Cause: the content is outside the plugin’s recognized directory structure, its metadata does not describe the capability accurately, or Claude Code is still using previously loaded marketplace state.

Fix the filesystem contract first:

plugins/repo-guardrails/
  .claude-plugin/
    plugin.json
  skills/
    verify-repository/
      SKILL.md

Then refresh the marketplace and reinstall the plugin rather than editing random local copies. The official documentation should be the authority for supported plugin component locations; your marketplace repository should be the authority for the exact source tree your team installs.

If the plugin controls important workflows, document its rollback before rollout. The broader PairFoundry packs are useful when you want a defined operating system rather than an isolated extension.

Photo by Digital Buggu on Pexels.

Verifying it works#

Verification requires proof at four layers: marketplace discovery, plugin identity, capability discovery, and repository-safe execution. Seeing the marketplace name in a UI or receiving a successful install response proves only the first part of the chain.

Use this acceptance sequence:

1. Add the marketplace from a clean Claude Code setup.
2. Confirm engineering-marketplace is discoverable.
3. Install repo-guardrails@engineering-marketplace.
4. Confirm the verify-repository capability is visible.
5. Invoke it inside a repository with committed instructions.
6. Check that its output cites existing files and commands.
7. Remove or rename the expected skill locally, refresh, and confirm the failure becomes visible rather than silently falling back.
8. Reinstall from the marketplace and repeat the invocation.

The decisive test is provenance: can the second developer explain which marketplace supplied the plugin, which directory supplied the capability, and which repository files supplied the actual invariants?

A plugin that produces plausible output without traceable inputs is not verified. It is merely convincing. For more integration patterns built around this distinction, use the Wiring It In hub.

Team considerations#

A team rollout succeeds only when installation, updates, ownership, and rollback are explicit. The second developer does not share the original author’s local cache, unstated repository assumptions, or memory of why the plugin was structured a certain way. Design for that developer first.

Commit or document:

• the canonical marketplace repository;
• the exact install selector;
• the expected plugin directory layout;
• the repository instructions the plugin must respect;
• the owner who reviews plugin changes;
• the refresh and reinstall procedure;
• the removal or rollback procedure.

Do not require a marketplace plugin for the basic ability to build, test, or safely modify the repository. A contributor must still be able to find those commands in committed project files. The plugin may orchestrate them, but it should not become their only source.

Updates need the same review discipline as code. A changed skill can alter decisions even when no application file changes. Review manifest edits, prompts, hooks, and tool permissions as operational code, using the Claude Code documentation to check the supported mechanism rather than relying on remembered behavior.

Photo by ThisIsEngineering on Pexels.

Related reading#

• Getting Claude Code GitHub actions right the first time
• Claude Code Neovim, including the failure mode nobody documents

FAQ#

Should repository rules live inside the marketplace plugin?#

No. Required repository invariants should be committed with the repository. Put reusable workflows in the plugin, and let those workflows read project-owned rules. Otherwise, a missing or stale installation changes the repository’s effective operating contract.

How is this different from following the official setup?#

It is not a replacement for the official setup. The official Claude Code overview defines the product and extension surface. This wiring adds the repository structure, verification gates, ownership, and rollback discipline that a production team still needs.

How do we roll back a broken plugin?#

Remove or disable the affected installation, restore the last reviewed marketplace and plugin content, refresh the marketplace, and reinstall. Repository-owned build and validation instructions should remain usable throughout the rollback.

When should we avoid a marketplace?#

Avoid it when the behavior is specific to one repository, cannot be verified independently, or requires hidden local state. A marketplace earns its cost when multiple engineers need the same reusable capability with a clear source, owner, and update path.

What usually breaks when a second developer installs it?#

Path assumptions and undocumented local state. The marketplace may reference the wrong package root, or the plugin may depend on files that existed only on the author’s machine. A clean-install acceptance test catches both before team rollout.