[BUG] Custom Slash Commands Not Appearing in Claude Code

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Custom Slash Commands Not Appearing in Claude Code

Summary

Custom slash commands defined in .claude/commands/ are not being recognized or shown in the available commands list, despite following the documented format.

Environment

• Platform: Linux (Raspberry Pi CM5 - Distiller)
• OS Version: Linux 6.12.34+rpt-rpi-2712
• Claude Code Version: [Please add your version - run claude --version]
• Working Directory: /home/distiller/projects/esp32-s3-matrix-waveshare

What Should Happen?

Expected Behavior

• Custom commands should appear in the available commands list
• Commands should be invokable with /command-name syntax
• Claude should recognize and expand command prompts from .md files

Actual Behavior

• No custom commands appear in available commands list
• Attempting to invoke commands (e.g., /build, /upload) does not work
• Claude does not recognize any of the 11 defined custom commands

Error Messages/Logs

Steps to Reproduce

Steps to Reproduce

1. Create .claude/commands/ directory in project root
2. Add multiple custom command files (e.g., build.md, upload.md, etc.) with proper frontmatter:

```markdown
---
description: Build the ESP32-S3 project
---

Build the ESP32-S3-Matrix project using PlatformIO.

Run: pio run

Show me the build output, and if there are any errors, help me fix them.
```

1. Verify files exist with ls -la .claude/commands/
2. Attempt to use commands or check available commands list
3. Commands do not appear and cannot be invoked

Current Project Structure

.claude/
├── commands/
│   ├── build.md
│   ├── esp32-matrix-coder.md
│   ├── flash.md
│   ├── god-think.md
│   ├── monitor.md
│   ├── new-animation.md
│   ├── optimize.md
│   ├── rpi-cm5-hardware-specialist.md
│   ├── test-leds.md
│   ├── test.md
│   └── upload.md
├── skills/
│   ├── create-matrix-animation/SKILL.md
│   ├── debug-matrix-hardware/SKILL.md
│   └── esp32-s3-matrix-development/SKILL.md
└── settings.local.json

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.27 (Claude Code)

Platform

Other

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

Configuration Files

settings.local.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "DISABLE_TELEMETRY": "1",
    "DISABLE_ERROR_REPORTING": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "0"
  },
  "includeCoAuthoredBy": false,
  "hooks": {
    "UserPromptSubmit": [...],
    "PreToolUse": [...],
    "PostToolUse": [...]
  }
}

Sample Command File (build.md)

---
description: Build the ESP32-S3 project
---

Build the ESP32-S3-Matrix project using PlatformIO.

Run: `pio run`

Show me the build output, and if there are any errors, help me fix them.

Git History

b2a6abf Add custom slash commands for ESP32-S3 Matrix development
8df0603 initial write

Additional Context

• Commands were committed in commit b2a6abf
• Skills in .claude/skills/ directory follow similar structure
• Hooks in settings.local.json are working correctly
• Files have correct permissions (644, readable by all)
• Frontmatter format follows documentation with description field

Things Tried

• Verified file format matches documentation
• Checked file permissions
• Confirmed files are in correct directory
• Restarted sessions
• Commands still not recognized

Question

Is there a specific initialization step, configuration flag, or file format requirement that might be missing? Are there known issues with custom commands on Linux platforms or in specific environments?

Request

Please investigate why custom slash commands are not being discovered/loaded from the .claude/commands/ directory despite following the documented structure.