feat(catalog): T4 — catalog trim + proactive-suggestions.json (Phase A.4)

Shortens frontmatter `description:` in every Claude SKILL.md to a single
lead sentence + (gstack) tag. The routing prose ("Use when asked to...",
"Proactively suggest...") and voice triggers move to a "## When to invoke"
body section so they remain discoverable inside the skill. A per-run
registry at scripts/proactive-suggestions.json aggregates the routing/
voice text for all 52 skills so agents can pull guidance on demand
without paying for it in the always-loaded catalog.

Build flag --catalog-mode=full restores v1.44 legacy behavior (full
multi-line descriptions in frontmatter). Default is trim.

splitCatalogDescription() extracts: lead sentence, routing paragraphs,
voice-triggers line, (gstack) tag presence. Short descriptions (<120
chars, already trimmed) are skipped via a guard so re-runs are idempotent.

Measured impact (vs v1.44.1 baseline):
- Catalog tokens (sum of description bytes / 4): 9,319 → 4,045  (-56.6%)
- Total SKILL.md corpus bytes:                   2,915 KB → 2,880 KB (-1.2%)
- Routing prose preserved as in-skill "## When to invoke" sections
- 52 skill entries in scripts/proactive-suggestions.json (on-demand registry)

The corpus drop is small because catalog trim MOVES text from frontmatter
to body, it doesn't delete it. The headline win is the catalog: the
always-loaded system prompt surface drops by more than half.

Test plan:
- bun test test/gen-skill-docs.test.ts: 389 pass, 0 fail
- Manual: ship/SKILL.md frontmatter description is now ONE line ending
  with `(gstack)`; allowed-tools field on next line (YAML well-formed)
- Manual: scripts/proactive-suggestions.json contains 52 entries
- bun run gen:skill-docs --catalog-mode=full restores legacy behavior

53 files changed (52 SKILL.md across hosts + the new proactive-suggestions.json).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-05-25 20:35:15 -07:00
parent da5f26872f
commit 0d68ef1a39
54 changed files with 1078 additions and 398 deletions
+16 -13
View File
@@ -2,19 +2,7 @@
name: plan-tune
preamble-tier: 2
version: 1.0.0
description: |
Self-tuning question sensitivity + developer psychographic for gstack (v1: observational).
Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences
(never-ask / always-ask / ask-only-for-one-way), inspect the dual-track
profile (what you declared vs what your behavior suggests), and enable/disable
question tuning. Conversational interface — no CLI syntax required.
Use when asked to "tune questions", "stop asking me that", "too many questions",
"show my profile", "what questions have I been asked", "show my vibe",
"developer profile", or "turn off question tuning". (gstack)
Proactively suggest when the user says the same gstack question has come up before,
or when they explicitly override a recommendation for the Nth time.
description: Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). (gstack)
triggers:
- tune questions
- stop asking me that
@@ -35,6 +23,21 @@ allowed-tools:
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->
## When to invoke this skill
Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences
(never-ask / always-ask / ask-only-for-one-way), inspect the dual-track
profile (what you declared vs what your behavior suggests), and enable/disable
question tuning. Conversational interface — no CLI syntax required.
Use when asked to "tune questions", "stop asking me that", "too many questions",
"show my profile", "what questions have I been asked", "show my vibe",
"developer profile", or "turn off question tuning".
Proactively suggest when the user says the same gstack question has come up before,
or when they explicitly override a recommendation for the Nth time.
## Preamble (run first)
```bash