[BUG] Plugin skills/ don't register as slash commands when plugin is loaded via project-local extraKnownMarketplaces (file:// source) — docs and implementation disagree

[thewoolleyman]

Summary

A Claude Code plugin loaded into a project via extraKnownMarketplaces + enabledPlugins in .claude/settings.json (or ~/.claude/settings.json) shows as ✔ enabled in /plugin, and its skills load as Agent Skills (model can invoke via the Skill tool). But the plugin's skills do NOT appear in / slash-command autocomplete, regardless of whether the enablement is at project scope or user scope.

Adding a parallel commands/<name>.md directory at the plugin root makes the slash commands appear. So commands/ works; skills/ alone doesn't — exactly the inversion of what the docs describe.

This consolidates evidence from multiple related (some closed, some open) issues that have not been individually resolved.

Reproduction

.claude/plugins/my-plugin/
├── .claude-plugin/
│   ├── plugin.json        # {"name":"my-plugin","version":"0.1.0","description":"..."}
│   └── marketplace.json   # local marketplace pointing at ./.claude-plugin
└── skills/
    └── hello/
        └── SKILL.md       # frontmatter has name: hello, description: ...

.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "my-plugin-local": {
      "source": {
        "source": "file",
        "path": "./.claude/plugins/my-plugin/.claude-plugin/marketplace.json"
      }
    }
  },
  "enabledPlugins": {
    "my-plugin@my-plugin-local": true
  }
}

Then in the CLI:

• claude plugin list → Status: ✔ enabled
• /reload-plugins → reports skill count that EXCLUDES this plugin's skills (verified by counting against other loaded plugins)
• Typing /my-plugin:hello (or /hello) in autocomplete → no match
• Adding commands/hello.md with frontmatter + body → autocomplete immediately finds it after /reload-plugins

Tested with both project-scope (.claude/settings.json) and user-scope (~/.claude/settings.json) enablement — same result either way. Scope is not the variable.

Documentation contradicting the observed behavior

From Skills:

Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way.

From Plugins reference:

Plugins add skills to Claude Code, creating /name shortcuts that you or Claude can invoke.
Location: skills/ or commands/ directory in plugin root
Skills and commands are automatically discovered when the plugin is installed

Per docs, skills/ alone should produce slash commands. It doesn't, for project-local marketplace plugins.

Related closed issues (the underlying bug recurs)

• Plugin skills/ directory does not register slash commands — only commands/ works #41842 — exact same bug, closed as duplicate
• [BUG] Plugin skills don't register as user-invocable slash commands via marketplace; CLI silently fails for GHE #38501 — same bug via marketplace, closed as duplicate
• Plugin skills not usable after /reload-plugins in existing session #42471 — /reload-plugins doesn't surface skills mid-session, closed
• Plugin skills not appearing in slash command autocomplete #21125 — skills missing from autocomplete, closed
• Plugin skills not visible in initial / slash command list #28555 — skills missing from initial / list, closed

Related open issues (different facets of the same problem space)

• Newly-installed plugin skills missing from slash-command autocomplete until Desktop restart #54278 — Desktop: newly-installed plugin skills missing from autocomplete
• Personal plugin upload: skills not registered in runtime #47347 — uploaded personal plugin skills not registered in runtime
• feat(plugins): namespace plugin skills with plugin name prefix like commands #50486 — feature request: namespace plugin skills like commands
• Plugin slash-command autocomplete drops namespace prefix on accept #54829 — autocomplete drops namespace prefix on accept

Ask

Either:

1. Fix implementation to match docs — make skills/<name>/SKILL.md register as /<plugin-name>:<skill-name> slash commands when the plugin is loaded via project-local extraKnownMarketplaces (and any other path where the plugin is currently enabled but its skills aren't surfacing).
2. Update docs to clarify that for project-local marketplace plugins, skills/ alone is insufficient and commands/<name>.md files are required for slash-command exposure.

Either resolves the contradiction. Option 1 is preferred — it matches the design direction implied by "custom commands have been merged into skills."

Workaround (currently)

Author a parallel commands/<name>.md for each skill, with frontmatter matching what the SKILL.md would have provided (description, allowed-tools, etc.) and a body that delegates to the corresponding SKILL.md. Maintainable but redundant — duplicates frontmatter and adds drift risk between SKILL.md and command.md.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Project skill display in slash command but plugin skill doesn't #17271
2. Personal plugin upload: skills not registered in runtime #47347
3. Plugin skills not injected into <available_skills> context #15178

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[thewoolleyman]

Update — empirical findings invalidate the original "workaround"

After filing the issue, I drove a claude session via tmux to actually verify what surfaces in / autocomplete (rather than relying on claude plugin list which only shows enablement status, not registered slash commands). The findings invalidate the original issue's "Workaround" section:

Original claim (in this issue's "Workaround" section):

Author a parallel commands/<name>.md for each skill ... The codex plugin uses this same pattern (its commands/ files DO appear in /codex:* autocomplete). For project-local plugins, commands/ is currently the only path that exposes slash commands in autocomplete.

Empirical reality (tested):

For the same plugin at .claude/plugins/<name>/ loaded via extraKnownMarketplaces (file path) + enabledPlugins:

Configuration tested	/ autocomplete result
skills/<name>/SKILL.md only, project-scope enable	✗ no entries
skills/<name>/SKILL.md only, user-scope enable	✗ no entries
skills/<name>/SKILL.md + commands/<name>.md, project-scope enable	✗ no entries
skills/<name>/SKILL.md + commands/<name>.md, user-scope enable	✗ no entries
Same files copied into ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ (mimicking marketplace install layout), project plugin dir removed	✗ no entries

/plugin UI consistently shows the plugin as ✔ enabled with Status: Enabled and No plugin errors across all configurations. The plugin's metadata (description from plugin.json) loads correctly. But its skills/ and commands/ directory contents never register as user-invokable slash commands.

What does work, for comparison

The ralph-wiggum plugin (cached install via the official claude-plugins-official GitHub marketplace) exposes /ralph-wiggum:ralph-loop, /ralph-wiggum:help, /ralph-wiggum:cancel-ralph correctly with namespace prefix. Its commands/ files have the same shape as the ones I authored; the difference is the install path (cache directory under ~/.claude/plugins/cache/).

The shipped livespec plugin (also cached install) exposes /seed, /critique, etc. without a namespace prefix.

So the variable isn't skills/ vs commands/ — it's how the plugin got into Claude Code's plugin registry. Plugins installed via /plugin install from a real marketplace (GitHub source, or via the marketplace install path) work. Plugins enabled via extraKnownMarketplaces + enabledPlugins from a local file path show as enabled but their commands and skills never register.

Revised ask

Either:

1. Fix implementation: plugins enabled via extraKnownMarketplaces (file:// source) + enabledPlugins should register their skills/commands the same way as cache-installed plugins.
2. Update docs: clarify that extraKnownMarketplaces + enabledPlugins in settings.json is NOT a viable path for project-local plugin distribution; only /plugin install from a marketplace produces a usable plugin. Document the supported alternatives for "ship a plugin alongside a project repo."

There is no documented or undocumented workaround for project-local plugins that produces user-invokable slash commands. The commands/ claim in this issue's original body was incorrect.

Apologies for the original misdirection

I filed this issue based on incomplete testing — I had verified claude plugin list showed enabled and inferred (from the codex pattern) that commands/ would surface in autocomplete. I never tmux-drove a session to actually check / autocomplete output for my plugin specifically. The "commands/ workaround" claim was an extrapolation, not an observation.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.