Files
gstack/lib/skill-triggers.ts
T
Garry Tanandcapy-ai[bot] ab114c5308 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>
2026-11-17 12:23:35 +00:00

88 lines
4.5 KiB
TypeScript

/**
* Trigger-first skill wording for harness listings (GSTA-135 skill use).
*
* Frozen rule, built only from each skill's own frontmatter, and the trigger
* part always comes first:
* - Router lines (lib/harness-register.ts, 160 chars): the description's own
* trigger sentence (its first sentence that starts "Use when", "Use to",
* "Use for", ...), followed by the description's first sentence when both
* fit. A description with no trigger sentence, or whose trigger sentence is
* the catalog-trimmed Claude render's short "Use for:" clause, uses the
* triggers list below instead.
* - Hermes descriptions (scripts/gen-skill-docs.ts, hosts/hermes.ts): a lead
* of at most 57 chars, the part Hermes's skills index shows: "Use for: "
* and the skill's `triggers:` list in frontmatter order, as many whole
* entries as fit; without triggers, the trigger sentence (or first
* sentence) cut at a word. The description's own trigger sentence, which
* the list repeats, is dropped, so a render does not grow.
*/
const TRIGGER_SENTENCE = /^Use (when|whenever|to|for|after|before|on|if)\b/;
export const normalizeDescription = (description: string) => description.replace(/\s*\(gstack\)\s*$/, '').replace(/\s+/g, ' ').trim();
export const sentences = (description: string): string[] => normalizeDescription(description).split(/(?<=[.!?])\s+/).filter(Boolean);
/** Cuts at the last word boundary that leaves room for "...". */
export function cutWords(text: string, max: number): string {
if (text.length <= max) return text;
const cut = text.slice(0, max - 3);
const space = cut.lastIndexOf(' ');
return (space > max / 3 ? cut.slice(0, space) : cut).replace(/[\s,;:]+$/, '') + '...';
}
/** The description's own trigger sentence, or ''. */
export const triggerSentence = (description: string) => sentences(description).find(s => TRIGGER_SENTENCE.test(s)) ?? '';
/** "Use for: a, b, c." from a skill's triggers list, as many whole entries as fit in max chars ('' without triggers). */
export function triggerList(triggers: string[], max: number): string {
const items = triggers.map(t => t.replace(/\s+/g, ' ').trim()).filter(Boolean);
if (!items.length) return '';
let lead = 'Use for: ' + items[0] + '.';
for (const t of items.slice(1)) {
const next = lead.slice(0, -1) + ', ' + t + '.';
if (next.length > max) break;
lead = next;
}
return cutWords(lead, max);
}
/** A trigger-first lead of at most max chars: the triggers list, else the trigger sentence or first sentence cut at a word. */
export function triggerLead(description: string, triggers: string[], max: number): string {
return triggerList(triggers, max) || cutWords(triggerSentence(description) || sentences(description)[0] || '', max);
}
/** A description led by triggerLead on its own first line; the description's trigger sentence is dropped when the lead comes from the triggers list, which that sentence repeats. */
export function withTriggerLead(description: string, triggers: string[], max: number): string {
const lead = triggerLead(description, triggers, max);
const sentence = triggerSentence(description);
if (!sentence || !triggerList(triggers, max)) return lead + '\n' + description;
const tag = /\(gstack\)\s*$/.test(description) ? ' (gstack)' : '';
return lead + '\n' + sentences(description).filter(s => s !== sentence).join(' ') + tag;
}
/** A router line of at most max chars: the trigger part first, then the description's first sentence when both fit. */
export function routerLine(description: string, triggers: string[], max = 160): string {
const first = sentences(description)[0] ?? '';
const own = triggerSentence(description);
const trigger = (triggers.length && own.startsWith('Use for:') ? '' : own) || triggerList(triggers, max);
if (!trigger) return cutWords(first, max);
const both = trigger + ' ' + first;
return first && first !== trigger && both.length <= max ? both : cutWords(trigger, max);
}
/** The values of a YAML block list field (`field:` then ` - value` lines) in a SKILL.md's frontmatter. */
export function frontmatterList(md: string, field: string): string[] {
const fm = md.startsWith('---\n') ? md.slice(4, md.indexOf('\n---', 4)) : '';
const lines = fm.split('\n');
const i = lines.findIndex(l => l.trimEnd() === field + ':');
if (i < 0) return [];
const out: string[] = [];
for (const l of lines.slice(i + 1)) {
const m = /^\s*-\s+(.*)$/.exec(l);
if (!m) break;
out.push(m[1].trim().replace(/^["']|["']$/g, ''));
}
return out;
}