← Blog · 2026-10-18

Claude Code Slash Command Not Showing? 12 Causes and Fixes

Shortcut: build the file with our free SKILL.md builder, or paste an existing one into the SKILL.md validator. Both run in your browser and catch the folder, name and front matter mistakes below. Nothing is uploaded.

You saved a command, typed /, and it isn't there. Or you typed the full name and got Unknown command. Since custom commands were merged into skills, a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and they go missing for the same reasons. Work through the checks below in order.

This page is about a command that doesn't show up or won't run when you type it. If /name works but Claude never uses the skill on its own, that's a different problem: see the 10-point skill-not-triggering checklist.

First: what did Claude Code actually load?

Run /skills. It lists the skills Claude Code found in your project, user and plugin locations, and skills synced from claude.ai appear under claude.ai sync. /context shows the same listing plus the bundled skills. If your command is in neither, it didn't load: start at cause 1. If it's listed but you can't find it in the / menu, go to cause 5. If it's listed under a name you didn't expect, go to cause 7.

Not loaded at all: 4 reasons

It's a loose file, not a skill folder. A skill is a folder with a file named exactly SKILL.md inside: .claude/skills/client-update/SKILL.md. A file saved as .claude/skills/client-update.md doesn't appear in /skills. The older single-file format still works, but only in a commands folder: .claude/commands/client-update.md becomes /client-update.
It's in a folder this session doesn't read. Personal skills go in ~/.claude/skills/ and load in every project on that machine. Project skills go in .claude/skills/ in the folder where you start Claude Code or any parent up to the repository root. A .claude/skills/ folder below where you started doesn't load at startup and isn't in the / menu until Claude reads or edits a file in that subfolder; on v2.1.257 or later, run /add-dir with its path to load it now. In a git worktree, Claude Code only looks up to the worktree root (v2.1.277 or later falls back to the main checkout's skills when the worktree has no .claude/skills of its own).
You're not on your own machine. Cloud sessions, routines and Cowork don't read ~/.claude/skills/ on your laptop, so a routine that calls a personal skill reports that the skill wasn't found. Commit the skill to the repo's .claude/skills/ for cloud sessions, or enable it on your claude.ai account for Cowork and cloud sessions.
Claude Code refused the name. A folder or file name with a zero-width space, a control character, an icon-font glyph, a no-break space, two spaces in a row, a leading or trailing space, or a < or > doesn't load. Neither does a skill folder named synced or one named (or starting with) anthropic-skills, which are reserved for skills synced from claude.ai. Look for the startup notice skill or command name refused, then start claude --debug and search the debug log for [names]: the line for your skill ends in is not offered, and it spells hidden characters out as codes such as \u{200B}. Rename the folder or file, then restart.

Loaded, but hidden from the / menu: 2 reasons

It's hidden on purpose. user-invocable: false in the front matter removes the skill from the / menu and stops /name from running it; only Claude can use it. The skillOverrides setting can hide it too: "off" takes it out of the menu, and invoking it by name returns the skillOverrides error instead of running it. That setting is easy to set by accident, because in the /skills menu pressing Space cycles a skill's state and Esc saves it to .claude/settings.local.json. Check that file. (By contrast, disable-model-invocation: true keeps the skill in the menu; it only stops Claude from running it on its own.)
Your organization or a startup flag turned custom commands off. When managed settings set strictPluginOnlyCustomization to lock skills, Claude Code stops loading ~/.claude/skills/, .claude/skills/, both commands folders, --add-dir skills and synced skills. Only plugin, bundled and managed skills load. Starting with claude --safe-mode also turns off your skills, plugins and custom commands, and bare mode restricts them further.

It's there under a different name: 4 reasons

You're typing the wrong name. The name comes from where the file lives. A skill folder uses its front matter name or the folder name. A file in a subfolder of commands gets the subfolder as a prefix: .claude/commands/frontend/component.md is /frontend:component, not /component. Command files ignore a name field (they accept the same front matter as skills except name and paths), so the file name is the command. Plugin skills are namespaced, as in /my-plugin:review. A nested skill whose folder name clashes with another skill is listed with its path, such as /apps/web:deploy.
Another command already has the name. When two share a name, one wins. Enterprise beats personal, and personal beats project, so with deploy in both ~/.claude/skills/ and the project, /deploy runs your personal copy, and you may be editing the one that never runs. A skill beats a .claude/commands/ file of the same name. Your skill replaces a built-in or bundled command of the same name, but not its aliases: a project usage skill takes over /usage while /cost still runs the built-in. A skill synced from claude.ai that loses its short name runs only as /anthropic-skills:<name>, and /skills adds a note saying why.
It's an MCP prompt and the server isn't connected. MCP prompts appear as /servername:promptname (MCP), and typing /mcp__servername__promptname also runs them. They're discovered from connected servers, so a server that failed to start lists none: check /mcp first (our MCP server not connecting guide covers the usual causes). A server named anthropic-skills connects, but its prompts never appear as commands; rename the server.
It's a plugin skill and the plugin isn't active yet. Plugins you install or enable load the next time you start Claude Code or when you run /reload-plugins. If you see Plugins changed. Run /reload-plugins to activate., do that. Plugin skills also ignore skillOverrides; turn them on or off from /plugin. And plugins enabled only in your user settings don't load in cloud sessions.

Just added or edited it: 2 reasons

Claude Code isn't watching that folder. Claude Code picks up added, edited or removed skills under ~/.claude/skills/, the project's .claude/skills/ and a .claude/skills/ inside an --add-dir folder without a restart (except in bare mode). If you created a top-level skills folder that didn't exist when the session started, run /reload-skills, and again after each later change there. Files in an added directory's .claude/commands/ aren't watched, so restart after changing them, and restart after renaming a file or editing a name: line outside a watched folder.
It's a built-in command you don't have. Not every built-in command appears for every user; availability depends on your platform, plan and environment. /desktop, for example, only shows on macOS and x64 Windows when you're signed in with a Claude subscription, and /upgrade doesn't show on Enterprise plans. Unavailable commands are left out of the menu and usually return Unknown command. A few commands, such as /heapdump, are hidden by design and appear only once you type the full name. Bundled skills disappear when disableBundledSkills is on.

Also check where you typed it: a command only runs when it's at the start of your message. In go ahead and /deploy to staging, nothing runs directly; the name only gives Claude permission to run the skill.

Quick ways to narrow it down

/skills and /context: confirm the skill loaded and see which name it's listed under.
claude --debug: search the debug log for [names] to see refused names.
claude plugin validate .claude/skills (or ~/.claude/skills): finds SKILL.md files whose front matter doesn't parse (v2.1.233 or later). Malformed YAML doesn't hide a command, though. The skill still loads, just with no description.
claude --safe-mode: starts a session with your skills, plugins, custom commands and MCP servers turned off. If the problem disappears there, one of your own customizations is the cause, often a name clash (cause 8).

A minimal command that shows up

Save this as .claude/skills/client-update/SKILL.md in your project (the folder name and name match, and the front matter starts on line 1):

---
name: client-update
description: Writes the weekly client status email from my notes and open tasks. Use when I ask for a client update or Friday recap.
argument-hint: "[client-name]"
---

Write this week's status email for $ARGUMENTS from my notes in clients/.
Keep it under 150 words and end with next week's plan.

Type /client and it should appear with the [client-name] hint. Prefer a single file? .claude/commands/client-update.md with the same body creates the same /client-update.

Facts on this page come from Anthropic's Claude Code docs on skills, commands, MCP prompts, debugging your configuration, error messages and the settings reference. This guide isn't affiliated with Anthropic.