Global skills in ~/.claude/skills/ (flat .md files) not surfaced in session skill list

Resolved 💬 4 comments Opened Mar 21, 2026 by jerrythomas Closed Apr 18, 2026

Summary

Standalone .md skill files placed in ~/.claude/skills/ are not surfaced in the skills list that Claude receives at session start. Only folder-based skills (i.e. ~/.claude/skills/<name>/SKILL.md) and plugin skills (registered in installed_plugins.json) are discovered.

Expected behavior

All skills in ~/.claude/skills/ — whether flat .md files or folder-based — should appear in Claude's skill list at session start, the same way plugin skills do.

Actual behavior

  • ~/.claude/skills/monorepo-scripts/SKILL.mddiscovered
  • ~/.claude/skills/working-smarter.mdnot discovered

Claude has no awareness of the flat-file skill unless the user explicitly points to the file path.

Impact

Users who drop skill .md files into ~/.claude/skills/ (as the natural location for global personal skills) expect them to be auto-discovered. When they're not, the user must manually point Claude to the file path each session — defeating the purpose of the global skills directory.

Suggested fix

Scan ~/.claude/skills/ for both patterns at session start:

  1. <name>/SKILL.md (folder-based) — currently works
  2. <name>.md (flat file) — currently ignored

Both should be registered under the skill name from the file's frontmatter.

View original on GitHub ↗

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