Reduce static skill context after one-time setup is settled
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Problem
Even after one-time setup prompts have been answered and their runtime branches skip, the prose that explains those branches remains inline in every generated `SKILL.md`. The host loads that static text on every skill invocation.
Measured on gstack v1.63.0.0 in the Codex install on 2026-08-17:
- `office-hours/SKILL.md`: 2,102 lines
- `review/SKILL.md`: 1,457 lines
- multiset line intersection: 1,051 identical lines
That is a static context cost, separate from whether the preamble shell actually executes.
## Why this is not #1572
#1572 proposes caching repeated *runtime preamble output* within a session. This report is about the already-loaded `SKILL.md` prose: a branch can do no work and still consume context because its full setup instructions were injected before execution.
## Why this is not fully covered by #2342
#2342 factors the shared behavioral/conduct block for the Claude host and fixes a duplicated macro. It deliberately leaves operational/setup prose inline, and notes that external hosts keep the full inline block. The current Codex-host skill files above still share 1,051 lines.
## Suggested direction
Factor settled one-time setup and operational explanations into a shared on-demand reference, while leaving a compact executable contract inline. Alternatively, generate a post-setup skill variant selected from marker state so machines that have completed onboarding do not keep loading onboarding prose.
The important test is static: after setup is settled, compare generated skill file size/context, not only emitted shell output.
## Downstream evidence
BucketMap issue areddy294/BucketMap#927 measured this as the largest local gstack token-cost source. That repo can reduce its own always-loaded `CLAUDE.md` and wrap Codex output, but it cannot remove generated gstack skill context locally without forking the install.
Contributor guide
Research direction
Start by comparing the generated office-hours/SKILL.md and review/SKILL.md files, then trace the generator that produces their shared setup prose. Evaluate the shared on-demand reference and post-setup variant options against the existing host behavior. Done means settled setup no longer contributes the repeated static context, while the compact executable contract remains and generated file size or context is tested.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100