Claude Code plugins: install, verify and remove

A plugin packages instructions or tools you want to carry between projects. You can test installation without trusting an unfamiliar third-party package or its hooks: create one explicitly invoked skill that returns a known marker.

This walkthrough assumes macOS/Linux and a configured Claude Code client. Windows users can create the same JSON and Markdown in an editor; the shell examples use Bash or Zsh. A model response needs a working connection. Structural validation is a separate check.

Create the local package

Start in a new empty directory:

mkdir -p plugin-lab/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/.claude-plugin
mkdir -p plugin-lab/plugins/load-check/skills/ping

Save the manifest in plugin-lab/plugins/load-check/.claude-plugin/plugin.json:

{
  "name": "load-check",
  "version": "1.0.0",
  "description": "Local plugin loading exercise"
}

Save the skill in plugin-lab/plugins/load-check/skills/ping/SKILL.md:

---
description: Return a marker to verify this local plugin is loaded.
disable-model-invocation: true
---

Return exactly PLUGIN_READY. Do not use tools or change files.

Save the marketplace definition in plugin-lab/.claude-plugin/marketplace.json:

{
  "name": "local-load-lab",
  "owner": {"name": "Local developer"},
  "plugins": [
    {"name": "load-check", "source": "./plugins/load-check"}
  ]
}

The marketplace points to the package. Within the package, .claude-plugin holds the manifest and skills sits beside it. Putting skills inside .claude-plugin violates the documented plugin layout.

Validate and install

From your original directory, run:

claude --version
claude plugin validate ./plugin-lab/plugins/load-check
claude plugin validate ./plugin-lab
claude

Fix the specific file if validation fails. Valid structure alone says nothing about instruction quality or the safety of an arbitrary plugin.

In the Claude Code session, add the local marketplace and install the package:

/plugin marketplace add ./plugin-lab
/plugin install load-check@local-load-lab

Choose Local in the installation panel to scope this exercise to the current project. Read where the setting will be written before confirming. If the summary requests a reload, run /reload-plugins. The official marketplace guide explains this sequence.

Verify the namespaced skill

/plugin list
/load-check:ping

The first command should list the installed package; the second should return PLUGIN_READY. The full name /load-check:ping includes the plugin namespace, distinguishing it from another package’s skill with the same name.

Check your working directory separately: this skill should not change files. “Do not use tools” is a model instruction, not a separate system permission boundary. Use Claude Code permissions to control access.

If the command is missing, check the manifest name, the skills/ping/SKILL.md location, installation scope, enabled state and reload requirement, in that order. Keep marketplace loading and a --plugin-dir launch as separate tests.

Disable, update and uninstall

claude plugin disable load-check@local-load-lab --scope local
claude plugin enable load-check@local-load-lab --scope local
claude plugin update load-check@local-load-lab --scope local
claude plugin uninstall load-check@local-load-lab --scope local

Run these commands individually from the same project and check each result. --scope local matches your chosen installation scope; update and uninstall default to user scope without it. Restart after updating if the CLI requests it. After disabling or uninstalling, open a new session and confirm the skill is unavailable; after enabling it, repeat the marker test.

To test a content change, edit the source skill’s marker and increase the package version, then update the marketplace and installed plugin using the plugin management instructions. Editing the original file may not change an installed copy held in a cache.

Before installing someone else’s package

Inspect the package first. A text skill, a shell hook and an MCP server have different consequences. Review commands, external service addresses and instructions requesting secrets. Do not grant extra permissions merely to silence an installation error.

Repeat the same short cycle in a working project: known scope, visible component, expected action, file check and a clear way to disable it. See the plugin reference for the complete format and validator capabilities.