Claude Code Guide: Plugin Packaging, Testing, and Distribution

InYourLeague Research · 2026-08-28

Answer in brief

Package each Claude Code plugin as a self-contained directory, with component folders at the plugin root and only plugin.json under .claude-plugin/. Test it with --plugin-dir; use /reload-plugins only as documented for an edited skill, and use claude plugin validate for the evidenced agent-frontmatter check. Distribute releases through a marketplace catalog, bump a declared manifest version when required, and avoid claiming cache behavior not specified in the supplied excerpts.

Key facts at a glance

Failure modes and verification

FAQ

What is the minimum Claude Code plugin structure?

A plugin is a self-contained directory containing supported components. A .claude-plugin/plugin.json manifest is optional; when present, it goes under .claude-plugin/, while component folders such as skills/, agents/, commands/, and hooks/ remain at the plugin root. See Create plugins.

How should I test a plugin locally?

Run claude --plugin-dir ./my-plugin, invoke each skill through its expected namespace, and inspect the Custom commands tab in /help. This verifies the local package path and skill discovery described in Create plugins.

Does /reload-plugins reload every plugin component?

The supplied evidence demonstrates /reload-plugins after editing the example skill. It does not establish equivalent hot-reload behavior for agents, hooks, MCP servers, LSP servers, or monitors, so verify those components in a fresh test session rather than generalizing the skill example.

What does claude plugin validate prove?

The supplied reference specifically supports it for finding plugin-agent files whose frontmatter does not parse. Use the plugin root for a manifest-based plugin or the agents/ directory in the documented manifest-free case; this requires Claude Code v2.1.233 or later. A clean result is not evidence of comprehensive semantic validation for every component.

How does manifest versioning affect updates?

If the optional manifest version is set, users receive updates only when it is bumped, except for a command source. If it is omitted, another source in the documented version-management sequence supplies the version, but the supplied excerpt does not show the full precedence. See the Plugins reference.

How does marketplace distribution work?

Users add a marketplace catalog first and then install individual plugins; adding the catalog alone installs nothing. Anthropic controls the official marketplace, while independent publishers can share their own catalog. The community marketplace uses automated validation and safety screening and pins each entry to a commit SHA, as described in Discover and install plugins.

What cache behavior is established by the supplied evidence?

The excerpts do not specify an installed-plugin cache location, retention period, copy policy, or universal invalidation rule. They therefore do not support claims about when arbitrary changes to a marketplace-installed plugin become visible; use versioned releases and test the published installation path.

Sources and freshness

• Official source
• Official source
• Official source
• Last verified: 2026-08-28

Extended guide

Package a Claude Code plugin as one self-contained directory. Put component folders at the plugin root, and reserve .claude-plugin/ for plugin.json.

Package structure

The manifest is optional. When present, .claude-plugin/plugin.json declares identity and display metadata such as name, description, version, and author. Its name also supplies the skill namespace: a hello skill in my-first-plugin is invoked as /my-first-plugin:hello. The plugin root is the individual directory passed to --plugin-dir or containing .claude-plugin/plugin.json; it is not ~/.claude/. See the official creation guide and technical reference.

Build and release workflow

1. Create the package. Make a dedicated directory and add .claude-plugin/plugin.json when the plugin needs stable identity, manager-facing metadata, or an explicit version. Keep skills/, commands/, agents/, and hooks/ beside .claude-plugin/, not inside it.

2. Package skills deliberately. Give each skill a directory containing SKILL.md when the plugin ships multiple skills. If neither a skills/ directory nor a manifest skills field exists, Claude Code can load one root SKILL.md. Set that file’s frontmatter name to keep its invocation name stable. Without it, the fallback can be the installation directory name, which may be a changing version string for marketplace installations.

3. Test locally. Run claude --plugin-dir ./my-plugin, invoke each skill through its expected namespace, and confirm its listing under the Custom commands tab in /help. The creation guide demonstrates /reload-plugins after editing the example skill. That evidence supports reloading the edited skill, but it does not establish that every hook, agent, MCP server, LSP server, or monitor change is hot-reloaded. Use a fresh test session when verifying other component types or complete release behavior.

4. Apply the documented validation check. For a plugin with a manifest, use claude plugin validate ./my-plugin. For the documented manifest-free agent case, use claude plugin validate ./my-plugin/agents. The supplied reference specifically supports this command for finding plugin-agent files whose frontmatter does not parse, beginning with Claude Code v2.1.233. Do not treat a clean result as evidence that every manifest field or component configuration has received comprehensive semantic validation; inspect the relevant schemas and exercise the actual components as well.

5. Version the release. The manifest version is optional. If it is declared, users receive updates only after it is bumped, except when the plugin uses a command source. If it is omitted, another source in the documented version-management sequence supplies the version. The supplied excerpt does not enumerate that remaining precedence, so this draft does not infer it.

6. Distribute through a marketplace. A marketplace is a catalog, not an installation bundle. Users first add the catalog, which installs no plugins, and then install selected entries. Anthropic decides inclusion in claude-plugins-official; in-app submissions go to the community marketplace instead. Independent publishers can share their own marketplace. The community marketplace contains third-party plugins that passed automated validation and safety screening, with each catalog entry pinned to a specific commit SHA. See Discover and install plugins.

Release checks and evidence limits

Before publishing, confirm the root layout, manifest identity, skill namespace, local invocation, evidenced agent-frontmatter validation, version change, and marketplace installation path. Test the published entry in a clean environment where practical.

The supplied excerpts demonstrate skill reloading but do not specify an installed-plugin cache directory, retention period, file-copy policy, or universal invalidation rule. Accordingly, this draft makes no claim about when cached marketplace installations notice arbitrary file changes. Version bumps and end-to-end installation tests remain the evidence-backed release controls described here.

Model availability note: The official source does not specify a selectable model ID.