Claude Code custom commands that don't show up

Custom commands are skills now

Anthropic's own note is short and it explains most of this page: custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way, and existing command files keep working. A setup built before the merge is not broken by it.

The documentation has no custom-commands page of its own any more: the old slash-commands address now serves the skills page, which is where these rules live at 2.1.310.

What the newer format adds is room. A command file is one Markdown file in .claude/commands/, project or global, and it takes the same frontmatter as a skill except name and paths. A skill is a folder with a SKILL.md inside it, which can carry supporting files, frontmatter that decides who may invoke it, and a description Claude uses to load it by itself when the work matches.

For a command that will not appear, the format is almost never the cause, which is why everything below applies to both. The causes are where the file sits, what it is called, whether the session has scanned it, and whether another command already owns that name.

Where the file has to be

Where you save the file decides which sessions load it, and the list is longer than most people expect.

A command file follows the same two scopes with a different folder: .claude/commands/<name>.md in the project, or ~/.claude/commands/<name>.md for every project on this machine.

The name you type comes from where the file lives and, for a skill folder, from its frontmatter name. A folder named deploy-staging gives /deploy-staging, and adding name: deploy inside it makes /deploy work as well. A command file takes its name from the file name, and a subfolder becomes a colon, so .claude/commands/frontend/component.md is /frontend:component.

Two namespaces are worth knowing before you rename anything. A plugin's skill always carries the plugin prefix, so both a plugin skill and your own skill of the same name can load at once. A skill synced from your claude.ai account answers to /anthropic-skills:<name> and only owns the bare /<name> while nothing else uses it.

A .claude/skills/ folder below the directory you started in is not loaded at startup. It loads the first time Claude reads or edits a file in that subdirectory, and until then it is not in the / menu and typing its name does not run it. To load it sooner, run /add-dir with that path, which needs Claude Code 2.1.257 or later.

Claude Code watches the skills folders it already knows about, except in bare mode, so a SKILL.md you add or edit during a session is picked up without a restart, and the watch covers the skill's text only. The watch is documented for skills folders, not for a commands/ folder, so after adding or editing a file in .claude/commands/ run /reload-skills, which re-scans skill and command directories. Two more cases fall outside the watch. A top-level skills folder that did not exist when the session started is not watched, so run /reload-skills after creating it and again after later changes there. And a directory passed with --add-dir has its .claude/commands/ read at startup but not watched, so restart the session with the same --add-dir after changing a command file in one.

Check what actually loaded

Start with the list, not the file. /skills shows the skills from your project, your user folder and your plugins, with the source of each, and you can type to filter it. /context shows the skills among what is filling the context window, and adds the bundled ones /skills leaves out. The two answers send you down different paths: a command missing from both did not load, while a command present in one and absent from the / menu is being hidden rather than failing.

1. Look in /skills Type /skills in the session. It lists the skills from your project, your user folder and your plugins, with the source of each. A command that is missing here did not load at all. A command that is here but absent from the / menu is usually hidden by a setting rather than broken.
2. Reload the list A file added to a skills folder the session already watches loads by itself. After adding or editing a file in .claude/commands/, run /reload-skills, and run it too for a skills folder created after the session started. If the file is a command file in a directory passed with --add-dir, restart the session with the same --add-dir.
3. Check the name Start Claude Code with claude --debug and search the log for [names]. A name holding a hidden character, a blank other than one plain space between words, an angle bracket, or more than 256 characters is refused with a startup notice: either the command never loads, or only its name field is ignored.
4. Check who else owns the name Enterprise beats personal, personal beats project, a skill beats a command file, and a skill synced from your claude.ai account loses its short name to any other command that already uses it.
5. Check the kind of session Outside an interactive terminal session, in a -p run, an SDK app, a cloud session or a chat panel, an unrecognised name is not reported as an error. It is sent to Claude as ordinary text with a note that the command did not run, and a list of the commands that session can run.

The reload command is blunt on purpose: /reload-skills re-scans the skill and command directories and reports how many are available and how many were added or removed, which is the confirmation people want after saving a file. When you have just saved a file and the menu has not caught up, run /reload-skills before you start suspecting a bug.

The documentation names no shell command that prints the list before a session starts. The check is one of the in-session commands above, or the debug log the session writes at ~/.claude/debug/<session-id>.txt, which is also where a refused name is spelled out.

Safe mode is worth knowing about, but it is not a test for a missing command. claude --safe-mode starts a session with custom commands, skills, plugins, hooks, MCP servers and CLAUDE.md switched off, so every command of yours is missing there by design and nothing is learned. It separates a different kind of problem: a command that runs and behaves oddly because something in your setup, such as a hook or another customization, is interfering. If that problem disappears in safe mode, the cause is one of the things it turned off.

Two failures have a documented answer in one line each. A skill saved as .claude/skills/name.md, a file where a folder belongs, never appears in /skills at all; it needs the folder with SKILL.md inside. And a skill that /skills lists but Claude never invokes carries a user-only badge when disable-model-invocation: true is set, which tells you the command is fine and the automatic trigger is off.

Why it is missing from the menu

The menu is a view of what loaded, so a missing row means a missing command or a hidden one. These are the cases worth checking first.

One cause is not in the table because it is not about the file at all. A release regression kept correct command files out of the menu, while a Homebrew install or a ripgrep configuration on the machine stopped the folder being read at all. Both reports at the end of this page cover those cases.

A refused name is the one case where Claude Code tells you directly. The startup notice opens 1 skill or command name refused: run with --debug to see which ([names]), rename, then restart and continues a name may not hold hidden, direction-changing or blank-like characters, < or >, or be over 256 characters, and it means at least one name was refused. Either the command never loaded, or only a frontmatter name was refused, in which case the skill still loads under its folder name. Names cannot hold hidden characters such as a zero-width space, direction-changing characters, the characters < or >, a blank other than one plain space between words, or more than 256 characters. The debug log spells some hidden characters out by code, so you can often see where the problem is. Since 2.1.299, a file or folder name holding those characters is no longer offered until it is renamed.

The other refusal is a reserved name. A skill folder, a frontmatter name, or a file or subfolder in .claude/commands/ called anthropic-skills, or starting with anthropic-skills:, does not load, because that namespace belongs to skills synced from your claude.ai account. The notice names the first item to rename and counts the rest, with each one in the debug log. Since 2.1.282 these names are refused where earlier versions loaded them.

A command that loaded but cannot be seen is a setting, not a fault. user-invocable: false in the frontmatter hides the skill from the / menu and stops /name from running it, which is the right choice for background knowledge and the wrong one for a command you typed. The same hiding is available from settings as skillOverrides, whose off value hides a skill from both Claude and autocomplete, and whose user-invocable-only value does the reverse of the frontmatter field. Plugin skills are managed through /plugin instead.

An organization can also remove the whole category. A managed strictPluginOnlyCustomization policy locks skills, agents, hooks or MCP servers to plugins and managed settings, so a project or personal skill never loads. There is no separate check for it in the session: /status names the settings sources in effect, including whether managed settings are, and the administrator who set the policy is the one who can say whether it locks skills.

When a different command runs

Two commands can share a name, and the documentation is explicit about which one answers. This is also the answer when your command is in /skills and something else runs anyway.

The synced-skill row is the one that surprises people, because nothing on your machine changed. Once a claude.ai account is signed in, its skills download into ~/.claude/skills/synced/ and can arrive with the same name as one of your commands. Yours keeps the short name, and the synced one moves to /anthropic-skills:<name>. /skills groups them under claude.ai sync and prints a note under the list saying which one lost its short name, and, when the name is held by one of your own skills or command files in ~/.claude/, what to rename or delete to free it.

The menu itself also deserves a mention, because the failure looks like a broken command. Claude Code highlights a suggestion only when what follows the / matches a name or alias from its start or from a word inside it, ignoring the :, _ and - separators, and after a typo nothing is highlighted: pressing Enter submits your text as typed and answers Unknown command with the closest name it knows. Commands that are unavailable in your session are left out of the menu entirely, and when nothing matches you get No commands match.

When it runs, but not the way you wrote it

A command is recognised only at the start of a message, and the text after its name becomes its arguments, which is the part that goes wrong without a message. Up to six skills can be chained in one message, with the trailing text passed to each of them as arguments.

The placeholders are simple once you know the shapes. $ARGUMENTS expands to everything after the command name. $ARGUMENTS[0] and its shorthand $0 are the first argument, $1 the second, and a named list in frontmatter turns $issue into the first argument and $branch into the second. Values are split with shell-style quoting, so /my-skill "hello world" second gives $0 the value hello world.

Two outcomes look like the command ignored your input. An indexed placeholder with no matching argument stays in the content unchanged, so $2 in a command called with one argument reaches Claude as the text $2, while a named placeholder with no argument expands to an empty string. And an argument value that itself contains $1 or $ARGUMENTS is inserted as literal text rather than expanded. To write a dollar sign before a digit in your own prose, escape it with a backslash, as in \$1.00.

A shell line inside a command fails loudly, but the failure can look like the command itself did nothing. The !`command` form runs before Claude sees the file and its output is inlined, and a failure there aborts the whole invocation: a command that fails stops the skill with Shell command failed for pattern, where with the default shell any non-zero exit counts as a failure except exit code 1 from a search or comparison command, and a command containing a raw control character other than tab or newline is refused before any of the file's commands run, with a message naming the tool and showing each unprintable character as �. A skill synced from claude.ai is a third case: its ! commands run only in a session Anthropic hosts, a Cowork session replaces each line with a placeholder, and in any other session on your machine the line reaches Claude as literal text.

When Claude never picks it up on its own

A command that works when you type it and never fires on its own is usually a description problem. Claude decides from the description, so the words a person would naturally use belong at the front of it, and the documented checklist is to check those keywords, ask what skills are available, rephrase the request, then invoke the command directly; if /name is not recognised either, the next check is whether the name was refused.

One frontmatter field turns automatic use off on purpose. disable-model-invocation: true keeps the skill out of Claude's reach while leaving /name working, and /skills marks it user-only, so a reader who did not write the file can see why it never volunteers.

The listing has a budget, and it can weaken automatic use without breaking anything. Claude Code loads a list of skill names and descriptions so it knows what is available; when the list overflows its budget, which scales at one percent of the model's context window, it drops descriptions starting with the skills you invoke least, while every name stays. A skill whose description was dropped still runs as /name and only loses its chance of being chosen automatically. /doctor estimates the listing's cost, and the budget can be raised with skillListingBudgetFraction or a fixed character count in SLASH_COMMAND_TOOL_CHAR_BUDGET.

Malformed frontmatter is the quietest cause. If the YAML between the markers does not parse, the skill still loads with no fields set, so /name works while the description Claude matches on, and any name: alias, do not, and claude --debug shows the parse error.

A paths field narrows when a skill is loaded automatically, and it only matches files inside Claude's current working directory.

A skill written for one part of a monorepo therefore stays quiet when the session is pointed somewhere else, including at a sibling worktree you added with /add-dir.

Outside an interactive terminal session

The / menu and the Unknown command message belong to an interactive terminal session, and if you got here from an Unknown command message, the Claude Code error messages guide covers that message in full. In a -p run, an Agent SDK application, the Code tab of the desktop app, the VS Code chat panel, a cloud session or a cloud scheduled task, an unmatched name is sent to Claude as a normal message with a note that the command did not run and a list of the commands it can run. A command that did load still works there; what you lose is the error message, and a typo costs a wasted turn. The note Claude receives lists the commands that session can run, so asking Claude what it has available is the confirmation there.

Cloud and Cowork sessions also change where the file has to live. They do not read ~/.claude/skills on your machine, so a personal command that works locally is absent there. To use it in one of those sessions, enable it for your claude.ai account. Committing it to the repository's .claude/skills/ also works in a cloud session that is not a project thread, but not in a project's cloud threads and not in Cowork, and plugins declared only in your user settings do not load in cloud sessions either.

In an Omniscio session

Omniscio runs each Claude Code session through the claude binary, so the commands described here belong to that session, and a session on an engine that does not run the claude binary, such as Codex or OpenCode, has none of them. The composer has its own / list, built from the skills in your ~/.claude/skills, the current project's .claude/skills, and your plugins, so a skill folder appears there and a legacy .claude/commands file does not. That list is behind the skillSlashAutocomplete setting, which is on by default.

Typing a name the app does not recognise is still worth trying: the app hands the line to the Claude Code session, which runs custom commands and skills that arrive as user text, and its own /help describes custom commands as passing straight through. What no menu exists for is the confirmation. If a command works when typed and never appears in the composer list, that is the difference between the app's list and the CLI's, not a broken file.