SKM-X01 · Error
Filename is not exactly `SKILL.md`
`SKILL.md` is case-sensitive on the filesystems that enforce it — `skill.md` is a documented cause of a skill silently never appearing in Claude Code.
What the rule is
`SKILL.md` is case-sensitive on the filesystems that enforce it, and a file named `skill.md` is not found. This is the resolution of one of the most-cited bug reports in this space: a detailed root-cause analysis in the issue's body blamed `/tmp/` directory permissions, complete with an `EACCES` trace — and that analysis is what propagated into third-party troubleshooting articles and, for a time, into an AI-generated search summary for the topic.
The issue's actual resolution, posted by the same reporter after further investigation, was simpler: the file was named `skill.md`, not `SKILL.md`. Both explanations live in the same GitHub issue; only the second one is the answer.
Where it comes from
- anthropics/claude-code #17417 — resolved as filename case, not directory permissionsVerified issue — closed January 2026
Strict spec conformance
Not tested. Not run against the official reference validator (skills-ref) — not inferred from severity or from any other rule's result.
This is a separate question from the severity above and from which runtimes enforce it below — a rule can be a real, working extension in its home runtime while the reference validator still rejects the file outright, or vice versa. Both facts are reported, never one inferred from the other.
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Breaks the skill | Resolution of a verified, widely-cited bug report: a skill.md (wrong case) file never appeared, traced to filename case rather than the directory-permissions theory that circulated first. |
| Codex | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
| Cursor | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
| OpenClaw | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
| Hermes Agent | Not documented | Not documented for this runtime — we hold no runtime-specific evidence either way. |
How to fix it
- Rename the file to exactly `SKILL.md` — all capitals, no variation. On a case-insensitive filesystem (the macOS and Windows default) this may not surface locally even though it will elsewhere, so it's worth checking explicitly rather than trusting that the file opens correctly on your machine.
Elsewhere
- SKILL.md, the formatThe full frontmatter field table this rule is drawn from.
- Agent Skills Not WorkingThe diagnostic reference this rule’s portability and failure evidence comes from.
- All rulesEvery check the validator runs, grouped by class.