[DOCS] Plugin authoring guide should warn about plugin.json name collision with marketplace name
Problem
The plugin authoring and marketplace creation docs don't mention that the name field in .claude-plugin/plugin.json must differ from the marketplace name. When they match, plugin installation fails with an EXDEV error on Linux systems where /tmp is a separate filesystem (tmpfs).
This is a silent naming constraint with no validation or helpful error message — the user only sees:
Error: Failed to install: EXDEV: cross-device link not permitted,
rename '/home/user/.claude/plugins/cache/my-skills' -> '/tmp/claude-plugin-temp-...'
Root cause
See my comment on #14799 for the full source-level analysis. In short: the installer stages files at cache/<plugin.json name> then renames to cache/<marketplace>/<plugin>/<version>. When the names match, the final path is inside the staging path, triggering a detour through os.tmpdir() which crosses filesystems.
Who is affected
Any marketplace author whose plugin.json name matches their marketplace name. This is the natural default — if your marketplace is my-org/my-skills and your plugin is also called my-skills, you'll hit this on any Linux system with tmpfs /tmp (which is the default on Ubuntu, Fedora, Arch, etc.).
Official marketplace plugins are unaffected because claude-plugins-official never collides with plugin names like code-review.
Suggestions
- Docs: Add a note to the plugin/marketplace authoring guides that
plugin.jsonnamemust not match the marketplace name - Validation: Emit a clear error during
plugin installwhen a name collision is detected, instead of the opaque EXDEV message - Fix: Use a same-filesystem temp directory instead of
os.tmpdir()for the intermediate rename (see #14799 comment)
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗