skip to content

While developing a Claude Code plugin, how do you load and iterate on it without publishing it to a marketplace?

level: middleimportance: nice to knowfreq 8%

answer

  1. session-only, nothing written to settings
  2. --plugin-dir with a folder or zip
  3. edit, then /reload-plugins
  4. claude plugin validate before running
  5. same name silently shadows the installed copy

basics

~10 s

Start claude --plugin-dir ./my-plugin to load it for one session without installing, run /reload-plugins after each edit, and check it with claude plugin validate and the /plugin Errors tab.

solid answer

~40 s

`claude --plugin-dir ./my-plugin` loads the plugin for that session only, as `my-plugin@inline`, and writes nothing to settings; the flag repeats for several plugins and also accepts a `.zip`. After editing files, `/reload-plugins` applies the changes and prints a `Reloaded:` summary with counts. Before running, `claude plugin validate ./my-plugin` checks the manifest and the frontmatter of every skill, agent and command (add `--strict` to fail on warnings); at runtime the `/plugin` Errors tab lists what failed to load. One trap: a `--plugin-dir` plugin whose manifest name matches an installed plugin replaces it silently, so you may be testing your copy while `claude plugin list` still shows the installed one as enabled. To keep a plugin loading in every session without a flag, `claude plugin init` scaffolds it under `~/.claude/skills/`.

code

bash · 5 lines
bash
claude plugin validate ./team-toolkit --strict
claude --plugin-dir ./team-toolkit plugin details team-toolkit
claude --plugin-dir ./team-toolkit
# inside the session, after each edit on disk:
# /reload-plugins

go deeper

for a junior

Recall the loop: claude --plugin-dir ./my-plugin to load it for one session, /reload-plugins after edits, and /plugin to see what loaded or failed.

for a middle

Explain what validate checks, how @inline ids differ from installed ones, and why shell subcommands need the same --plugin-dir flag before them to see the plugin.

for a senior

Show you can untangle which copy is running: silent shadowing of installed plugins, list output that reflects settings, held reloads that need --force, and managed locks.

for a principal

Set the team's plugin development practice: session-only loading for authors, a local marketplace for in-place testing, evals before release, and when admins should disable side-loading.

## Loading a plugin you are writing You do not need a marketplace to run a plugin under development. The `claude` command offers **session-only** loading: - **`--plugin-dir <path>`** loads a plugin directory or a `.zip` of one for this session. Repeat the flag for several plugins; pointing it at a folder of plugins loads each subfolder that has a `.claude-plugin/plugin.json`. - **`--plugin-url <url>`** downloads a `.zip` archive at startup, such as a CI build artifact; point it only at archives you trust. - **`CLAUDE_CODE_PLUGIN_DIRS`** lists absolute plugin paths when you cannot add a flag, for example when a parent process launches Claude Code. A plugin loaded this way gets the id `<name>@inline`, and **nothing is written to your settings**. It disappears when the session ends. `claude --plugin-dir ./my-plugin` with no manifest still works: the plugin is named after its directory. ## The edit loop 1. Run `claude plugin validate ./my-plugin` in your shell. It checks the manifest and the frontmatter of every skill, agent and command file, exits `0` on `Validation passed`, and with `--strict` also fails on warnings. It does not read `.lsp.json`. 2. Start `claude --plugin-dir ./my-plugin` and exercise the component: type `/my-plugin:<skill>`, ask Claude to edit a file to trigger a `PostToolUse` hook, or open `/mcp` to see a server's status. 3. Edit files on disk, then run **`/reload-plugins`** in the same session. It prints one line such as `Reloaded: 1 plugins · 2 skills · 1 agents · 1 hooks · 1 plugin MCP servers · 0 plugin LSP servers`, plus an error count pointing to `/plugin`. 4. When something is missing, open **`/plugin`**: the **Installed** tab shows the components Claude Code found, and the **Errors** tab names what failed, such as `commands path not found`. A reload that would add or remove an MCP server or the `LSP` tool would also invalidate the prompt cache, so Claude Code holds it and asks for `/reload-plugins --force`; the cost side of that is covered with caching. ## Inspecting it from the shell Shell subcommands see a session-only plugin only when the same flag comes first: - `claude --plugin-dir ./my-plugin plugin list` shows it under a `Session-only plugins` heading. - `claude --plugin-dir ./my-plugin plugin details my-plugin` prints its **Component inventory** (skills, agents, hooks with their events, MCP and LSP servers) and the always-on token cost. ## The shadowing trap When a `--plugin-dir` plugin has the same **manifest name** as an installed marketplace plugin, the session-only copy **replaces the installed one silently**. `claude plugin list` still shows the marketplace row as enabled, because that row reflects settings, and only the `--debug` log records the override. Two consequences: - A developer who forgets the flag in another terminal tests the installed version, not the working copy. - To make the installed copy load again while the flag is passed, set `"<name>@inline": false` under `enabledPlugins`. The exception is a plugin locked by managed settings, where the `--plugin-dir` copy is ignored with a message; an administrator can also disable the side-loading flags altogether. ## Failures you hit while developing - **`--plugin-dir` pointed at a marketplace root.** The flag takes one plugin's root, the folder that holds `.claude-plugin/plugin.json`. Pointed at a marketplace root, Claude Code does not read `marketplace.json`, so plugins under `plugins/` do not load and no error appears. - **Skills missing although the plugin loads.** The `skills/` folder was saved inside `.claude-plugin/`, or a `skills` manifest entry points at a file instead of a folder containing `SKILL.md`. - **A manifest path that resolves outside the plugin root**, such as `../shared`, is rejected with a `path escapes plugin directory` error and that component is skipped. - **A hook that seems silent.** A `PostToolUse` hook that exits 0 shows nothing in the transcript; confirm it ran with the debug log or by what its script changed. ## Other ways to keep a plugin loaded | Approach | Loads | Notes | |---|---|---| | `--plugin-dir` | One session | Edits apply on `/reload-plugins` | | `claude plugin init <name>` | Every session | Scaffolds under `~/.claude/skills/<name>/`, id `<name>@skills-dir` | | Local marketplace with a relative-path entry | Every session after install | Loads in place, so edits apply on reload without bumping `version` | Two more details: the `userConfig` dialog appears only when installing through `/plugin`, so a `--plugin-dir` plugin opens it with `/plugin configure <name>`; and `claude plugin eval` runs test cases with and without the plugin to check it actually changes Claude's behaviour.

  • Your --plugin-dir plugin seems to ignore edits, yet claude plugin list shows the marketplace version enabled. What is going on?
    Check which copy is loaded. A `--plugin-dir` plugin replaces a same-named installed plugin silently, and `claude plugin list` reflects settings rather than what loaded; only the `--debug` log records the override. If the terminal was started without the flag, you are running the installed copy. Otherwise, run `/reload-plugins` after editing, since the running session keeps what it loaded.
  • Why does the userConfig dialog never appear for a plugin loaded with --plugin-dir?
    The dialog for a plugin's `userConfig` options is part of installing through `/plugin` in a session; neither `--plugin-dir` nor `claude plugin install` in a shell shows it. With the plugin loaded, run `/plugin configure <plugin-name>` to open it.

  • You must publish to a marketplace before you can test a plugin.
  • --plugin-dir permanently adds the plugin to your settings.
  • Every edit to a loaded plugin needs a full Claude Code restart.
  • claude plugin list proves which copy of a plugin actually loaded.
  • claude plugin validate also checks the .lsp.json file.