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

  1. Define project-level skills in .claude/skills/ with proper SKILL.md format
  2. Start Claude Code — skills are listed and invocable normally
  3. Continue working in the same session
  4. At some point, invoking a skill (e.g. /devlog-close) returns "Unknown skill"
  5. Restart Claude Code — the same skill works again

Environment

  • macOS (Darwin 25.4.0, ARM64)
  • Skills are in .claude/skills/SKILLNAME/SKILL.md format (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)

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗