Project skills beyond a session-level cap return "Unknown skill" from the Skill tool despite valid SKILL.md files
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.mdfiles 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.mdfiles 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+/continueresumption within the same container — same 14 registered both before and after.
Reproduction
- Install/copy 60+ well-formed project skills into
.claude/skills/<name>/SKILL.mdin a single project. - Start a session; note the "available skills" system-reminder only lists a subset.
- Call the
Skilltool withskill: "<name-of-an-unlisted-skill>"for one of the skills not in that listing. - Observe:
Unknown skillerror, 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
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗