Function applyCatalogTrim

scripts/gen-skill-docs.ts:426–479

(content: string, skillName: string)

 * JSON aggregation at the end of the run).
 */
export function applyCatalogTrim(content: string, skillName: string): { content: string; parts: CatalogParts } | null {
  // Locate description block in frontmatter
  if (!content.startsWith('---\n')) return null;
  const fmEnd = content.indexOf('\n---', 4);
  if (fmEnd === -1) return null;
  const frontmatter = content.slice(4, fmEnd);

  // Match `description: |` block + indented body lines
  const descMatch = frontmatter.match(/^description:\s*\|?\s*\n((?:\s{2,}.*(?:\n|$))+)/m)
                    || frontmatter.match(/^description:\s+(.+)$/m);
  if (!descMatch) return null;

  // Extract full description text
  let descText: string;
  if (descMatch[0].startsWith('description: |') || /^description:\s*\|/.test(descMatch[0])) {
    descText = descMatch[1].split('\n').map(l => l.replace(/^\s{2}/, '')).join('\n').trim();
  } else {
    descText = descMatch[1].trim();
  }

  // Skip skills with very short descriptions (already trimmed or no routing prose).
  // Below ~120 chars, splitting adds no value.
  if (descText.length < 120) return null;

  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;

  // Replace description in frontmatter — keep trailing newline so the next
  // YAML field doesn't collide on the same line as the description value.
  // Quote the value when it would be an invalid YAML plain scalar (the common
  // 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.
  const newDescLine = `description: ${toYamlInlineScalar(newDesc)}\n`;
  const newFrontmatter = frontmatter.replace(descMatch[0], () => newDescLine);
  let newContent = '---\n' + newFrontmatter + content.slice(fmEnd);

  // Insert body section after frontmatter (after the closing ---\n and any
  // existing GENERATED header). We insert before the first non-comment line.
  const bodyStart = newContent.indexOf('\n---\n') + 5;
  const whenToInvoke = '\n' + buildWhenToInvokeSection(parts).trim() + '\n';
  // Skip past the generated header if present (it lives after frontmatter close)
  const headerMatch = newContent.slice(bodyStart).match(/^(<!--[^>]*-->\s*\n)+/);
  const insertAt = bodyStart + (headerMatch ? headerMatch[0].length : 0);
  newContent = newContent.slice(0, insertAt) + whenToInvoke + '\n' + newContent.slice(insertAt);

  return { content: newContent, parts };
}

const OPENAI_SHORT_DESCRIPTION_LIMIT = 120;