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.
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
Which runtimes enforce it
| Runtime | Effect | Note |
|---|---|---|
| Claude Code | Breaks the skill | Resolution of one of the most-cited bug reports in this space: a detailed root-cause analysis blaming directory permissions turned out to be filename case. |
| Codex | Breaks the skill | Resolution of one of the most-cited bug reports in this space: a detailed root-cause analysis blaming directory permissions turned out to be filename case. |
| Cursor | Breaks the skill | Resolution of one of the most-cited bug reports in this space: a detailed root-cause analysis blaming directory permissions turned out to be filename case. |
| OpenClaw | Breaks the skill | Resolution of one of the most-cited bug reports in this space: a detailed root-cause analysis blaming directory permissions turned out to be filename case. |
| Hermes Agent | Breaks the skill | Resolution of one of the most-cited bug reports in this space: a detailed root-cause analysis blaming directory permissions turned out to be filename case. |
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.