[BUG] Plugin install from a marketplace "source: url" entry does not clone git submodules — "skills path not found" (planetscale plugin)

Preflight Checklist

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

What's Wrong?

When a marketplace entry installs a plugin from a git source: url, Claude Code clones the plugin repo into the plugin cache without --recurse-submodules. If the plugin's plugin.json points skills (or commands/agents) at a path inside a submodule, that directory is empty and the plugin loads with an error.

This is reproducible today with the planetscale plugin in the official marketplace, which is broken for every user who installs it.

.claude-plugin/marketplace.json in claude-plugins-official:

{
  "name": "planetscale",
  "source": {
    "source": "url",
    "url": "https://github.com/planetscale/claude-plugin.git",
    "sha": "849552445a90b17f2b17267593d0a10d41d4b316"
  }
}

That repo's plugin.json declares:

{ "skills": "./database-skills/skills" }

and database-skills is a submodule (.gitmodules → https://github.com/planetscale/database-skills.git). After install it is an empty directory:

$ git -C ~/.claude/plugins/cache/claude-plugins-official/planetscale/1.0.0 submodule status
-5e01c52c2e5b23ae998a6a7626e00886af864cb5 database-skills

The - prefix means never initialized. The clone reflog has exactly two entries and no submodule step:

0000000 -> 8495524  clone: from https://github.com/planetscale/claude-plugin.git
8495524 -> 8495524  checkout: moving from main to 849552445a90b17f2b17267593d0a10d41d4b316

Initializing the submodule by hand fixes it completely, which confirms the cause:

$ git -C ~/.claude/plugins/cache/claude-plugins-official/planetscale/1.0.0 \
      submodule update --init --depth 1
Submodule 'database-skills' registered for path 'database-skills'
$ ls ~/.claude/plugins/cache/claude-plugins-official/planetscale/1.0.0/database-skills/skills
mysql  neki  postgres  vitess

Note submodule update reported registered for path — the submodule was not even present in the clone's .git/config, so nothing initialized it at any point.

Relationship to previously-filed issues

This is a different code path from the submodule issues already closed, which is why I'm filing rather than commenting:

• #17293 "Marketplace installation doesn't clone git submodules" — fixed in v2.1.7. That covered cloning a marketplace repo. This report is about cloning an individual plugin from a source: url entry into ~/.claude/plugins/cache/, which still does not recurse.
• #33164 (marketplace update/pull path) — auto-closed as stale, not fixed.

In my case the marketplace itself isn't even a git clone — ~/.claude/plugins/marketplaces/claude-plugins-official/ is a GCS-fetched snapshot with a .gcs-sha file, so the v2.1.7 fix could not apply here regardless.

What Should Happen?

The plugin-cache clone should initialize submodules, equivalent to:

git clone --recurse-submodules <url> <cache-dir>
# or, since the entry pins a sha:
git clone <url> <cache-dir> && git -C <cache-dir> checkout <sha> \
  && git -C <cache-dir> submodule update --init --recursive

Note the ordering matters for pinned entries: submodule update has to run after the checkout <sha>, or the submodule lands on the wrong commit.

Error Messages/Logs

1 error:
  skills path not found: /Users/<user>/.claude/plugins/cache/claude-plugins-official/planetscale/1.0.0/database-skills/skills
  → Check that the path in your manifest or marketplace config is correct

Steps to Reproduce

1. Enable the planetscale plugin from the official marketplace (/plugin), or add any plugin whose plugin.json points skills at a path inside a git submodule.
2. Let Claude Code install it.
3. Restart Claude Code, or run /plugin.
4. The error above appears; ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/<submodule-path> is an empty directory and git submodule status shows the - (uninitialized) prefix.

Impact

Any plugin that composes its skills/commands from a submodule is silently half-installed. The error message points at the manifest path as if it were misconfigured, which sends you looking in the wrong place — the manifest is correct, the checkout is incomplete.

The manual submodule update --init workaround only patches a cache directory, so it is undone by the next plugin update or version bump.

Is this a regression?

No, this never worked

Claude Code Version

2.1.236 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other (Ghostty, zsh)