sshlg-skills 1.77.0 → 1.78.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## v1.78.0 (2026-10-24): quiet core skills listed by name only
+
+- **B-254:** `visibility` lists quiet core skills by name only on Claude Code. Measured
+  2026-10-24 on Claude Code 2.1.299: `Skill listing over budget: 132 skills, 61725 chars > 30000
+  budget`; over budget the host keeps bundled skills whole, gives the rest their description
+  most-used first and lists the remainder by name. A personal skill in the core that was not
+  used within 14 days and is not named in `~/.claude/CLAUDE.md` now gets
+  `skillOverrides: "name-only"` (on this machine 22 skills, the launcher's estimate 46,402 to
+  35,853 characters). `--full-days N|off`; ownership of each value is recorded
+  (`claudeNameOnly`), `--revert` removes only values still as written, and `update` re-applies
+  the tier only after an `--apply` that recorded `fullDays`. The listing estimate now counts
+  Claude's `- name: description` form, and the preview prints Claude Code's own last count
+  from its debug logs. `test/visibility_test.js` 22 to 29 checks,
+  `test/visibility_e2e_test.js` 11 to 15. Release impact card:
+  `docs/evidence/specs/2026-10-24-v1780-release-impact.md`.
+- **Context audit, the same request:** B-255 (the listing still over budget: family and foreign
+  plugin descriptions) and B-256 (the 15,410-character routing block in every host file) are
+  open rows with their measurements; oversized project instruction files are tracked in the
+  HANDOFF entry.
+
 ## v1.77.0 (2026-10-24): every release with users carries its impact card
 
 - **Pins:** task-pipeline 1.102.0, the release impact card (operator, 2026-10-24): a release in a

package/README.md

@@ -686,6 +686,17 @@ hides every other installed pack; an existing file is replaced only with `--repl
   so a plugin's skills stay listed (switch a foreign plugin off with `enabledPlugins`).
   The pack marks and the overrides below do not change them; `--keep <skill>` keeps a
   skill listed there.
+- **Claude Code name-only tier** (B-254, since v1.78.0): a personal skill in the core that
+  was not used within 14 days and is not named in `~/.claude/CLAUDE.md` stays listed by name
+  without its description (`skillOverrides: "name-only"`). Claude Code 2.1.299 does the same
+  on its own once the listing is over budget (bundled skills whole, the others' descriptions
+  most-used first, the rest by name), so this picks the quiet ones by the operator's usage
+  instead of the host's order. `--full-days N` sets the window, `--full-days off` turns the
+  tier off. `update` re-applies it only after one `visibility --apply` that recorded
+  `fullDays`; an older record re-applies without it. The preview prints the launcher's
+  estimate of the listing and Claude Code's own last count from its debug logs (the one
+  `Skill listing over budget` line); the estimate leaves out bundled skills, plugin commands
+  and plugins loaded from other roots, so the logged count is the one to trust.
 - **Gemini, Pi, OpenCode and Hermes** hide the skills of marked packs, except the usage
   core. Strongest first: a family pack is never hidden; the usage core is never hidden
   (family skills, skills used in the last 60 days by Claude Code usage, skills
@@ -698,12 +709,13 @@ hides every other installed pack; an existing file is replaced only with `--repl
 npx sshlg-skills config set visibility.pack.anthropics/financial-services show   # or hide, or default
 npx sshlg-skills visibility            # preview: per-host counts, nothing written
 npx sshlg-skills visibility --apply    # write each host's own switch, backups first; records consent
+npx sshlg-skills visibility --apply --full-days off   # Claude: keep every core description
 npx sshlg-skills visibility --revert   # remove exactly what --apply wrote; withdraws consent
 ```
 
 | Host | The switch `visibility` writes | Source | A hidden skill can still |
 |---|---|---|---|
-| Claude Code | `skillOverrides: "user-invocable-only"` in `~/.claude/settings.json`; plugin skills are out of its reach | since v1.55.0; Claude Code settings reference: overrides do not apply to plugin skills | be run from the `/` menu by a person |
+| Claude Code | `skillOverrides: "user-invocable-only"` (hidden) or `"name-only"` (quiet core) in `~/.claude/settings.json`; plugin skills are out of its reach | since v1.55.0; Claude Code settings reference: overrides do not apply to plugin skills | be run from the `/` menu by a person |
 | Codex | `enabled = false` entries in `~/.codex/config.toml` `[skills] config` | since v1.55.0 | be read from its SKILL.md path when asked |
 | Gemini CLI 0.63.0 | `skills.disabled` in `~/.gemini/settings.json`, the list `gemini skills disable <name> --scope user` writes; read back with `gemini skills list` (`[Disabled]`) | `packages/cli/src/utils/skillSettings.ts`; `SkillManager.getSkills()` drops disabled skills | come back with `gemini skills enable <name>` |
 | Pi 1.1.0 | `-<path>` exact exclusions in the `skills` array of `~/.pi/agent/settings.json`, one per folder holding the skill (`~/.agents/skills`, `~/.pi/agent/skills`); the file is created if absent and removed again by `--revert` | Pi's own docs, settings → Resources; `isEnabledByOverrides` in its `dist/core/package-manager.js` | be loaded for one session with `pi --skill <path>` |

package/bin/sshlg-skills.js

@@ -314,8 +314,9 @@ Usage:
                                                       # report header + footer, links looked up
   npx sshlg-skills toolkit [--for "<task>"] [--find "<concept>, …"] [--expand <provider>]
                                                       # every skill this machine can reach
-  npx sshlg-skills visibility [--apply | --revert] [--days 60] [--keep a,b]
+  npx sshlg-skills visibility [--apply | --revert] [--days 60] [--full-days 14|off] [--keep a,b]
                                                       # Claude/Codex: hide all outside the core;
+                                                      # Claude: quiet core skills name-only;
                                                       # Gemini/Pi/OpenCode/Hermes: hide marked
                                                       # packs; Cursor/Kimi: cannot hide
   npx sshlg-skills visibility marks [--init --show <owner/repo,…> [--replace] [--apply]]
@@ -773,6 +774,9 @@ function reapplyVisibility(f) {
   log(`\n== Skill visibility (re-applied: this machine ran \`visibility --apply\`; hosts: ${[...only].join(', ')}) ==`);
   return runVisibility({
     mode: 'apply', days: Number(rec.days) || undefined, keep: Array.isArray(rec.keep) ? rec.keep : [], only, reapply: true,
+    // A record from before the name-only tier carries no fullDays: re-apply keeps the old
+    // behaviour until the operator runs `visibility --apply` once (B-254, explicit consent).
+    fullDays: typeof rec.fullDays === 'number' ? rec.fullDays : null,
   }) === 0;
 }
 
@@ -2139,9 +2143,19 @@ function cmdVisibility(argv) {
     mode: flag('--revert') ? 'revert' : flag('--apply') ? 'apply' : 'preview',
     days: Number(value('--days')) || V.DEFAULT_DAYS,
     keep: (value('--keep') || '').split(',').map((s) => s.trim()).filter(Boolean),
+    fullDays: fullDaysArg(value('--full-days'), V.DEFAULT_FULL_DAYS),
   });
 }
 
+/** `--full-days N` (a whole number of days), `--full-days off` (no name-only tier), or the default. */
+function fullDaysArg(raw, dflt) {
+  if (raw === null) return dflt;
+  if (raw === 'off') return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) { log(`visibility: --full-days takes a whole number of days or "off", got "${raw}"; using ${dflt}`); return dflt; }
+  return n;
+}
+
 /**
  * The work of `visibility`, callable from `update` (which re-applies it on a machine whose
  * record shows the operator ran `--apply`). `opts.only` limits the run to a set of host
@@ -2163,6 +2177,29 @@ function runVisibility(opts) {
   finally { lock.release(home, got.token); }
 }
 
+/**
+ * Claude Code's own last listing count, read from its debug logs (newest first). Only the
+ * one warning line is parsed; nothing else in a log is read into the output.
+ */
+function lastListingMeasure(claudeRoot) {
+  const dir = path.join(claudeRoot, 'debug');
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((n) => n.endsWith('.txt'))
+      .map((n) => ({ n, m: fs.statSync(path.join(dir, n)).mtimeMs })).sort((a, b) => b.m - a.m).slice(0, 40);
+  } catch (e) { return null; }
+  const re = /^(\S+) \[WARN\] Skill listing over budget: (\d+) skills, (\d+) chars > (\d+) budget/m;
+  for (const f of files) {
+    let text;
+    try { text = fs.readFileSync(path.join(dir, f.n), 'utf8'); } catch (e) { continue; }
+    const all = text.match(new RegExp(re.source, 'gm'));
+    if (!all) continue;
+    const m = re.exec(all[all.length - 1]);
+    return { at: m[1], skills: Number(m[2]), chars: Number(m[3]), budget: Number(m[4]) };
+  }
+  return null;
+}
+
 function runVisibilityUnlocked(opts) {
   const V = require(path.join(ROOT, 'lib', 'visibility.js'));
   const HV = require(path.join(ROOT, 'lib', 'hostvis.js'));
@@ -2179,6 +2216,8 @@ function runVisibilityUnlocked(opts) {
   const doRevert = opts.mode === 'revert';
   const days = opts.days || V.DEFAULT_DAYS;
   const keep = opts.keep || [];
+  // null: no name-only tier (a re-apply of a record that predates it, or `--full-days off`).
+  const fullDays = typeof opts.fullDays === 'number' ? opts.fullDays : null;
   const inScope = (id) => !opts.only || opts.only.has(id);
 
   const recordPath = path.join(home, '.sshlg-skills', 'visibility.json');
@@ -2226,11 +2265,24 @@ function runVisibilityUnlocked(opts) {
   try { settingsData = JSON.parse(settingsText || '{}'); } catch (e) { settingsData = {}; }
   const overrides = settingsData.skillOverrides || {};
   const mine = new Set(owned.claude.filter((n) => overrides[n] === V.HIDE));
+  const ownedNameOnly = Array.isArray(owned.claudeNameOnly) ? owned.claudeNameOnly : [];
+  const mineNameOnly = new Set(ownedNameOnly.filter((n) => overrides[n] === V.NAME_ONLY));
   const foreign = {};
-  for (const [k, v] of Object.entries(overrides)) if (!mine.has(k)) foreign[k] = v;
-  const plan = doRevert ? { hide: [], respected: [] } : V.claudePlan({ personal, core: coreSet, overrides: foreign, keep });
-  const claudeSet = plan.hide.filter((n) => !mine.has(n));
-  const claudeUnset = [...mine].filter((n) => !plan.hide.includes(n));
+  for (const [k, v] of Object.entries(overrides)) if (!mine.has(k) && !mineNameOnly.has(k)) foreign[k] = v;
+  const full = doRevert || fullDays === null ? null
+    : V.fullSet({ personal, usage, now, fullDays, instructions });
+  const plan = doRevert ? { hide: [], nameOnly: [], respected: [] }
+    : V.claudePlan({ personal, core: coreSet, full, overrides: foreign, keep });
+  // Values this run writes, and values it removes (only while they still hold what it wrote).
+  const claudeSetMap = {};
+  for (const n of plan.hide) if (overrides[n] !== V.HIDE) claudeSetMap[n] = V.HIDE;
+  for (const n of plan.nameOnly) if (overrides[n] !== V.NAME_ONLY) claudeSetMap[n] = V.NAME_ONLY;
+  const planned = new Set(plan.hide.concat(plan.nameOnly));
+  const claudeUnsetMap = {};
+  for (const n of mine) if (!planned.has(n)) claudeUnsetMap[n] = V.HIDE;
+  for (const n of mineNameOnly) if (!planned.has(n)) claudeUnsetMap[n] = V.NAME_ONLY;
+  const claudeSet = Object.keys(claudeSetMap);
+  const claudeUnset = Object.keys(claudeUnsetMap);
   const stateOf = (s, ov) => {
     if (s.loaded === false) return 'hidden';  // installed, not loaded here (B-185): not in the listing
     if (s.namespace !== 'claude:plain') return 'on';
@@ -2239,7 +2291,7 @@ function runVisibilityUnlocked(opts) {
     return v === 'name-only' ? 'name-only' : 'on';
   };
   const after = Object.assign({}, overrides);
-  for (const n of claudeSet) after[n] = V.HIDE;
+  for (const n of claudeSet) after[n] = claudeSetMap[n];
   for (const n of claudeUnset) delete after[n];
   const charsBefore = V.listingChars(skills.map((s) => ({ name: s.plugin && s.namespace === 'claude:plugin' ? `${s.plugin.split('@')[0]}:${s.id}` : s.id, description: s.description, state: stateOf(s, overrides) })));
   const charsAfter = V.listingChars(skills.map((s) => ({ name: s.plugin && s.namespace === 'claude:plugin' ? `${s.plugin.split('@')[0]}:${s.id}` : s.id, description: s.description, state: stateOf(s, after) })));
@@ -2336,11 +2388,21 @@ function runVisibilityUnlocked(opts) {
     log(`  overrides (config.json): hidePacks ${(ov.hidePacks || []).length}, showPacks ${(ov.showPacks || []).length} — Gemini, Pi, OpenCode and Hermes only`);
   }
   if (inScope('claude')) {
-    log(`  Claude: ${personal.length} personal skills; hide ${claudeSet.length} more, un-hide ${claudeUnset.length}; ` +
+    const newHides = claudeSet.filter((n) => claudeSetMap[n] === V.HIDE).length;
+    log(`  Claude: ${personal.length} personal skills; hide ${newHides} more, name-only ${claudeSet.length - newHides} more, restore ${claudeUnset.length}; ` +
         `${Object.keys(foreign).length} operator-set override(s) left alone`);
-    log(`  Claude listing ≈ ${charsBefore} → ${charsAfter} characters (names + descriptions, 1536 cap each).`);
-    log('    Budget: Claude Code logs it — `claude -p x --debug` then look for "Skill listing over budget"');
-    log('    (30000 characters measured on 2026-10-10). Over budget, descriptions drop least-used first.');
+    log(fullDays === null
+      ? '    name-only tier: off (`--full-days N` turns it on: core skills unused for N days keep their name, lose their description)'
+      : `    name-only tier: core skills not used within ${fullDays} days and not named in the instructions are listed by name only (${plan.nameOnly.length})`);
+    log(`  Claude listing, launcher's estimate ≈ ${charsBefore} → ${charsAfter} characters`);
+    log('    (personal and registered plugin skills in Claude\'s `- name: description` form; bundled skills,');
+    log('    plugin commands and plugins loaded from other roots are not counted).');
+    const measured = lastListingMeasure(claudeRoot);
+    log(measured
+      ? `    Claude Code's own count (debug log ${measured.at}): ${measured.skills} entries, ${measured.chars} characters > ${measured.budget} budget.`
+      : '    Claude Code\'s own count: none logged yet. `claude -p x --debug`, then look for "Skill listing over budget".');
+    log('    Over budget, Claude Code 2.1.299 keeps bundled skills whole, gives the others their description');
+    log('    most-used first and lists the rest by name only.');
   }
   if (inScope('codex')) {
     log(`  Codex: ${shared.length} shared skills; disable up to ${codexAdd.length} more (entries already present are left as they are), re-enable ${codexDrop.length}` +
@@ -2404,7 +2466,7 @@ function runVisibilityUnlocked(opts) {
   const degraded = [];
   let record = Object.assign({}, owned, {
     note: 'Written by `npx sshlg-skills visibility`; --revert removes these entries. Pending holds a write-ahead receipt; applied is consent for update on hosts only.',
-    days, keep, marksRevision: marksData && !markProblems.length ? marksData.revision : null,
+    days, keep, fullDays, marksRevision: marksData && !markProblems.length ? marksData.revision : null,
     updatedAt: new Date().toISOString(), created: Object.assign({}, owned.created || {}),
     files: Object.assign({}, owned.files || {}, Object.fromEntries(Object.entries(files).filter(([id]) => inScope(id)))),
   });
@@ -2442,13 +2504,14 @@ function runVisibilityUnlocked(opts) {
       if (id === 'claude') {
         if (claudeSet.length && !('skillOverrides' in settingsData)) next.created.claude = ['skillOverrides'];
         if (doRevert) delete next.created.claude;
+        next.claudeNameOnly = plan.nameOnly.slice().sort();
       }
       if (r.text === before) { journal.save(next); log(`  ${id}: already as planned`); return; }
       transact(id, file, before, r.text, next, () => S.write(file, r.text, home));
     };
     const claudeCreated = createdOf('claude').includes('skillOverrides') || !Object.prototype.hasOwnProperty.call(owned, 'applied');
     writeSimple('claude', settingsPath, settingsText,
-      (t) => V.editClaudeSettings(t, { set: claudeSet, unset: claudeUnset, prune: claudeCreated }), () => plan.hide.slice().sort());
+      (t) => V.editClaudeSettings(t, { set: claudeSetMap, unset: claudeUnsetMap, prune: claudeCreated }), () => plan.hide.slice().sort());
     writeSimple('codex', codexPath, codexText,
       (t) => V.editCodexConfig(t, { disable: codexAdd, enable: codexDrop }),
       (r) => [...new Set(owned.codex.filter((p) => codexWant.includes(p)).concat(r.added || []))].sort());

package/lib/visibility-state.js

@@ -39,6 +39,8 @@ function validate(r) {
   if (!r || typeof r !== 'object' || Array.isArray(r)) throw new Error('visibility record is not an object');
   for (const h of HOSTS) if (r[h] !== undefined && (!Array.isArray(r[h]) || r[h].some((x) => typeof x !== 'string')))
     throw new Error(`visibility record ${h} is not a list of strings`);
+  if (r.claudeNameOnly !== undefined && (!Array.isArray(r.claudeNameOnly) || r.claudeNameOnly.some((x) => typeof x !== 'string')))
+    throw new Error('visibility record claudeNameOnly is not a list of strings');
   if (r.files !== undefined && (!r.files || typeof r.files !== 'object' || Array.isArray(r.files)
     || Object.entries(r.files).some(([h, f]) => !HOSTS.includes(h) || typeof f !== 'string' || !path.isAbsolute(f))))
     throw new Error('visibility record files is not a host-to-absolute-path map');

package/lib/visibility.js

@@ -23,8 +23,15 @@
  */
 
 const HIDE = 'user-invocable-only';
+const NAME_ONLY = 'name-only';
 const DESC_CAP = 1536;
 const DEFAULT_DAYS = 60;
+// B-254. Measured 2026-10-24: Claude Code 2.1.299 logged `Skill listing over budget:
+// 132 skills, 61725 chars > 30000 budget`. Over budget it keeps bundled skills whole and
+// gives the rest their description most-used first; the remainder are listed by name
+// only. So a quiet core skill loses its description anyway. Within the core, only what
+// was used within DEFAULT_FULL_DAYS or is named in the instructions keeps it.
+const DEFAULT_FULL_DAYS = 14;
 
 /** Skill names the instruction text references deliberately: inside backticks. */
 function namedIn(text, names) {
@@ -53,16 +60,39 @@ function core({ personal, family, usage, now, days, instructions }) {
   return set;
 }
 
-function claudePlan({ personal, core: coreSet, overrides, keep }) {
+/**
+ * The core members that keep their description: used within `fullDays`, or named in
+ * the instructions (an agent told to use a skill by name is already told when).
+ */
+function fullSet({ personal, usage, now, fullDays, instructions }) {
+  const window = (fullDays == null ? DEFAULT_FULL_DAYS : fullDays) * 86400e3;
+  const set = new Set();
+  for (const n of personal || []) {
+    const u = (usage || {})[n];
+    if (u && typeof u.lastUsedAt === 'number' && now - u.lastUsedAt <= window) set.add(n);
+  }
+  for (const n of namedIn(instructions, personal)) set.add(n);
+  return set;
+}
+
+/**
+ * `hide`: outside the core. `nameOnly`: in the core but outside `full`, so listed by name
+ * without its description. Without `full` nothing goes name-only. A key the operator set
+ * is never planned over, in either list.
+ */
+function claudePlan({ personal, core: coreSet, full, overrides, keep }) {
   const kept = new Set(keep || []);
   const hide = [];
+  const nameOnly = [];
   const respected = [];
   for (const n of personal || []) {
-    if (coreSet.has(n) || kept.has(n)) continue;
+    if (kept.has(n)) continue;
+    const inCore = coreSet.has(n);
+    if (inCore && (!full || full.has(n))) continue;
     if (overrides && Object.prototype.hasOwnProperty.call(overrides, n)) { respected.push(n); continue; }
-    hide.push(n);
+    (inCore ? nameOnly : hide).push(n);
   }
-  return { hide: hide.sort(), respected: respected.sort() };
+  return { hide: hide.sort(), nameOnly: nameOnly.sort(), respected: respected.sort() };
 }
 
 /**
@@ -77,12 +107,19 @@ function editClaudeSettings(text, { set, unset, prune }) {
   if (JSON.stringify(data, null, 2) + '\n' !== text) {
     return { ok: false, reason: 'settings.json is not in the 2-space JSON format Claude Code writes; refusing to reformat it' };
   }
+  // `set` and `unset` map a name to its value; a bare list means the hidden value, the
+  // form callers used before the name-only tier. `unset` removes a key only while it
+  // still holds the value the launcher wrote.
+  const asMap = (x) => (Array.isArray(x) ? Object.fromEntries(x.map((n) => [n, HIDE])) : (x || {}));
+  const setMap = asMap(set);
+  const unsetMap = asMap(unset);
   const ov = Object.assign({}, data.skillOverrides || {});
   let changed = false;
-  for (const n of set || []) if (ov[n] !== HIDE) { ov[n] = HIDE; changed = true; }
+  for (const [n, v] of Object.entries(setMap)) if (ov[n] !== v) { ov[n] = v; changed = true; }
   const kept = [];
-  for (const n of unset || []) {
-    if (ov[n] === HIDE) { delete ov[n]; changed = true; }
+  for (const [n, v] of Object.entries(unsetMap)) {
+    if (Object.prototype.hasOwnProperty.call(setMap, n)) continue;
+    if (ov[n] === v) { delete ov[n]; changed = true; }
     else if (n in ov) kept.push(n);
   }
   // Nothing to do leaves the file exactly as it was — including an empty map the
@@ -177,15 +214,21 @@ function editCodexConfig(text, { disable, enable }) {
   return { ok: true, text: lines.join('\n'), added };
 }
 
-/** Characters a listing spends: a listed name, plus its description while `on`. */
+/**
+ * Characters a listing spends, in the form Claude Code 2.1.299 prints it: `- name: description`
+ * while `on` (description capped at 1536), `- name` when name-only, one newline between
+ * entries; hidden costs nothing.
+ */
 function listingChars(rows) {
   let n = 0;
+  let entries = 0;
   for (const r of rows || []) {
     if (r.state === 'hidden') continue;
-    n += String(r.name).length;
-    if (r.state === 'on') n += Math.min(DESC_CAP, String(r.description || '').length);
+    entries += 1;
+    n += 2 + String(r.name).length;
+    if (r.state === 'on') n += 2 + Math.min(DESC_CAP, String(r.description || '').length);
   }
-  return n;
+  return entries ? n + entries - 1 : 0;
 }
 
 // ── Packs: the operator's marks (pack-marks.json) and per-machine overrides ──
@@ -453,7 +496,8 @@ function jsonAt(text, keys) {
 }
 
 module.exports = {
-  core, claudePlan, editClaudeSettings, editCodexConfig, listingChars, namedIn, HIDE, DEFAULT_DAYS,
+  core, fullSet, claudePlan, editClaudeSettings, editCodexConfig, listingChars, namedIn,
+  HIDE, NAME_ONLY, DEFAULT_DAYS, DEFAULT_FULL_DAYS,
   MARKS_SCHEMA, marksProblems, marksIndex, marksFromLock, packHidden, hostHide, setPackOverride,
   editJsonList, editJsonMap, jsonAt,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sshlg-skills",
-  "version": "1.77.0",
+  "version": "1.78.0",
   "skillsCli": "skills@1.7.2",
   "description": "The ssheleg harness skill layer: routing, delivery gates, specialist skills and durable handoffs for coding agents.",
   "bin": {