bug: custom skills with reserved names (e.g., "mcp") shadow native slash commands
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
- Create a skill directory:
.claude/skills/mcp-vector-search/SKILL.md - Add valid skill content
- Try to invoke
/mcp(the native MCP server management command) - 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:
- Namespace precedence: Native commands always win over skill names (already partially implemented but seems incomplete for substring matches)
- Validation on skill load: Warn or reject skills whose names contain reserved command words
- Prefix convention: Skills invoked as
/skill:nameinstead of/nameto avoid collision entirely
Workaround
We're implementing a startup migration on our side to rename skills containing "mcp" to alternatives (e.g., mcp-vector-search → vector-search). But this is a framework-level issue that should be handled by Claude Code itself.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗