Claude Code Skill Missing From the Slash Menu?

Last night a teammate updated the project's /review: it should now produce a review table with risk levels. You open a new session and run it, and it still returns a block of free-form text, exactly like before. You restart the session twice, and nothing changes.

Problems like this show up in two ways, and each points in a different direction:

• It's not in the menu at all: the Skill wasn't discovered, so check the directory, file name, frontmatter, and visibility settings.
• It's in the menu but behaves wrong: you may be running a different Skill with the same name, so check project, personal, and higher-priority sources.

The opening case is the second kind. Your personal directory happens to hold a review Skill you made last week, and personal Skills outrank project Skills. Two files existing at once and the old one actually loading this time are separate facts, and only the real source shown in /skills confirms which happened.

We'll cover which Skill wins on a name clash, give a checklist for each symptom, and then explain what it takes to accept a finished Skill: test the success case, and test the failure paths like missing arguments and missing dependencies too.

01 Who Wins on a Name Clash

Project Skills live at .claude/skills/<skill-name>/SKILL.md, and personal Skills at ~/.claude/skills/<skill-name>/SKILL.md. The full set of scopes:

On a name clash, enterprise beats personal, and personal beats project; plugins use a namespace. The Claude Code skills documentation gives an example that matches the opening exactly: with deploy in both ~/.claude/skills/ and the project's .claude/skills/, /deploy runs the personal one. Plugin Skills appear as /plugin-name:skill-name, so they don't collide.

Legacy commands are part of this ordering too. .claude/commands/deploy.md still provides /deploy, but once a Skill with the same name exists, the Skill wins. When migrating an old entry, build and verify the new Skill before removing the old file, so nobody ends up on a different method during the switch; see writing custom slash commands for Claude Code.

The command name has two sources: the directory name always invokes the Skill, and when the frontmatter sets name, the docs say that becomes the command the menu shows and you type, unless another command already uses it.

02 Not in the Menu: Check Discovery

After creating a Skill, check discovery with /skills, then look at the slash menu. If it doesn't appear, confirm in order:

1. Is the path really .claude/skills/<name>/SKILL.md, with the correct file-name case?
2. Is the YAML frontmatter wrapped in a matching pair of --- lines, with valid fields and indentation?
3. Is user-invocable set to false, or has skillOverrides in Settings turned it off?
4. Did you just create a top-level Skills directory that didn't exist when the session started?
5. Is there a personal, enterprise, or legacy Command with the same name, so the loaded version isn't the one you expect?

For item 4, follow the docs: Claude Code watches existing Skill directories and picks up additions, edits, and removals within the current session. If you create a top-level skills directory that didn't exist when the session started, it isn't being watched yet, so run /reload-skills, and run it again after each later change there.

Item 2 has two details. The docs say Claude Code reads the frontmatter only when the opening --- is the file's first line. If the YAML is malformed, the body still loads with empty metadata, so /skill-name works but Claude can't match against the description. To find unparseable files in bulk, run claude plugin validate .claude/skills.

skillOverrides in item 3 lets you hide or collapse a Skill without editing its SKILL.md. Per the settings reference, toggling visibility in the /skills menu writes to .claude/settings.local.json. If you switched one off at some point and forgot, this is where it'll be.

03 In the Menu but Wrong Version: Check the Real Source

If a command or Skill doesn't appear, check /skills. What you do next depends on what you see:

Not in the list → check the directory, SKILL.md, frontmatter, and visibility
In the list but behaving wrong → check project, personal, and higher-priority versions with the same name

Back to the /review example. Start by writing the symptom down briefly:

• Symptom: since 10 p.m. last night, running /review in this repository produces free-form paragraphs instead of the expected review table with risk levels.
• Reproduction: open a new session, type /review, and the same result appears every time.
• Environment: version 2.x, model unchanged; meanwhile a teammate updated a file in the project's .claude/skills/, and your personal directory has a same-named Skill created last week.

With the time, the input, and two same-named files on record, "name override" becomes the hypothesis worth checking first. You still need the real source. The project template was clearly changed, yet /skills shows the Skill coming from your personal directory; now you have grounds to suspect the old same-named version. Give the project Skill a directory name that doesn't clash, and invoke it with the same diff.

Only when both the source and the output match expectations does the fix hold up. If the source was right all along, move on to the body or the input; renaming further just loses direction. What to put in a failure record and how to narrow down by layer is covered in troubleshooting Claude Code errors layer by layer.

04 When a Finished Skill Counts as Accepted

Once it's in the menu, use real input to check three things: did it read the right scope, did it stop when it should, and does the result match the contract? Check in invocation order:

1. Use /skills or the slash menu to confirm the name, scope, and source.
2. Test automatic triggering with words users really say, or invoke a manual Skill directly.
3. Confirm granted tools don't prompt again and removed tools are truly unavailable.
4. Check result quality on one low-risk real sample.
5. Test missing arguments, a missing target, a missing dependency, and a failing dynamic command.

If it doesn't trigger, check whether description covers the request, then check invocation limits and frontmatter. If it triggers too often, narrow the description or switch to manual invocation. Use /doctor for configuration and context-budget problems, and start with claude --debug to see YAML parse errors in the debug log.

Take the commit-prep command as an example: test with and without staged changes. With staged changes, it returns a matching draft; with none, it explains and stops. Both meet the contract. Inventing a summary from nothing doesn't.

Test both the success sample and the failure paths. Stopping with a clear explanation when input is missing or the environment doesn't fit is part of result quality. Getting /review to run the new version after the rename is only step one. Run the same diff to get the new format, then try a call with no baseline and see whether it stops; after that, the Skill is ready to hand to the team.