[BUG] Agents cannot discover plugin-scoped slash commands - namespace resolution fails

[jsulopzs]

[BUG] Agents cannot discover plugin-scoped slash commands - namespace resolution fails

Preflight Checklist

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

Environment

• Claude Code Version: 2.0.31+
• Platform: macOS (Darwin 24.6.0)
• OS: macOS
• Plugin System: Using plugin marketplace with custom plugins

Problem Statement

When agents (launched via @mention or Task tool) attempt to use slash commands from plugins, they cannot discover the plugin-scoped command names. Agents try to use short names like /docs, /task, /commit but these commands are actually namespaced as /general:docs, /general:task, /general:commit when they come from a plugin.

This creates a fundamental disconnect between:

• User experience: Commands work fine when typed directly (/general:docs)
• Agent experience: Agents fail when trying to use the same commands

What's Wrong?

Current Behavior

When an agent's documentation says:

Use /docs to search documentation
Use /task to plan implementation

The agent tries to execute:

/docs fastmcp validation

Result: Error: Unknown slash command: docs

Root Cause

Slash commands from plugins are namespaced with the plugin name:

• Plugin: general@personal
• Command file: commands/docs.md
• Actual command name: /general:docs (not /docs)

Agents don't have access to:

1. The plugin command registry
2. Namespace resolution mechanism
3. Available command discovery

This is similar to issue #7152 but specific to the plugin namespace problem.

What Should Happen?

Agents should be able to:

1. Discover plugin-scoped commands - know that /general:docs exists
2. Resolve short names - understand that /docs in context means /general:docs
3. Access command registry - see all available commands with their full names

OR

The SlashCommand tool should accept both:

• Full names: /general:docs (currently works)
• Short names: /docs (resolve to /general:docs if unambiguous)

Steps to Reproduce

1. Create a plugin with slash commands:

   marketplaces/personal/general/
   ├── .claude-plugin/plugin.json
   └── commands/
       ├── docs.md
       ├── task.md
       └── commit.md
   

2. Install the plugin: claude plugin install general@personal

3. Create an agent that references commands:

   ---
   name: offload
   ---
   
   ## How to Use
   
   Execute commands like:
   - /docs to search documentation
   - /task to plan work

4. Launch the agent: @offload /docs fastmcp

5. Expected: Agent uses /general:docs fastmcp

6. Actual: Agent tries /docs and fails with "Unknown slash command"

Impact

This breaks agent workflows that rely on slash commands from plugins:

Affected Use Cases

1. Documentation research agents - can't use /general:docs
2. Task planning agents - can't use /general:task
3. Commit automation - can't use /general:commit
4. Any agent in a plugin referencing other plugin commands

Current Workarounds

Option 1: Manually specify full names in agent documentation

Use /general:docs to search documentation  # Not /docs
Use /general:task to plan implementation   # Not /task

Problem: This is error-prone and non-obvious to plugin developers

Option 2: Use direct tool calls instead

Use mcp__context7__get-library-docs instead of /general:docs

Problem: Bypasses the slash command abstraction, couples to implementation

Option 3: Don't use agents with plugin commands
Problem: Severely limits plugin utility

Expected Behavior

Solution 1: Command Registry Exposure

Expose available commands to agents via context or tool:

// Agent has access to:
{
  "available_commands": [
    { "name": "/general:docs", "short_name": "docs", "plugin": "general@personal" },
    { "name": "/general:task", "short_name": "task", "plugin": "general@personal" },
    // ...
  ]
}

Agents can then intelligently resolve /docs → /general:docs.

Solution 2: Namespace Resolution in SlashCommand Tool

The SlashCommand tool could resolve short names:

# User types: /docs fastmcp
# SlashCommand tool resolves to: /general:docs fastmcp
# If multiple matches exist, ask for clarification

Solution 3: Plugin Context Inheritance

Agents launched from plugin context inherit the plugin's namespace:

# In general@personal plugin
# Agent can use /docs (implicitly means /general:docs)

Related Issues

• [FEATURE_REQUEST] - Command Tool #7152 - Agents try to use Bash() for slash commands, need Command() tool
• Add exit notifications for slash command agents #11290 - Slash command agent lifecycle (exit notifications)
• [BUG] Slash commands not loading in version 2.0.27 - "Unknown slash command" error #10294 - Slash commands not loading (different issue, but related to discovery)

Additional Context

This issue becomes critical when:

• Building modular plugin architectures
• Creating reusable agent libraries
• Sharing plugins across teams

Plugin developers currently must choose between:

1. Not using slash commands in agents (lose functionality)
2. Hardcoding full namespace in docs (fragile, unclear)
3. Avoiding agent-to-agent command delegation (limits composition)

Proposed Priority

High - Blocks effective use of plugin marketplace for agent-driven workflows

Test Scenarios

1. Agent in general@personal uses /docs → resolves to /general:docs ✓
2. Agent uses /docs when two plugins provide it → asks for clarification ✓
3. Agent lists available commands → sees all plugin commands with namespaces ✓
4. SlashCommand tool with short name → resolves unambiguous matches ✓
5. Plugin disabled → its commands not available to agents ✓

Environment Details

Plugin Structure:

~/.claude/marketplaces/personal/general/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── docs.md          # Creates /general:docs
│   ├── task.md          # Creates /general:task
│   └── commit.md        # Creates /general:commit
├── agents/
│   └── offload.md       # Tries to use /docs, /task
└── .mcp.json

Settings:

{
  "enabledPlugins": {
    "general@personal": true
  }
}

Commands work when typed directly:

• /general:docs fastmcp ✓ Works
• /docs fastmcp ✗ "Unknown slash command"

Same command in agent fails:

• @offload /docs fastmcp → Agent tries /docs → Fails

[jsulopzs]

Interim Documentation Created

While this issue is being addressed, I've created comprehensive documentation of the current namespacing behavior and workarounds.

Documentation: Plugin Namespacing Guide in my dotfiles repo

Key Points Documented

1. Naming Conventions:

   • Slash commands: docs.md → /general:docs
   • MCP servers: "context7" → plugin:general:context7
   • MCP tools: mcp__context7__* → mcp__plugin_general_context7__*

2. Current Workarounds:

   • Use full plugin-scoped names in agent documentation
   • Inherit all tools instead of listing MCP tools explicitly
   • Test with only plugin-scoped resources to verify naming

3. Common Pitfalls:

   • Mixing user-scoped and plugin-scoped MCP servers with same name
   • Copy-pasting user-scoped examples into plugin context
   • Agent documentation using short names that fail at runtime

4. Migration Guide: How to update existing documentation from short names to plugin-scoped names

This documentation should help plugin developers work around the current limitations until a proper solution is implemented.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.