chore: reduce context burn from skill listing — adopt lazy skill-index pattern #24

New Issue

mathias · 2026-05-20T19:17:21Z

mathias commented

2026-05-20 19:17:21 +00:00

Problem

87 skills are currently injected into every conversation's system-reminder as a flat name list. This costs tokens on every turn regardless of whether any skill is relevant.

Observed in session-start hook: the available-skills block enumerates all skills alphabetically — ~60+ GSD skills plus ~20 engineering skills — every time.

Proposed solution

Replace the full skill dump with a lazy skill-index pattern:

Keep a single SKILLS_INDEX.md (already exists at ~/dev/.skills/SKILLS_INDEX.md for the engineering skills) that the agent can query on demand.
Surface only a minimal hint in the system-reminder: e.g. "87 skills available — query SKILLS_INDEX or use Skill tool".
The agent reads the index only when it needs to pick a skill, not on every turn.

This mirrors the pattern used in some published Claude Code skill setups (e.g. video tutorials showing a single index file instead of injected lists).

Impact

Cuts per-turn context by the length of the skill list (~200–300 tokens/turn).
No loss of capability — agent still has full access via Skill tool.

Open questions

Does the current hook system support conditional/lazy injection? Check ~/.claude/hooks/ and settings.json.
GSD skills are installed under ~/.claude/skills/ by the GSD plugin; the index approach may need a GSD-side change too.
Engineering skills index already exists (SKILLS_INDEX.md) — reuse as the single source, extend to cover GSD skills?

Acceptance criteria

System-reminder no longer lists all skill names on every turn
Agent can still discover and invoke any skill when relevant
Skill invocation latency (time-to-first-use) is acceptable

## Problem 87 skills are currently injected into every conversation's system-reminder as a flat name list. This costs tokens on every turn regardless of whether any skill is relevant. Observed in session-start hook: the `available-skills` block enumerates all skills alphabetically — ~60+ GSD skills plus ~20 engineering skills — every time. ## Proposed solution Replace the full skill dump with a **lazy skill-index** pattern: 1. Keep a single `SKILLS_INDEX.md` (already exists at `~/dev/.skills/SKILLS_INDEX.md` for the engineering skills) that the agent can query on demand. 2. Surface only a minimal hint in the system-reminder: e.g. `"87 skills available — query SKILLS_INDEX or use Skill tool"`. 3. The agent reads the index only when it needs to pick a skill, not on every turn. This mirrors the pattern used in some published Claude Code skill setups (e.g. video tutorials showing a single index file instead of injected lists). ## Impact - Cuts per-turn context by the length of the skill list (~200–300 tokens/turn). - No loss of capability — agent still has full access via `Skill` tool. ## Open questions - Does the current hook system support conditional/lazy injection? Check `~/.claude/hooks/` and `settings.json`. - GSD skills are installed under `~/.claude/skills/` by the GSD plugin; the index approach may need a GSD-side change too. - Engineering skills index already exists (`SKILLS_INDEX.md`) — reuse as the single source, extend to cover GSD skills? ## Acceptance criteria - [ ] System-reminder no longer lists all skill names on every turn - [ ] Agent can still discover and invoke any skill when relevant - [ ] Skill invocation latency (time-to-first-use) is acceptable

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mathias/hyperguild#24