msd-core/docs/research/2026-05-12-skill-surface-budget.md

# Skill surface budget — research memo

**Date:** 2026-05-12
**Author:** triage analysis for issue [#3408](https://github.com/open-gsd/get-shit-done-redux/issues/3408)
**Status:** Research input for ADR-0010
**Reading time:** ~15 min

---

## 1. Problem statement

Claude Code and other runtimes that surface skills enumerate every installed skill's `name + description` into the system prompt on every turn, inside an `<available_skills>` block. This block is capped by `skillListingBudgetFraction` — default **1%** of the model's context window, ~**2,000 tokens** at 200k. When the combined descriptions exceed the cap, the harness silently truncates the tail. The reporter of #3408 has 135 installed skills across multiple plugins and observed dropped skills.

GSD's audited footprint:

| Metric | Value |
|---|---|
| Installed skills | 66 |
| Installed sub-agents | 33 (not listed in `<available_skills>` — invoked via `Task`) |
| Total skill description chars | 4,787 |
| Estimated description tokens (÷4) | ~1,196 |
| Mean description length | 72.5 chars |
| Description ceiling (enforced by `scripts/lint-descriptions.cjs`) | 100 chars |
| GSD share of a 200k 1% budget | ~60% |

GSD on its own consumes roughly 60% of the default skill-listing budget. When the user stacks any other plugin of comparable size (the reporter's `/doctor` shows several), the budget is breached and skills get dropped. This is not a GSD-only problem, but **GSD is the single biggest contributor in the typical install**, so we are the natural place for ecosystem-wide remediation to start.

## 2. What's already in place

GSD has done one consolidation pass and shipped one install-time lever:

- **`--minimal` / `--core-only` install flag** (`bin/install.js:123`, `gsd-core/bin/lib/install-profiles.cjs`). Stages a filtered copy of `commands/gsd/` into a temp dir before each runtime-specific copy step. Reduces ~12k tokens of cold-start overhead to ~700.
- **`MINIMAL_SKILL_ALLOWLIST`** — 6 skills: `new-project`, `discuss-phase`, `plan-phase`, `execute-phase`, `help`, `update`. Zero sub-agents in minimal.
- **Hard 100-char description budget**, enforced in CI by `scripts/lint-descriptions.cjs` and `npm run lint:descriptions`.
- **`gsd update` (without `--minimal`)** as the documented upgrade path from minimal → full.

The 100-char cap means **shrinking descriptions further is not a viable lever** — average is already 72.5 chars and the rare 99-char outliers exist because they earn their length (e.g. `gsd:progress`, `gsd:inbox`). Any future budget relief has to come from **emitting fewer skills**, not shorter ones.

## 3. Audit findings

### 3.1 Dependency topology (66 skills)

Hot nodes (counted by other-skill body references):

| Rank | Skill | Callers | Role |
|---|---|---|---|
| 1 | `phase` | 38 | Dispatcher to all phase-typed workflows |
| 2 | `review` | 11 | Review-output convergence |
| 3 | `config` | 7 | Project config display/edit |
| 4 | `progress` | 5 | Active-phase progress tracker |
| 5 | `update` | 5 | Upgrade path |
| 6 | `discuss-phase` | 2 | Main-loop step 1 |
| 6 | `execute-phase` | 2 | Main-loop step 3 |
| 6 | `new-project` | 2 | Bootstrap |
| 6 | `plan-phase` | 2 | Main-loop step 2 |

`phase` and `review` are the two skills whose absence would silently break dozens of others. **`phase` is referenced by 38 other skills but is not in the current minimal allowlist** — a latent gap worth raising. Confirm with a `--minimal` install + a `/gsd:audit-fix` invocation whether it still works.

### 3.2 Functional clusters

Greedy clustering by name + prose intent:

| Cluster | Skills | Desc chars | Desc tokens |
|---|---|---|---|
| `core_loop` | 6 | 346 | ~87 |
| `phase_variants` (includes `core_loop`) | 10 | 734 | ~184 |
| `audit_review` | 11 | 772 | ~193 |
| `milestone` | 4 | 292 | ~73 |
| `research_ideate` (`sketch`, `spike`, `forensics`, `explore`, `graphify`, `ns-ideate`) | 6 | 482 | ~121 |
| `workspace_state` (`pause`, `resume`, `workspace`, `workstreams`, `thread`, `capture`, `inbox`) | 7 | 496 | ~124 |
| `docs` | 2 | 160 | ~40 |
| `ui` | 2 | 122 | ~31 |
| `ai_eval` | 2 | 179 | ~45 |
| `ns_meta` | 6 | 315 | ~79 |
| `utility` (incl. `health`, `stats`, `settings`, `cleanup`, `pr-branch`, `ship`, `undo`, `fast`, `quick`, …) | 23 | 1,714 | ~429 |

The **utility** bucket is the heaviest single cluster (36% of description tokens) and is also the most heterogeneous — half of these likely run only once per project, not once per session. They're the prime candidates for an "advanced" or "opt-in" tier.

### 3.3 Consolidation ceiling

A second consolidation pass (collapsing all 10 `*-phase` skills into a single dispatcher) would save ~150 tokens at most, at the cost of making the user-facing slash commands less discoverable in the UI and complicating argument parsing. **Pure consolidation has diminishing returns** below the current 66-skill count; the next big saves come from changing *what gets surfaced* rather than *how it's written*.

## 4. Options

Each option is graded against five dimensions:

- **User UX**: how surprising / how much new mental model
- **Implementation cost**: relative dev effort
- **Dependency safety**: risk of breaking cross-skill calls
- **Token savings**: vs. current ~1,196 desc tokens
- **Anthropic dependency**: whether platform changes are required

### Option A — Expand install-time profiles (named feature flags)

Layer named profiles on top of the existing minimal/full binary:

```
gsd install --profile=core            # current --minimal (6 skills, 0 agents)
gsd install --profile=standard        # +phase, +review, +config, +progress (~14 skills)
gsd install --profile=full            # current default (66 skills, 33 agents)
gsd install --profile=core,audit,ui   # composable feature tags
```

| Dimension | Assessment |
|---|---|
| User UX | Familiar pattern (Cargo features, Helm `--set`, Ansible tags). Picker prompt on interactive install. |
| Implementation cost | **Low.** `install-profiles.cjs` already does the staging. Extend `MINIMAL_SKILL_ALLOWLIST` into a map of profile → set, add a `--profile` arg parser, add interactive `AskUserQuestion`. |
| Dependency safety | Need a manifest declaring each skill's required-skills set, so a profile can't ship an orphan caller. Add as CI lint. |
| Token savings | High — `standard` cuts ~70% of descriptions; named clusters give users granular control. |
| Anthropic dependency | None. |

**Pros:** ships unilaterally, leverages existing seam, low blast radius.
**Cons:** install-time only — users on a "full" install can't shrink without reinstall.

### Option B — Runtime enable/disable command

A `/gsd:surface` (or `gsd surface` CLI) command that toggles which skills are visible to the runtime without touching installed files:

```
/gsd:surface list                # show enabled/disabled
/gsd:surface disable ui audit    # hide a cluster
/gsd:surface profile standard    # apply a named profile
```

Implementation: write enable/disable state to `~/.claude/skills/<name>/SKILL.md.disabled` (rename) or maintain a `gsd-surface.json` manifest the installer reads on every `update`.

| Dimension | Assessment |
|---|---|
| User UX | Discoverable through `/gsd:help`. Lower commit than reinstall. Mirrors VS Code's enable/disable extension UX. |
| Implementation cost | **Medium.** Need persistent state separate from install files, plus a re-apply loop on `gsd update`. |
| Dependency safety | Same manifest requirement as Option A — disabling `phase` should warn that 38 skills depend on it. |
| Token savings | High — user-driven; can match Option A's savings. |
| Anthropic dependency | None for the rename approach. Cleaner if Anthropic supports a `SKILL.disabled` convention natively. |

**Pros:** in-session adjustable, no reinstall friction.
**Cons:** state lives outside the installer's idempotent model, so `gsd update` migrations get more complex.

### Option C — Further skill consolidation

Collapse semantically related skills into a single dispatcher with sub-modes:

```text
gsd-phase           → keeps existing
gsd-milestone {new|complete|summary|audit}        # was 4 skills (hypothetical)
gsd-research  {sketch|spike|forensics|explore}    # was 4 skills (hypothetical)
gsd-workspace {pause|resume|capture|inbox|thread} # was 5 skills (hypothetical)
```

(The hypothetical dispatchers above are written without the slash prefix to signal they are not shipped commands — Option C is a sketch, not a recommendation.)

| Dimension | Assessment |
|---|---|
| User UX | Breaking change for muscle-memorized slash commands; needs aliases for ≥1 release cycle. |
| Implementation cost | **Medium-high.** Argument-parsing inside each dispatcher; migration of cross-references in 30+ skill bodies; aliases; CHANGELOG entries. |
| Dependency safety | High — every cross-reference in existing skill bodies needs rewriting. The audit graph (3.1) is the migration spec. |
| Token savings | Moderate — ~200-300 tokens by collapsing the 13-15 named skills above into 3 dispatchers. |
| Anthropic dependency | None. |

**Pros:** also improves IA — the slash-command surface becomes more discoverable.
**Cons:** breaks user habits, doesn't compose with A/B (you still want profiles after consolidating).

### Option D — Lazy / on-demand descriptions (Anthropic ask)

Skills ship a 1-line *teaser* in the system prompt and the full description loads only when the model expresses interest (analogous to `ToolSearch` for deferred tools). Cuts per-skill listing cost to ~10 chars.

| Dimension | Assessment |
|---|---|
| User UX | Invisible to users. |
| Implementation cost | **Low for GSD** — add a `teaser:` frontmatter field. **High for Anthropic** — harness changes. |
| Dependency safety | N/A (purely about listing). |
| Token savings | ~85% of all skill-listing budget across the ecosystem. |
| Anthropic dependency | **Yes — platform feature.** |

This is the architecturally correct long-term answer. GSD can't ship it alone.

### Option E — Per-plugin budget allocation (Anthropic ask)

Instead of one shared `skillListingBudgetFraction`, give each plugin a dedicated quota (e.g. proportional to declared `skills.count` × ceiling). Eliminates one greedy plugin starving others.

| Dimension | Assessment |
|---|---|
| User UX | Invisible. |
| Implementation cost | **Low for GSD** — declare quota in `package.json` / plugin manifest. **Medium for Anthropic** — quota arithmetic and tie-breaking in the harness. |
| Token savings | Doesn't reduce total, but eliminates the silent-drop failure mode. |
| Anthropic dependency | **Yes.** |

### Option F — Sub-plugins / split distribution

Publish GSD as multiple npm packages: `get-shit-done-redux-core`, `get-shit-done-redux-milestones`, `get-shit-done-redux-research`, etc. Users install only what they need.

| Dimension | Assessment |
|---|---|
| User UX | Reasonable for advanced users; confusing for first-time installers. Needs a meta-package (`get-shit-done-redux`) that depends on the slim ones — analogous to VS Code extension packs. |
| Implementation cost | **High.** Multi-package build pipeline, version sync across packages, changelog routing, install-script forking. |
| Dependency safety | npm semver carries the contract; cross-package refs become real `require()` calls. |
| Token savings | Same as Option A in practice — token savings come from choosing not to install, not from the package boundary. |
| Anthropic dependency | None. |

**Pros:** clean separation, follows npm-ecosystem norms.
**Cons:** very high lift for the same token savings Option A delivers.

## 5. Recommendation

**Adopt Option A (named install profiles) as ADR-0010, with Option B (runtime surface toggle) as a Phase-2 amendment**. File Options D and E to Anthropic as platform asks.

Why this ordering:

1. **A reuses an existing seam.** `install-profiles.cjs` is already the staging point; this is the lowest-risk way to ship meaningful relief in the next release.
2. **A is composable.** Naming clusters as profiles is a forcing function for the dependency manifest, which we want anyway for the lint described in 3.1.
3. **B follows A naturally.** Once profiles exist, the `/gsd:surface` command is "apply a profile to a live install plus persist deltas." Without A, B has no profiles to apply.
4. **C is independent and orthogonal.** It can happen in parallel as IA cleanup; it should not block A.
5. **D and E are platform-level.** GSD ships A regardless; D/E are documented as cooperative asks so Anthropic sees them in context.

## 6. Anthropic platform asks

Drafted for filing at <https://docs.claude.com/feedback> or similar channel; copy unchanged into the issue or feedback form.

### Ask 1 — Native lazy skill descriptions

> Skills currently emit `name + description` into every system prompt. For large plugin ecosystems (135+ skills on power-user installs) this overruns `skillListingBudgetFraction` and silently drops skills. Proposal: add a frontmatter `teaser:` field (≤40 chars) that ships in the listing, with the full `description:` loaded only when the model requests it (analogous to ToolSearch for deferred tools). Backwards-compatible: skills without `teaser:` keep current behavior.

### Ask 2 — Per-plugin budget allocation

> A single `skillListingBudgetFraction` shared across all installed plugins causes silent truncation when one plugin's skill set is large. Proposal: each plugin declares a soft quota in its manifest; the harness arbitrates fairness when total demand exceeds budget (e.g. proportional shrink, with a documented order — most-recently-installed last to be cut). Surface drops in `/doctor` output today; do not drop silently.

### Ask 3 — Dependency-aware skill listing

> Skills can call other skills (in GSD, the `phase` skill is referenced by 38 others). When the harness drops a skill from the listing, it has no way to know whether anything else relies on it. Proposal: optional frontmatter `requires: [other-skill]` so the harness keeps the closure of dependencies in the listing, or warns the user at install time that a dropped skill is reachable from a kept one.

### Ask 4 — Disable/enable without uninstall

> Today the only way to remove a skill from the listing is to delete its `SKILL.md`. Proposal: a `.disabled` suffix (e.g. `SKILL.md.disabled`) or a per-skill `enabled: false` frontmatter is treated as "not surfaced" by the harness. This lets plugins ship surface-toggle UIs (like our proposed `/gsd:surface disable`) without touching install state.

## 7. Implementation sketch (for the ADR)

Phase 1 — profiles (ships with ADR-0010):

1. In `gsd-core/bin/lib/install-profiles.cjs`, replace the single `MINIMAL_SKILL_ALLOWLIST` constant with a `PROFILES` map. Each profile is the *transitive closure* over a base set, so `standard` includes `core` automatically.
2. Add a `requires:` frontmatter field to every skill that calls another skill in its body. Add a lint check in `scripts/lint-descriptions.cjs` (or a sibling `lint-skill-deps.cjs`) that fails CI if a skill body references another skill that isn't in its `requires` list, and that fails if any profile would ship a skill whose `requires` aren't satisfied.
3. Extend the `bin/install.js` argument parser: `--profile=<name>` (mutually exclusive with `--minimal`), `--profile=core,audit` for composition. Keep `--minimal` as an alias for `--profile=core`.
4. Interactive install: if no `--profile` is given and no runtime/location is forced, present an `AskUserQuestion`-style picker. (Cowork analog already in the install flow.)
5. `gsd update` re-applies the recorded profile from a small marker file (`~/.claude/skills/.gsd-profile`).

Phase 2 — runtime surface command (follow-up ADR or amendment):

1. `/gsd:surface` command writes to the profile marker and re-runs the staging step for the active runtime.
2. Once Anthropic ships Ask 4, switch from file-deletion to `.disabled`-suffix toggling.

## 8. Follow-ups outside this scope

- **Stale comment in `install-profiles.cjs`.** The module-level header cites "86 skills + 33 agents" producing ~12k tokens. The audited count is 66 + 33 — a previous consolidation pass already happened. Update the comment in a parallel cleanup commit when ADR-0010 lands.
- **Audit JSON refresh.** `docs/research/data/2026-05-12-skill-audit.json` is a one-shot snapshot. If we want it to stay current, wire the extraction script into `scripts/` and run it on `lint:skill-deps`. Not a blocker.

## 9. Risks and unknowns

- **The `phase` dispatcher gap in the existing minimal allowlist.** Confirm whether a fresh `--minimal` install + the documented main loop actually works end-to-end. If `discuss-phase`/`plan-phase`/`execute-phase` silently fall back to `/gsd:phase`, the minimal allowlist is currently broken. Track as a separate bug if confirmed.
- **Profile naming bikeshed.** `core` / `standard` / `full` vs. `minimal` / `recommended` / `everything` vs. functional names (`planning`, `audit`, `research`). Settle in the ADR's Open Questions.
- **Discoverability of disabled skills.** If `gsd:audit-fix` isn't surfaced, a user asking "audit my project" won't get it suggested. `/gsd:help` should list installed-but-not-surfaced skills with a one-line upgrade hint.
- **Telemetry blind spot.** GSD doesn't currently know which skills users invoke, so "drop the long tail" is theoretical. Survey or self-reporting may be needed before drawing the `standard` profile line.

## 10. References

- Issue: [#3408](https://github.com/open-gsd/get-shit-done-redux/issues/3408)
- Existing seam: `gsd-core/bin/lib/install-profiles.cjs`
- Description lint: `scripts/lint-descriptions.cjs`
- Install dispatcher: `bin/install.js:123` (mode parsing), `bin/install.js:8167-8207` (minimal staging)
- Audit data: [`docs/research/data/2026-05-12-skill-audit.json`](data/2026-05-12-skill-audit.json) (per-skill dep graph, description sizes, and cluster mapping — reproducible from `commands/gsd/` and `agents/`)
- Prior ADRs: 0008 (Installer Migration Module) and 0009 (Shell Command Projection Module) — both touch the same install pipeline this proposal extends.
- Ecosystem precedents: Cargo `[features]`, npm `optionalDependencies`, VS Code extension packs, Homebrew taps, Helm chart values, Ansible role tags, Linux kernel `make menuconfig` tristate, systemd target activation.