[FEATURE] Plugin marketplace developer experience improvements

Problem Statement

The plugin marketplace works well for basic install-and-use scenarios, but the developer experience for building, publishing, and maintaining plugins at scale has significant friction. After 6 weeks of building and maintaining 17 plugins through the marketplace system, I've accumulated a list of sharp edges — each discovered by getting burned, not from reading docs.

The issues cluster into three categories:

State management — the system creates state (cache dirs, settings entries, hook references) but doesn't clean it up. No garbage collection, no cascade deletes, no orphan detection.

Development workflow — the edit-test cycle for plugin development requires a multi-step publish pipeline (commit → push → marketplace update → install) when a local development mode would eliminate most round-trips.

Missing explicit controls — behaviors that should be configurable are instead emergent side effects (command namespacing, cache key derivation, branch tracking).

Proposed Solution

The highest-impact improvements, in priority order:

1. Cache garbage collection — remove old version directories in ~/.claude/plugins/cache/ when a new version is installed. Currently, stale versions persist and can shadow the active version (e.g., skills from 2.0.0 resolving instead of 2.1.17).

1. Cascade cleanup on plugin removal — plugin marketplace remove silently deletes all enabledPlugins entries from settings.json with no confirmation. Plugin uninstall doesn't clean up hook references, leaving ghost hooks pointing to deleted cache paths. Both should prompt before destructive state changes, and plugin removal should cascade to hook cleanup.

1. Local plugin development mode — a claude plugin dev <path> command that loads a plugin directly from a local directory, bypassing the cache/clone cycle. The extraKnownMarketplaces directory source is a partial workaround but is project-scoped and not discoverable.

1. git ls-remote before clone — URL-source plugins trigger a full git clone on every startup even when the cached SHA matches. Check the remote HEAD SHA first and skip the clone on cache hit. Combined with parallel loading, this would eliminate ~10 seconds of startup overhead for users with many plugins.

1. Explicit command namespace control — the colon-qualified form (/plugin:command) only appears when a command and skill collide on the same name. To get namespaced commands intentionally, you must create a thin wrapper command alongside the skill (two files for one command). A namespace: true frontmatter field, or always-on plugin prefixing, would be cleaner.

1. Document cache key derivation — the fallback chain (plugin.json.version ?? marketplace.json.version ?? gitCommitSha ?? "1.0.0") isn't documented. Removing version from plugin.json doesn't switch to SHA-based caching because marketplace.json version is a second fallback — this took significant debugging to discover.

Alternative Solutions

Current workarounds I've built:

• Cache GC: Custom cleanup script in setup-marketplaces.sh that removes non-active cache directories
• Ghost hooks: Manual settings.json audit after every plugin removal
• Local dev: extraKnownMarketplaces with "source": "directory" in project settings.local.json
• Startup perf: Reduced global URL-source plugins from 17 to 12 and moved others to per-repo install
• Namespacing: Thin command wrappers that delegate to skills to force collision-based namespace
• Nested CLI: unset CLAUDECODE before every claude plugin command inside a session

These work but are fragile and require tribal knowledge.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Typical plugin development cycle today:

1. Edit a skill in ~/Projects/my-plugin/skills/check/SKILL.md
2. git add . && git commit -m "fix: update check skill" && git push
3. unset CLAUDECODE (because I'm inside a Claude Code session)
4. claude plugin marketplace update workbench (must have pushed first — fetches remote, not local)
5. claude plugin install my-plugin@workbench
6. Restart Claude Code to pick up the changes
7. Test the skill
8. Realize I need a tweak, repeat from step 1

With a claude plugin dev ~/Projects/my-plugin/ command, steps 2-6 would disappear. Edit the file, it's live immediately.

Additional Context

• I maintain 17 plugins (10 personal + 7 forked) distributed through a hub marketplace
• The startup performance issue was filed separately with detailed profiling data
• Happy to provide more detail, test patches, or help with design on any of these