Cursor skill discovery drops all workspace skills when any user-level skills folder exceeds the scan depth limit #17215

Activity

1. juliusmarminge commented on Oct 8, 2026

   

   juliusmarminge

   on Oct 8, 2026

   Member

   More actions

   Note

   Grok responding on behalf of Julius.

   Thanks for the detailed write-up. Reading the code on main (12069eefd), the diagnosis looks right.

   What the code does

   • All eight roots share one CursorSkillScanBudget: project .cursor/.agents/.codex/.claude skills first, then the same four under home (CursorSkills.ts:225-246). Limits are MAX_SKILL_DEPTH = 10 and 10,000 entries (:26-28).
   • When a directory at depth 10 has a subdirectory, the walk sets budget.exhausted = true and stops (:207-210). Running out of entries does the same (:199-202). So hitting a limit in one subtree marks the whole scan as failed, rather than just skipping that subtree.
   • probeCursorSkills then throws CursorSkillsProbeError(scan-budget-exhausted) and discards skills it already found (:264-276). CursorDriver.snapshotForCwd turns that into a ProviderDriverError (CursorDriver.ts:267-285). With no workspace snapshot, the composer appears to get no skills.
   • The walk has no dot-directory or node_modules filter (:198-211). It also keeps going below a directory that already has a SKILL.md (:163-191). That would explain why a stale ~/.claude/skills/synced/<id>/.staging/... tree can reach the depth limit.

   Why it fails hard
   Failing the probe appears to be deliberate. #9180, which added this scanner, says "Strict probeCursorSkills fails when scan budgets are exhausted". The same pattern in AntigravitySkills.ts:158 explains it: "Read failures remain typed so workspace snapshots do not cache partial results." That reasoning works for a transient read error. It doesn't work for a depth or entry limit, because the same tree fails the same way on every refresh, so retrying never recovers. A filesystem error in any root (budget.incomplete, :67, :249-253) also fails the whole probe, so an unreadable user-level folder could probably cause the same symptom.

   The other providers don't walk this deep. Claude reads only the direct children of each root and skips anything it can't read (ClaudeSkills.ts:315-347). Antigravity stops at the first SKILL.md and goes at most one level down (AntigravitySkills.ts:206-229). Grok and Codex get their skill lists from the CLI or app-server instead of scanning the filesystem.

   Possible fix (not yet verified against Cursor's own loader)

   1. When a subtree hits the depth limit, skip it instead of setting exhausted. Keep the entry budget as a real hard stop.
   2. Skip dot-directories and node_modules. If Cursor's loader allows it, also stop descending once a directory has a SKILL.md.
   3. Optionally, give each root its own budget, or return partial results with a flag, so a bad user-level root can't hide project skills.

   Related

   • [Bug]: Workspace skill catalogs retain failed discovery and discard newer scan results #16866 covers how failed discovery is cached and retried. Fixing that alone probably wouldn't help here, since every new scan would fail the same way.
   • [Bug]: Cursor/OpenCode skill discovery returns zero skills despite skills existing on disk (Claude/Codex discover them fine) #2736 is an older issue with a similar symptom, from before the scan budget existed.
   • Open PR fix(server): include Cursor plugin skills in the composer picker #16430 rewrites part of CursorSkills.ts to add plugin skills. The plugin scan reuses the same shared budget and doesn't change the depth behavior. That would use up more of the shared entry budget, so the two changes may conflict.
   • fix(cursor): discover symlinked skills as package boundaries #9420 and fix(providers): discover workspace skills everywhere #9180 are the earlier Cursor discovery PRs. I didn't find an open PR that fixes this.

   Workaround until then: move stale .staging or .trash folders out of ~/.claude/skills, as you did, then refresh providers.
2. juliusmarminge

   added

   bugSomething is broken or behaving incorrectly.Something is broken or behaving incorrectly.

   via-triageFiled through npx t3 triageFiled through npx t3 triage

   on Oct 8, 2026
3. m4tta commented on Oct 9, 2026

   

   m4tta

   on Oct 9, 2026

   More actions

   Same all-or-nothing failure here, but from the 10,000 entry budget, not the depth limit. #17389 doesn't cover this. It only changes the depth path and keeps the entry-budget failure on purpose (it adds a test that a root with more than 10,000 entries still fails the probe). So this case stays broken after that PR merges.

   What happened

   In one workspace, Cursor threads only showed /model and /usage-limits in the composer. Other workspaces were fine, so it looked intermittent.

   Cause

   A project skill writes its run output into its own folder, <workspace>/.cursor/skills/verify-ava/artifacts/<run-id>/ (screenshots, videos, transcripts). After a month that folder had 301 runs and 10,651 entries. Max depth was 8, so the depth limit wasn't involved.

   Project roots are scanned first. The budget ran out inside <workspace>/.cursor/skills (remainingEntries === 0, CursorSkills.ts:199-202), probeCursorSkills threw scan-budget-exhausted, and every skill got dropped, including the ones it had already found.

   Also, ~/.agents/skills is a symlink to ~/.claude/skills on this machine. discoverSkillsInRoot creates a new visitedDirectories for each root, and both roots resolve to the same realpath, so the same 871-entry tree is charged to the budget twice. Skills get deduped by name, but the budget doesn't.

   Per-root scan before the workaround

   <workspace>/.cursor/skills   10,911 entries (10,651 in verify-ava/artifacts), depth 8
   <workspace>/.claude/skills        8 entries
   ~/.cursor/skills                  1 entry
   ~/.agents/skills                871 entries (symlink to ~/.claude/skills)
   ~/.codex/skills                  79 entries
   ~/.claude/skills                871 entries
   

   Trace

   {"name":"probeCursorSkills",...,"exit":{"_tag":"Failure","cause":"CursorSkillsProbeError: Cursor skill discovery for '<workspace>' was incomplete (scan-budget-exhausted)..."}}
   {"name":"refreshWorkspaceSnapshot",...,"cause":"ProviderDriverError: Provider driver 'cursor' failed to create instance 'cursor': Failed to discover Cursor skills for '<workspace>'..."}
   {"name":"recoverRefreshFailure",...,"provider registry refresh failed; preserving cached providers"}
   

   Repro

   1. Workspace with any skill at .cursor/skills/<name>/SKILL.md.
   2. mkdir -p .cursor/skills/<name>/artifacts && for i in $(seq 1 11000); do touch .cursor/skills/<name>/artifacts/f$i; done
   3. Open a Cursor thread in that workspace and type /. No skills, and the trace shows scan-budget-exhausted.

   Suggestions beyond the triage comment

   • Don't fail the probe on entry exhaustion either. Return what was found, or give each root its own budget, so one big project skill can't hide everything else.
   • Stop recursing once a directory has a SKILL.md, if Cursor's loader allows it. Then node_modules, build output or run artifacts next to a SKILL.md wouldn't count.
   • Share visitedDirectories (or a set of root realpaths) across roots so a symlinked root is only charged once.

   Workaround

   Deleted the old run folders under artifacts/ and refreshed providers.

   Environment

   T3 Code 0.0.45 (v0.0.45, 6c8fed3), desktop app (Nightly) with local server, macOS 26 arm64 (Darwin 25.5.0), Node v26.8.2.

   ---

   Posted via t3 triage with Claude Code (Claude Opus 5.5, claude-opus-5-5).
4. Yash-Singh1

   closed this as completedin #17389on Oct 11, 2026
5. ScottN-PV commented on Oct 11, 2026

   

   ScottN-PV

   on Oct 11, 2026

   Contributor

   More actions

   Thanks for the detailed trace. I ran both cases with probeCursorSkills on a real filesystem (Linux, Node 24), using main's scanner (unchanged from b9afba5 through bf725cb) and #17389's head (eedd33d). Both behave the same:

   • A project skill with 11,000 files in a subfolder beside its SKILL.md: scan-budget-exhausted, no skills returned.
   • ~/.agents/skills symlinked to a ~/.claude/skills tree with 6,000 files: scan-budget-exhausted. The same tree without the symlink passes, so the budget charges it twice.

   #17389 only stops the depth limit from failing the whole scan. It leaves both of these as they are, and if it merges as is, it closes this issue. I can open a separate small PR for them.

   For the symlink case I'd scan each real root once, keeping the current root order. The entry-budget case needs a maintainer decision, as in option 3 of the triage comment: keep failing hard, return the skills found so far with an incomplete flag, or give each root its own budget. Partial results alone keep the skills already found but still skip every later root, and the probe fails hard today so snapshots never cache a partial list. I'd give each root its own budget and skip only a root that runs out, with a log line, so one large skill folder can't hide the others. Stopping the walk at a SKILL.md would also help, but I don't know whether Cursor's loader allows nested skills. Limits: Linux only, the probe called directly rather than through the composer, and none of these remedies tested yet.

   Maintainers, which option do you want?

   Written by Claude Fable 5.1 and Claude Opus 5.5 on behalf of ScottN-PV.
6. Culpable commented on Oct 15, 2026

   

   Culpable

   on Oct 15, 2026

   More actions

   The entry-budget case still reproduces after the depth-limit fix in #17389.

   Environment:

   • T3 Code 0.0.46-nightly.20261014.3132
   • Cursor SDK 1.0.35
   • macOS

   A user-installed skill has test dependencies under: ~/.agents/skills/<skill>/tests/node_modules/

   With Cursor selected, the $ picker offers no skills. The server repeatedly logs:

   CursorSkillsProbeError: Cursor skill discovery for '' was incomplete (scan-budget-exhausted).

   A read-only replay of the installed scanner’s directory walk reaches the shared 10,000-entry limit inside that node_modules tree. That single skill package accounts for approximately 8,849 entries before discovery stops. No filesystem errors occur.

   The installed scanner includes #17389’s depth-limit change, but entry exhaustion still fails the entire probe and discards skills already discovered.

   Proposed fix:

   1. Skip node_modules when discovering skills.
   2. Stop descending beneath a directory containing SKILL.md, provided this matches Cursor’s supported nested-skill behaviour.
   3. If nested skills must remain discoverable, restrict traversal to their supported locations instead of walking every supporting directory.
   4. Preserve discovered skills when a limit is reached, with an explicit incomplete-discovery indication.

   The composer needs skill metadata from SKILL.md. Installed test dependencies, supporting assets and run outputs must not make unrelated skills disappear.

   Could this remaining case be tracked separately or the issue reopened? The depth fix does not resolve it.
7. Yash-Singh1

   reopened this on Oct 15, 2026