Project skills beyond a session-level cap return "Unknown skill" from the Skill tool despite valid SKILL.md files

Status Open
Maintainer reply None cached
Activity 1 comment · opened Sep 9, 2026

Summary

In a project with 61 project-scoped skills installed under .claude/skills/<name>/SKILL.md (each with valid, uniformly-structured frontmatter: name, description, when_to_use, dependencies, metadata), only ~14 of the 61 appear in the session-start "available skills" system-reminder listing. Calling the Skill tool directly by exact name on any of the other ~47 returns Unknown skill — they are not just hidden from the listing, they are not invocable at all.

This looks like the same root cause as #31505 ("Project skills silently dropped beyond ~28 limit — no warning or error"), which reported the identical symptom (Skill() returning "Unknown skill" for dropped skills, selection not alphabetical/mtime/size-based) at a lower skill count. That issue was auto-closed as stale rather than resolved, and is now locked, so filing fresh here with a larger reproduction (61 skills) rather than commenting.

Environment

  • Claude Code running in a remote/cloud session (claude.ai/code)
  • Project also has 5 plugins enabled (system@local, workflow@local, development@local, memory@local, setup@local) contributing their own skills, plus the standard built-in skills (docx, pdf, pptx, xlsx, artifact-design, etc.)
  • Total skills visible across plugins + built-ins + project skills is roughly 80-90

What was ruled out

  • File corruption: all 61 SKILL.md files are well-formed; the unregistered ones have the same frontmatter shape/fields as the registered ones.
  • Install/mtime order: the 14 registered skills are scattered non-contiguously through both an alphabetical listing and an mtime-batch ordering of the 61 directories — no correlation with directory scan order.
  • File size / description length: sizes of registered vs. unregistered SKILL.md files fully overlap (checked several from each group, ~3.7KB-5.9KB range in both groups); no size threshold distinguishes them.
  • Not a /clear-session artifact: persisted across a /clear + /continue resumption within the same container — same 14 registered both before and after.

Reproduction

  1. Install/copy 60+ well-formed project skills into .claude/skills/<name>/SKILL.md in a single project.
  2. Start a session; note the "available skills" system-reminder only lists a subset.
  3. Call the Skill tool with skill: "<name-of-an-unlisted-skill>" for one of the skills not in that listing.
  4. Observe: Unknown skill error, even though the file exists on disk with valid frontmatter identical in structure to a working skill.

Question / request

Is there a documented cap (character/token budget, or a hard count) on how many skills — across project + plugin + built-in — Claude Code will register as invocable per session? If so:

  • What determines which skills "win" when the cap is exceeded (doesn't appear to be alphabetical, mtime, or size-based from what we observed)?
  • Is it configurable (e.g. a settings.json field)?
  • Is there a way to make all project-installed skills invocable regardless of count, or a recommended pattern for large skill libraries (60+ skills) that doesn't hit this ceiling?

Docs checked (https://code.claude.com/docs/en/skills.md) don't appear to detail the discovery/registration mechanism or any such cap.

---
🤖 Generated with Claude Code

https://claude.ai/code/session_016zVdb3c27hyMtBWjdBYm9b

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗