[BUG] The relative paths in source property value in .claude-plugin/marketplace.json are confusing

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The documentation here: https://code.claude.com/docs/en/plugin-marketplaces#plugin-sources

Relative paths

For plugins in the same repository:
{
"name": "my-plugin",
"source": "./plugins/my-plugin"
}

Is very unclear. I simply think it is a bug. Note that marketplace.json is in the subfolder .claude-plugin . So the relative paths should most likely be "../plugins/my-plugin" relative to the marketplace.json file.

What Should Happen?

With the spec like this:

Relative paths

For plugins in the same repository:
{
"name": "my-plugin",
"source": "./plugins/my-plugin"
}

but my plugins being in the parent folder of .claude-plugin, the plugin loading should fail.

Only when I use:

Relative paths

For plugins in the same repository:
{
"name": "my-plugin",
"source": "../plugins/my-plugin"
}

it should work. This is how relative paths are generally resolved. Relative to the file in which they are specified.

What you have is a magical behavior and unexpected. I wasted a lot of time trying to understand why my plugins were not found because I used "../plugins/my-plugin".

NOTE: The leading ../

Error Messages/Logs

Steps to Reproduce

Try using:

Relative paths

For plugins in the same repository:
{
"name": "my-plugin",
"source": "../plugins/my-plugin"
}

in ./claude-plugin/marketplace.json file file.

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.1.50 (Claude Code)

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

I think the current implementation is a bad UX because of magical behavior.