Feature: skill visibility tiers (deferred/lazy-loaded skills)
Open 💬 0 comments Opened Jul 7, 2026 by Ling-Jun
Problem
All skills in ~/.claude/skills/ are listed in the system context every turn, regardless of whether they're auto-triggerable or purely user-invoked. With 30-40+ skills, this burns ~800-1200 tokens per turn on descriptions alone — compounding across long sessions.
Some skills benefit from always being listed (auto-trigger on context match, e.g. /dev-workflow fires on git operations). Others are strictly user-invoked (e.g. /standup, /handoff) and gain nothing from being in context until explicitly called.
Proposed solution
Support two visibility tiers in skill frontmatter:
---
name: standup
description: "Prepare daily standup notes"
visibility: deferred # <-- new field
---
active(default, current behavior) — listed in system context every turn, auto-triggerabledeferred— invocable by/namebut NOT listed in system context until invoked. Same pattern as deferred tools viaToolSearch
Why this matters
- Token efficiency — deferred skills don't consume context tokens until needed
- Cleaner context — fewer listings means less noise for the model to reason over
- Already precedented — deferred tool loading via
ToolSearchuses this exact pattern. Skills could follow the same mechanism
Workarounds today
- Move infrequent skills to project-scoped
.claude/skills/in a specific repo (limits availability) - Remove skills from the directory when not needed (impractical)
Neither is satisfactory.