config-audit/scanners/skill-listing-scanner.mjs

/**
 * SKL Scanner — Skill-listing token budget
 *
 * Claude Code shows the model a listing of every active skill's `description`
 * so it can decide which skill to invoke. That listing is budgeted: each
 * description is capped, and anything past the cap is silently truncated
 * (Claude Code raised the per-description cap 250 → 1,536 chars in v2.1.105,
 * changelog L1502, and added a startup/`/doctor` notice when truncation
 * happens). A description past the cap loses its tail from what the model
 * actually sees — the very trigger phrases meant to route invocation.
 *
 * Detection (v1, high confidence — no estimation):
 *   CA-SKL-001  active skill description > 1,536 chars → truncated (medium)
 *
 * The aggregate listing budget (skill descriptions sum vs ~2% of the context
 * window, v2.1.32 L2860) is deliberately NOT scanned in v1: it requires
 * assuming the user's context-window size, which would turn a verified fact
 * into a guess. Lead with the cap; the aggregate check is a possible later
 * addition (would carry a CALIBRATION_NOTE).
 *
 * Two-lens note vs TOK pattern F: TOK pattern F flags *project-local* skills
 * with descriptions > 500 chars as a structural per-turn "bloat" heuristic.
 * SKL is a different lens — it scans ALL active skills (user + plugin) against
 * the *verified* 1,536-char hard truncation cap, not a bloat heuristic. The
 * two are intentionally distinct, not duplicates.
 *
 * Zero external dependencies.
 */

import { finding, scannerResult } from './lib/output.mjs';
import { SEVERITY } from './lib/severity.mjs';
import { enumeratePlugins, enumerateSkills } from './lib/active-config-reader.mjs';
import { readTextFile } from './lib/file-discovery.mjs';
import { parseFrontmatter } from './lib/yaml-parser.mjs';

const SCANNER = 'SKL';

// Verified per-description skill-listing cap (CC 2.1.105, changelog L1502).
// Descriptions longer than this are truncated in the listing the model sees.
const DESCRIPTION_CAP = 1536;

/**
 * Main scanner entry point.
 *
 * @param {string} _targetPath unused (skill listing is HOME-scoped)
 * @param {object} _discovery unused (ignores project discovery)
 */
export async function scan(_targetPath, _discovery) {
  const start = Date.now();
  const findings = [];

  const plugins = await enumeratePlugins();
  const allSkills = await enumerateSkills(plugins);

  let scanned = 0;
  for (const skill of allSkills) {
    if (!skill || typeof skill.path !== 'string') continue;
    const content = await readTextFile(skill.path);
    if (!content) continue;
    scanned++;
    const fm = parseFrontmatter(content)?.frontmatter || null;
    const desc = (fm && typeof fm.description === 'string') ? fm.description : '';
    if (desc.length <= DESCRIPTION_CAP) continue;

    const sourceLabel = skill.source === 'plugin'
      ? `plugin:${skill.pluginName}`
      : 'user';

    findings.push(finding({
      scanner: SCANNER,
      severity: SEVERITY.medium,
      title: 'Skill description exceeds the listing cap (Claude Code truncates it)',
      description:
        `Skill "${skill.name}" (${sourceLabel}) has a description of ${desc.length} ` +
        `characters (>${DESCRIPTION_CAP}). Claude Code caps each skill description in ` +
        'the listing the model reads to choose a skill, so everything past ' +
        `${DESCRIPTION_CAP} characters is silently dropped — including any trigger ` +
        'phrases at the tail meant to route invocation.',
      file: skill.path,
      evidence:
        `description_chars=${desc.length}; cap=${DESCRIPTION_CAP}; ` +
        `skill="${skill.name}"; source=${sourceLabel}`,
      recommendation:
        `Trim the description below ${DESCRIPTION_CAP} characters, leading with the ` +
        'trigger phrases. To reclaim listing budget more broadly: set ' +
        '`disableBundledSkills: true` to drop bundled skills you do not use from the ' +
        'listing entirely, or use `skillOverrides` (`name-only` collapses a ' +
        'description, `off` removes a skill) on the heaviest entries.',
      category: 'token-efficiency',
    }));
  }

  return scannerResult(SCANNER, 'ok', findings, scanned, Date.now() - start);
}