bug: custom skills with reserved names (e.g., "mcp") shadow native slash commands

Resolved 💬 2 comments Opened Apr 6, 2026 by bobmatnyc Closed May 17, 2026

Summary

Custom skills deployed to .claude/skills/ can shadow native Claude Code slash commands if their name contains a reserved word. For example, a skill named mcp-vector-search or toolchains-ai-protocols-mcp can interfere with the native /mcp command.

Steps to Reproduce

  1. Create a skill directory: .claude/skills/mcp-vector-search/SKILL.md
  2. Add valid skill content
  3. Try to invoke /mcp (the native MCP server management command)
  4. The native command may fail to invoke or route to the skill instead

Expected Behavior

Native slash commands (/mcp, /help, /clear, /exit, /login, /logout, etc.) should always take precedence over custom skills, regardless of skill naming. Or: skill deployment should reject names that contain reserved command words.

Actual Behavior

Skills with "mcp" in the name can shadow or interfere with the /mcp native command. The exact behavior varies — sometimes the native command works but is ambiguous, sometimes it routes incorrectly.

Environment

  • Claude Code CLI (latest)
  • macOS
  • Skills deployed via claude-mpm agent framework to .claude/skills/

Suggested Fix

Either:

  1. Namespace precedence: Native commands always win over skill names (already partially implemented but seems incomplete for substring matches)
  2. Validation on skill load: Warn or reject skills whose names contain reserved command words
  3. Prefix convention: Skills invoked as /skill:name instead of /name to avoid collision entirely

Workaround

We're implementing a startup migration on our side to rename skills containing "mcp" to alternatives (e.g., mcp-vector-searchvector-search). But this is a framework-level issue that should be handled by Claude Code itself.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗