Bug: Custom Slash Commands Not Loading In Claude Code

Introduction

Hey guys! Today, we're diving deep into a frustrating bug reported in Claude Code 2.0.5. The issue? Custom slash commands stored in the ~/.claude/commands/ directory aren't being discovered or loaded. This means your personalized commands aren't showing up in autocomplete, and trying to use them results in an “Unknown slash command” error. Let's break down the problem, explore the troubleshooting steps, and see what might be causing this hiccup.

What's Wrong? The Core Issue

Custom slash commands are designed to make your life easier, allowing you to quickly execute specific tasks within Claude Code. However, in version 2.0.5, these commands, which should be automatically discovered from the ~/.claude/commands/*.md directory, are failing to load. Think of it like this: you've carefully organized your tools in a toolbox (~/.claude/commands/), but Claude Code isn't opening the box to see what's inside. These commands should be readily available, popping up in autocomplete as you type /, but instead, only the built-in commands appear. This is a major workflow disruption for anyone relying on custom commands to streamline their coding process.

Interestingly, there's a twist! Hooks configured in ~/.claude/settings.json are working perfectly. This is crucial because it tells us that Claude Code can access and load configuration files from the ~/.claude/ directory. The problem isn't a general access issue; it's specifically related to the file system scanning mechanism that's supposed to discover the command files. It’s like having a key that unlocks the front door but not the toolbox inside the house. All command files are formatted correctly with the required frontmatter (metadata at the beginning of the file, like a title and description), have the proper filenames (e.g., my-custom-command.md), and the right permissions (readable by the user). Multiple restarts and various troubleshooting steps have been attempted, but the issue persists. This points to a deeper problem within Claude Code's command discovery system.

Expected Behavior: What Should Happen?

Ideally, custom slash commands in Claude Code should behave as follows:

1. Automatic Discovery: On startup, Claude Code should automatically scan the ~/.claude/commands/*.md directory and identify all valid command files.
2. Availability as Slash Commands: Once discovered, these commands should be available for use by typing / followed by the command name (e.g., /debug, /test, /analyze-codebase).
3. Autocomplete Listing: As you type /, a list of available commands, including your custom ones, should appear in an autocomplete dropdown, making it easy to select the command you need.
4. Execution on Invocation: When you invoke a custom command (e.g., by pressing Enter after typing /test), Claude Code should execute the command as defined in the corresponding .md file.

In essence, custom commands should seamlessly integrate into your Claude Code workflow, providing a smooth and efficient way to perform common tasks. The fact that they aren't working as expected is a significant impediment to productivity.

Error Messages and Logs: The Silent Treatment

One of the most frustrating aspects of this bug is the lack of error messages. When things go wrong, error messages are your best friend. They provide clues, hints, and sometimes even explicit instructions on how to fix the problem. But in this case, Claude Code is giving us the silent treatment. No error messages appear in the console or anywhere else. The commands simply don't exist as far as Claude Code is concerned. Typing / only shows the built-in commands, and attempting to invoke a custom command directly results in the “Unknown slash command” error.

# When trying to invoke custom command:
/debug
Error: Unknown slash command: /debug

This error message, while technically accurate, doesn't give us any insight into why the command is unknown. It's like a doctor saying,