[BUG] Flat ``.md-files`` in ``/.claude/skills/`` silently ignored — no error, confusing given "merged" messaging

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?

Summary

Placing a flat .md file directly in .claude/skills/ (e.g., .claude/skills/deep.md) produces no error but the skill doesn't register. The exact same file in .claude/commands/deep.md works immediately. The docs say "commands have been merged into skills" — which implies interchangeability, but the file structures are different and the failure is completely silent.

Root cause

Skills require a directory with SKILL.md — not a flat file:

# This works (skills format):
.claude/skills/deep/SKILL.md     <- directory + uppercase SKILL.md

# This also works (legacy commands format):
.claude/commands/deep.md          <- flat file, still supported

# This silently fails (undocumented):
.claude/skills/deep.md            <- flat file in skills/ — no error, just ignored

Why this is confusing

The docs say:

"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."

We read "merged" and — naturally — expected both formats to work in both directories. A flat file in commands/ works, so a flat file in skills/ should too. Instead, it silently fails with no feedback.

Three related silent failure modes

| Format error | What happens | Reported in |
|-------------|-------------|-------------|
| Flat .md file in skills/ | Silently ignored | This issue |
| Lowercase skill.md instead of SKILL.md | Silently ignored | #17417 |
| Multi-line YAML description | Silently dropped from registry | #9817, #4700 |

In all three cases: no error message, no warning, no suggestion about the correct format.

The model makes it worse

Claude itself sometimes creates skills as flat files in .claude/skills/ (see #10145, and `@dellis23`'s comment in #9716). So the model generates the wrong format, which then silently fails (and the user has no signal about what went wrong!!).

What Should Happen?

Any of these would help:

1. Error message: When a .md file is found directly in .claude/skills/ (not inside a subdirectory), log a warning: "Found deep.md in `.claude/skills/ ... did you mean .claude/skills/deep/SKILL.md`?"
2. Accept flat files in skills/ too: Since commands and skills are "merged," honor both formats in both directories.
3. Documentation: Add a note to the skills page explicitly showing the format difference and warning that flat files in skills/ are not supported.

Error Messages/Logs

No error messages — that IS the bug.
In all three failure modes (flat file in skills/, lowercase skill.md, multi-line YAML description), there is zero feedback to the user.

Steps to Reproduce

1. Create a skill as a flat .md file:

``bash
cat > .claude/skills/deep.md << 'EOF'
---
model: opus
description: Deep analysis mode
---
Apply maximum analytical depth to the following task.
$ARGUMENTS
EOF
``

1. Try to invoke: /deep Analyze the pipeline
2. Result: "Unknown skill: deep" — no error, no warning, no suggestion about correct format
3. Move to commands/: mv .claude/skills/deep.md .claude/commands/deep.md
4. Try again: /deep Analyze the pipeline
5. Result: Works immediately. Appears in autocomplete.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.70

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

Related: #9716 (skills not discovered. No official response as of March 2026), #10145 (same flat-file bug, closed with 0 visibility), #17578 (merged messaging confusion), #17417 (case-sensitivity silent failure), #22171 (global skills path)