Say when to use each gstack skill in Claude Code's skill list (GST-2774) (#4387)

* Say when to use each gstack skill in Claude Code's skill list (GST-2774)

Claude Code's listing of each gstack skill now keeps a short when-to-use
clause after its first sentence, so Opus 5.5 loads /review on "review my
changes" and /plan-eng-review on "plan this feature" (GSTA-558).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Keep /review and /plan-eng-review within their size pins and refresh budgets

CI on the first head found five size and fact checks the new catalog
clause moved: the per-host SKILL.md size pins, the context-budget
ceilings, the deslop-shared-libs catalog byte pin, the Claude ship golden
and the catalog ceiling CLAUDE.md states. /review's and /plan-eng-review's
full descriptions are now shorter than before, so their pins go down, and
/plan-eng-review's scope gate is unchanged from main.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Say which skills keep no when-to-use clause in the changelog entry

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Update the catalog budget and voice-trigger docs for the when-to-use clause

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Drop "deploy this" from /ship's Claude Code skill list line

Deploying belongs to /land-and-deploy, so /ship's when-to-use clause keeps
"ship it, create a pr, push to main" only. Budgets, the size ledger and the
Claude ship golden are re-measured.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes

Review-Finding: p1/specialist-batched#1 reader=specialist-batched
Review-Finding: p1/red-team#1 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Re-measure the setup-gbrain size cap after merging main

Main grew setup-gbrain's always-loaded part to 38,621 bytes, and this
branch's when-to-use clause adds 55 more, so the cap measured on the old
base (38,637) is stale. The cap is now the merged measurement, 38,676.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-17 12:23:35 +00:00
1 parent 127bcd6d55
commit ab114c5308
83 files changed
+277 -216

No files matched your search

+21 -12
View File
@@ -29,7 +29,7 @@ import type { ModuleFilter } from './resolvers/types';
import { insertRuntimePreludes } from './resolvers/runtime-root';
import { generateSharedPreambleFile, hoistsPreamble, SHARED_PREAMBLE_FILE } from './resolvers/preamble-hoist';
import { extractVoiceTriggers } from './resolvers/voice-triggers';
import { frontmatterList, withTriggerLead } from '../lib/skill-triggers';
import { cutWords, frontmatterList, triggerList, triggerSentence, withTriggerLead } from '../lib/skill-triggers';
import { ALL_HOST_NAMES, resolveHostArg, getHostConfig } from '../hosts/index';
import type { HostConfig } from './host-config';
@@ -279,11 +279,14 @@ export { extractVoiceTriggers, processVoiceTriggers };
// asked to..." voice triggers, "Proactively..." routing guidance, and a
// "(gstack)" tag. This pile is the always-loaded catalog surface — every
// session pays for the full text. The catalog trim splits the description
// into a one-line catalog entry (lead sentence + "(gstack)") that stays in
// the frontmatter and drops the routing/voice prose. The body is not a home
// for it: Claude Code loads a skill body only after the skill is invoked, so
// routing text there can no longer route anything. Voice triggers live on in
// the root router's routing block ({{VOICE_TRIGGER_ROUTING}}).
// into a one-line catalog entry (lead sentence + a short when-to-use clause +
// "(gstack)") that stays in the frontmatter and drops the rest of the
// routing/voice prose. The clause is built by lib/skill-triggers.ts: the
// skill's `triggers:` list ("Use for: a, b."), else its "Use when" sentence. Without it the listing says what a skill is but not when to load
// it, and Opus 5.5 skipped /review on "review my changes" (GSTA-558). The body
// is not a home for routing text: Claude Code loads a skill body only after
// the skill is invoked. Voice triggers live on in the root router's routing
// block ({{VOICE_TRIGGER_ROUTING}}).
//
// Opt-out: `--catalog-mode=full` keeps v1.44 behavior (no trim, full
// description in frontmatter). Use when debugging routing regressions or
@@ -362,11 +365,18 @@ export function splitCatalogDescription(description: string): CatalogParts {
return { lead, routingProse, voiceLine, hasGstackTag };
}
/** Build the catalog-trimmed `description:` block. */
export function buildTrimmedDescription(parts: CatalogParts): string {
/** The when-to-use clause gets at most this many chars, and the whole trimmed description at most CATALOG_DESCRIPTION_MAX (test/catalog-budget.test.ts caps name + description at 260 bytes). */
const CATALOG_WHEN_MAX = 64;
const CATALOG_DESCRIPTION_MAX = 230;
/** Build the catalog-trimmed `description:` block: the lead, then the when-to-use clause when it fits and adds something. */
export function buildTrimmedDescription(parts: CatalogParts, triggers: string[] = []): string {
const lead = parts.lead.trim();
const suffix = parts.hasGstackTag ? ' (gstack)' : '';
return `${lead}${suffix}`;
const room = Math.min(CATALOG_WHEN_MAX, CATALOG_DESCRIPTION_MAX - lead.length - suffix.length - 1);
const sentence = triggerSentence(`${lead} ${parts.routingProse}`);
const when = room < 24 ? '' : triggerList(triggers, room) || (sentence && sentence !== lead ? cutWords(sentence, room) : '');
return when ? `${lead} ${when}${suffix}` : `${lead}${suffix}`;
}
/**
@@ -424,8 +434,8 @@ export function applyCatalogTrim(content: string, skillName: string): { content:
const parts = splitCatalogDescription(descText);
// If lead + (gstack) is already most of the text, no trim needed.
const trimmedLen = buildTrimmedDescription(parts).length;
if (trimmedLen >= descText.length - 20) return null;
if (buildTrimmedDescription({ ...parts, routingProse: '' }).length >= descText.length - 20) return null;
const newDesc = buildTrimmedDescription(parts, frontmatterList(content, 'triggers'));
// Replace description in frontmatter — keep trailing newline so the next
// YAML field doesn't collide on the same line as the description value.
@@ -433,7 +443,6 @@ export function applyCatalogTrim(content: string, skillName: string): { content:
// case: an interior ": " like "Ship workflow: detect..." which a strict YAML
// parser reads as a nested mapping and rejects — #1778). toYamlInlineScalar
// only quotes when needed, so descriptions without special chars stay plain.
const newDesc = buildTrimmedDescription(parts);
// Function replacer (not a string) so a `$` in the description — e.g. a future
// skill referencing `$B`/`$D` — can't be interpreted as a `$&`/`$1` replacement
// pattern and silently corrupt the frontmatter.