feat(skills): add lazy load mode to reduce startup token usage

[LastKnight1881]

Summary

Adds a skills.lazy config flag (default: false) to reduce token usage at session startup for agents with large skill libraries.

Problem

The full skills index is injected into every session's system prompt unconditionally. On a typical install with 100+ skills across 30+ categories, this adds ~3,500–5,000 tokens to every session. For local models with smaller context windows (32k–64k), this causes aggressive context compression after only a handful of messages.

Solution

When skills.lazy: true is set in cli-config.yaml, the full skills index is replaced with a compact ~60-token notice:

Skills are available but not pre-loaded. Use skill_view(name) to load a specific skill when you need it, or skills_list() to browse available skills.

The agent retains full access to all skills via skill_view() and skills_list() — it just doesn't have them all in context at startup.

Config

skills:
  lazy: true  # default: false

Changes

• run_agent.py: Read skills.lazy from config into self._skills_lazy; gate build_skills_system_prompt() on it; inject compact notice when lazy mode is active.
• cli-config.yaml.example: Document the new lazy flag with comments.

Backwards compatibility

Default is false — existing behavior is fully preserved for all users who don't opt in.

[alt-glitch]

Duplicate of #13980 (and #12379) — same lazy skill loading feature with different config key name (skills.lazy vs skills.loading: lazy).

[alt-glitch]

Duplicate of #13980 (and #12379) — same lazy skill loading feature with different config key name.

[ether-btc]

14 lines in run_agent.py — this is a targeted fix for the startup token cost problem. Given it's labeled "duplicate", worth checking if there's a canonical version merged or in review that this should close in favor of.

If not superseded: the approach of gating skill loading behind a config flag (skills.lazy_load: true) is the right abstraction. The concern would be: does this introduce a lazy-import pattern that breaks existing synchronous skill_view() calls elsewhere in the codebase?

Recommend: check all call sites of skill_view and get_skill for synchronous expectations. If any are in the startup path and now become lazy, the first call after startup could be slower than before for cold evaluation.

[teknium1]

Thanks for the PR. Closing based on a standing design rule in our contributor guide: for tools that serve instructional / procedural content (skills, system prompts, playbooks), full-content loading should be the default AND only option. Models will use any excuse to read less — if we add a lazy mode, they'll use it, skip the bulk of the content, and miss critical pitfalls and verification steps that only appear later in a SKILL.md.

The context-pressure concern is real for 32k–64k context models, but the right lever there is skill set curation (fewer installed skills / hermes curator), not lazy-loading the index. The skills index itself is the small part — it's the full SKILL.md reads that cost tokens, and those are driven by skill invocation, not session startup.

For reference: the same pattern was rejected in April 2026 when pagination was proposed for skill_view (see AGENTS.md 'Agent-Facing Tool Design: No Lazy-Reading Escape Hatches').