Project-level skills intermittently become 'Unknown skill' during sessions
Resolved 💬 4 comments Opened Apr 3, 2026 by okuyam2y Closed May 13, 2026
Description
Project-level custom skills defined in .claude/skills/SKILLNAME/SKILL.md intermittently become unavailable during a session, returning "Unknown skill" errors. Restarting Claude Code resolves the issue.
Steps to reproduce
- Define project-level skills in
.claude/skills/with properSKILL.mdformat - Start Claude Code — skills are listed and invocable normally
- Continue working in the same session
- At some point, invoking a skill (e.g.
/devlog-close) returns "Unknown skill" - Restart Claude Code — the same skill works again
Environment
- macOS (Darwin 25.4.0, ARM64)
- Skills are in
.claude/skills/SKILLNAME/SKILL.mdformat (project-level) - Context window still has capacity when the error occurs (not a compaction issue)
Notes
- This is intermittent — not every session, and timing varies
- All skills in the project become unavailable at once (not just one)
- The skill files on disk are unchanged; only a restart is needed to fix
- Related but distinct from #41530 (version-specific), #21428 (cache staleness), #11632 (new skills need restart)
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗