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-triggerable
  • deferred — invocable by /name but NOT listed in system context until invoked. Same pattern as deferred tools via ToolSearch

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 ToolSearch uses 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.

View original on GitHub ↗