@joenandez/academy 0.4.0 → 0.5.12

package/scripts/cli/scaffold.mjs

@@ -1,53 +1,82 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import {
   ACADEMY_ROOT,
   ACADEMY_SYSTEM_PROMPT,
-  SURFACES,
-  UNIVERSAL_SKILLS,
+  KIND_PROFILES,
   ensureAcademyGitignore,
   ensureSymlink,
-  memoryBridgeEnabled,
+  kindOf,
   projectPluginDir,
+  surfacesFor,
 } from './core.mjs';
+import { ownerYamlBlock } from './owner-config.mjs';
+import { renderPackageSkills, renderTemplate, universalSkillValues } from './skills.mjs';
 import { TEMPLATES } from './templates.mjs';
-import {
-  MEMORY_BRIDGE_PERMISSIONS,
-  MEMORY_BRIDGE_SKILL_GUIDANCE,
-} from '../../hooks/memory_bridge.mjs';
-
-export function scaffoldBootFiles(dir, name) {
-  const today = new Date().toISOString().slice(0, 10);
-  for (const surface of SURFACES) {
-    const filename = `${surface}.md`;
-    const path = join(dir, filename);
-    if (existsSync(path)) continue;
-    writeFileSync(path, TEMPLATES[filename](name, today));
+import { filterUserWork } from './user-work-view.mjs';
+import { tokenRecord } from '../../hooks/context_metrics.mjs';
+import { MEMORY_BRIDGE_PERMISSIONS } from '../../hooks/memory_bridge.mjs';
+
+export function scaffoldBootFiles(dir, name, today = new Date().toISOString().slice(0, 10)) {
+  // Only surfaces with a scaffold template are written, and never over an
+  // existing file: the shared ACADEMY_HOME surfaces belong to the user once
+  // they exist. The `wx` flag closes the gap between the check and the write,
+  // so a racing create or `academy notes add --user` is never overwritten.
+  const kind = kindOf(dir);
+  for (const { name: surface, path } of surfacesFor(dir)) {
+    const template = bootTemplate(kind, surface);
+    if (!template || existsSync(path)) continue;
+    mkdirSync(dirname(path), { recursive: true });
+    writeSeedOnce(path, template(name, today));
   }
   return today;
 }
 
-export function writeAgentYaml(dir, name, today) {
+function writeSeedOnce(path, text) {
+  try {
+    writeFileSync(path, text, { flag: 'wx' });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+}
+
+// Agents created before local rules get the empty file on their next run. An
+// existing file holds the user's rules and is never rewritten.
+export function scaffoldLocalRules(dir, name) {
+  const path = join(dir, 'local-rules.md');
+  if (existsSync(path)) return;
+  writeFileSync(path, TEMPLATES['local-rules.md'](name, new Date().toISOString().slice(0, 10)));
+}
+
+// A kind's pack may supply a surface's first content (a Principal's craft.md).
+// It is a seed: written at create, then the agent's own, never re-rendered.
+function bootTemplate(kind, surface) {
+  const packTemplate = join(ACADEMY_ROOT, 'templates', 'packs', kind, `${surface}.md`);
+  if (!existsSync(packTemplate)) return TEMPLATES[`${surface}.md`];
+  const template = readFileSync(packTemplate, 'utf8');
+  return (name, today) => renderTemplate(template, { agent_name: name, created: today });
+}
+
+export function writeAgentYaml(dir, name, today, kind = 'specialist') {
+  const { surfaces } = KIND_PROFILES[kind];
+  const totalCap = surfaces.reduce((sum, { cap }) => sum + cap, 0).toLocaleString('en-US');
+  const surfaceList = surfaces.map(({ name: surface }) => `  - ${surface}.md`).join('\n');
   const yaml = `# Agent metadata. Hand-edit role and objective once the hire flow runs.
 name: ${name}
 created: ${today}
 # Launch runtime — claude_code or codex. \`academy run --agent\` rewrites it.
 runtime: claude_code
-role: ""
+# Agent kind — specialist, principal or owner. Selects its surfaces and skills.
+kind: ${kind}
+${kind === 'owner' ? ownerYamlBlock() : ''}role: ""
 objective: ""
 
-# Boot context — 8 surfaces, ~5–6k tokens combined (see scope §3).
-# Files live alongside this yaml; academy run compiles them into the generated
-# .academy/generated/${ACADEMY_SYSTEM_PROMPT} before launching an agent runtime.
+# Boot context — the ${kind} surfaces, capped at ${totalCap} estimated tokens combined.
+# Agent files live alongside this yaml, shared ones under ACADEMY_HOME; academy run
+# compiles them into the generated .academy/generated/${ACADEMY_SYSTEM_PROMPT}
+# before launching an agent runtime.
 surfaces:
-  - identity.md
-  - role.md
-  - knowledge.md
-  - goals.md
-  - priorities.md
-  - threads.md
-  - notes.md
-  - dailys.md
+${surfaceList}
 `;
   writeFileSync(join(dir, 'agent.yaml'), yaml);
 }
@@ -57,10 +86,9 @@ export function writeAgentClaudeMd(dir, name) {
   // user instructions channel can grow over time but starts effectively empty.
   const md = `# ${name}
 
-User instructions for this agent. The 8 boot surfaces (\`identity.md\`,
-\`role.md\`, \`knowledge.md\`, \`goals.md\`, \`priorities.md\`, \`threads.md\`,
-\`notes.md\`, \`dailys.md\`) are compiled into \`.academy/generated/${ACADEMY_SYSTEM_PROMPT}\`
-when \`academy run ${name}\` launches an agent runtime.
+User instructions for this agent. The boot surfaces listed in \`agent.yaml\` are
+compiled into \`.academy/generated/${ACADEMY_SYSTEM_PROMPT}\` when
+\`academy run ${name}\` launches an agent runtime.
 
 Add user-driven instructions below as they come up.
 `;
@@ -129,7 +157,7 @@ export function writeProjectCodexSkillBridge(projectDir, dir) {
   const projectSkillsDir = join(projectDir, '.agents', 'skills');
   mkdirSync(projectSkillsDir, { recursive: true });
 
-  for (const skillName of UNIVERSAL_SKILLS) {
+  for (const skillName of KIND_PROFILES[kindOf(dir)].skills) {
     const source = join(agentSkillsDir, skillName);
     const target = join(projectSkillsDir, skillName);
     if (!existsSync(source) || existsSync(target)) continue;
@@ -137,68 +165,17 @@ export function writeProjectCodexSkillBridge(projectDir, dir) {
   }
 }
 
-function renderTemplate(template, values) {
-  const rendered = template.replace(/\{\{([a-z_]+)\}\}/g, (match, key) => {
-    if (!(key in values)) throw new Error(`Unknown template variable: ${match}`);
-    return values[key];
-  });
-  // An optional section that renders empty must not leave a hole in a surface
-  // Academy charges a token budget for.
-  return rendered.replace(/\n{3,}/g, '\n\n');
-}
-
-function universalSkillValues(dir, name, skillsDir) {
-  const dreamsDir = join(dir, 'dreams');
-  return {
-    agent_name: name,
-    agent_dir: dir,
-    identity_path: join(dir, 'identity.md'),
-    role_path: join(dir, 'role.md'),
-    knowledge_path: join(dir, 'knowledge.md'),
-    goals_path: join(dir, 'goals.md'),
-    priorities_path: join(dir, 'priorities.md'),
-    threads_path: join(dir, 'threads.md'),
-    notes_path: join(dir, 'notes.md'),
-    dailys_path: join(dir, 'dailys.md'),
-    memory_observations_path: join(dir, 'memory', 'observations'),
-    memory_bridge_guidance: memoryBridgeEnabled() ? MEMORY_BRIDGE_SKILL_GUIDANCE : '',
-    dreams_dir: dreamsDir,
-    skills_surface: skillsDir.endsWith(join('.agents', 'skills'))
-      ? '.agents/skills'
-      : '.claude/skills',
-    skills_dir: skillsDir,
-    check_in_path: join(skillsDir, 'check-in', 'SKILL.md'),
-    self_update_path: join(skillsDir, 'self-update', 'SKILL.md'),
-    nightly_consolidation_path: join(skillsDir, 'nightly-consolidation', 'SKILL.md'),
-    knowledge_curation_path: join(skillsDir, 'knowledge-curation', 'SKILL.md'),
-  };
-}
-
-function writeUniversalSkill(dir, name, skillName, skillsDir) {
-  const skillDir = join(skillsDir, skillName);
-  const templatePath = join(ACADEMY_ROOT, 'templates', 'skills', skillName, 'SKILL.md');
-  const template = readFileSync(templatePath, 'utf8');
-
-  mkdirSync(skillDir, { recursive: true });
-  writeFileSync(
-    join(skillDir, 'SKILL.md'),
-    renderTemplate(template, universalSkillValues(dir, name, skillsDir)),
-  );
-}
-
 export function writeSkillsScaffold(dir, name) {
-  // Universal Academy skills are copied into each agent with agent-specific
-  // paths. Agent/domain skills can be added later by hire or self-update.
+  // The kind's package skills are rendered into each agent with agent-specific
+  // paths. Agent/domain skills can be added later by hire or the skill-method skill.
   writeDreamsDir(dir);
   writeMemoryScaffold(dir);
-  for (const skillsDir of [join(dir, '.claude', 'skills'), join(dir, '.agents', 'skills')]) {
-    mkdirSync(skillsDir, { recursive: true });
-    for (const skillName of UNIVERSAL_SKILLS) writeUniversalSkill(dir, name, skillName, skillsDir);
-  }
-  writeKnowledgeCuratorAgents(dir, name);
+  const kind = kindOf(dir);
+  renderPackageSkills(dir, name, { kind, skills: KIND_PROFILES[kind].skills });
+  writeKnowledgeCuratorAgents(dir, name, kind);
 }
 
-function writeKnowledgeCuratorAgents(dir, name) {
+function writeKnowledgeCuratorAgents(dir, name, kind) {
   const definitions = [
     {
       source: join(ACADEMY_ROOT, 'templates', 'agents', 'claude-code', 'knowledge-curator.md'),
@@ -212,11 +189,21 @@ function writeKnowledgeCuratorAgents(dir, name) {
     },
   ];
 
+  // The curator exists to run the knowledge-curation skill. A kind without that
+  // skill has no curator, and one left from an earlier kind is removed.
+  const curates = KIND_PROFILES[kind].skills.includes('knowledge-curation');
   for (const { source, target, skillsDir } of definitions) {
+    if (!curates) {
+      rmSync(target, { force: true });
+      continue;
+    }
     mkdirSync(dirname(target), { recursive: true });
     writeFileSync(
       target,
-      renderTemplate(readFileSync(source, 'utf8'), universalSkillValues(dir, name, skillsDir)),
+      renderTemplate(
+        readFileSync(source, 'utf8'),
+        universalSkillValues(dir, name, skillsDir, kind),
+      ),
     );
   }
 }
@@ -225,41 +212,50 @@ export function academySystemPromptPath(dir) {
   return join(dir, '.academy', 'generated', ACADEMY_SYSTEM_PROMPT);
 }
 
+export { userWorkView } from './user-work-view.mjs';
+
 function surfaceTitle(surface) {
   return `${surface[0].toUpperCase()}${surface.slice(1)}`;
 }
 
-function readSurface(dir, surface) {
-  const surfaceFile = join(dir, `${surface}.md`);
+function readSurface(surface, surfaceFile) {
   if (!existsSync(surfaceFile))
     return `# ${surfaceTitle(surface)}\n\n_(No ${surface}.md present yet.)_`;
   const body = readFileSync(surfaceFile, 'utf8').trimEnd();
   return body || `# ${surfaceTitle(surface)}\n\n_(${surface}.md is empty.)_`;
 }
 
+// The operating model is package-owned text, not an agent file: one base for
+// every agent and one section for its kind, rendered with the same values the
+// skills read. It opens the prompt so the harness can cache it.
+function operatingModel(dir, name, kind) {
+  const values = universalSkillValues(dir, name, join(dir, '.claude', 'skills'), kind);
+  return ['base', kind].map((part) =>
+    renderTemplate(
+      readFileSync(join(ACADEMY_ROOT, 'templates', 'operating-model', `${part}.md`), 'utf8'),
+      values,
+    ).trimEnd(),
+  );
+}
+
 export function buildAcademySystemPrompt(dir, name) {
   const intro = [
     '<!-- Generated by `academy`. Do not edit this file directly. Edit the source surfaces instead. -->',
     '',
-    `# Academy Agent: ${name}`,
-    '',
-    'You are an Academy v3 agent. Treat the following surfaces as your durable identity, role, knowledge, goals, priorities, active threads, notes, and recent daily context.',
-    '',
-    'Capture transient steering cheaply with `academy notes add "..."` — it appends a timestamped bullet to your notes.md without reading the whole file. Use it for corrections, stakeholder facts, caveats, and raw learnings before they are durable enough for another surface; review with `academy notes list`. The self-update skill explains when a note should graduate or expire.',
-    '',
+    ...operatingModel(dir, name, kindOf(dir)).flatMap((part) => [part, '']),
   ];
-  const surfaces = SURFACES.map((surface) => {
-    const path = join(dir, `${surface}.md`);
-    const marker = `<!-- academy:surface:${surface} -->`;
-    const content = readSurface(dir, surface);
-    return {
+  const surfaces = surfacesFor(dir).map(({ name: surface, path }) => {
+    const entry = {
       name: surface,
       file: `${surface}.md`,
       path,
       exists: existsSync(path),
-      marker,
-      content,
+      marker: `<!-- academy:surface:${surface} -->`,
+      content: readSurface(surface, path),
     };
+    if (surface !== 'user-work') return entry;
+    const { view, ...counts } = filterUserWork(entry.content, name, basename(dir));
+    return { ...entry, content: view, ...counts };
   });
   const prompt = [
     ...intro,
@@ -274,25 +270,22 @@ export function buildAcademySystemPrompt(dir, name) {
 
 export function renderAcademySystemPrompt(dir, name) {
   mkdirSync(dirname(academySystemPromptPath(dir)), { recursive: true });
-  const { prompt } = buildAcademySystemPrompt(dir, name);
+  const { prompt, surfaces } = buildAcademySystemPrompt(dir, name);
   const promptPath = academySystemPromptPath(dir);
-  writeFileSync(promptPath, prompt);
-  return promptPath;
-}
-
-function estimateTokens(text) {
-  const normalized = text.trim();
-  if (!normalized) return 0;
-  const chunks = normalized.match(/[\p{L}\p{N}]+|[^\s\p{L}\p{N}]/gu) ?? [];
-  return Math.max(chunks.length, Math.ceil(text.length / 4));
+  // Replaced whole: a provider that starts during a concurrent render of the
+  // same agent reads the old prompt or the new one, never half of one.
+  const tempPath = join(dirname(promptPath), `.${ACADEMY_SYSTEM_PROMPT}.${process.pid}.tmp`);
+  try {
+    writeFileSync(tempPath, prompt);
+    renameSync(tempPath, promptPath);
+  } catch (err) {
+    rmSync(tempPath, { force: true });
+    throw err;
+  }
+  return { promptPath, surfaces };
 }
 
-export function tokenRecord(text) {
-  return {
-    estimatedTokens: estimateTokens(text),
-    chars: text.length,
-  };
-}
+export { tokenRecord };
 
 function writeDreamsDir(dir) {
   mkdirSync(join(dir, 'dreams'), { recursive: true });
@@ -312,8 +305,8 @@ export function writeSettingsLocal(dir) {
       allow: [
         'Bash(academy:*)',
         'Bash(helm:*)',
-        'Bash(helm-tasks:*)',
-        ...(memoryBridgeEnabled() ? MEMORY_BRIDGE_PERMISSIONS : []),
+        'Bash(tldr-agents tasks:*)',
+        ...MEMORY_BRIDGE_PERMISSIONS,
         'Bash(date:*)',
         'Read',
         'Edit',

package/scripts/cli/schedule-errors.mjs

@@ -0,0 +1,70 @@
+import { tldrTimeoutMs } from './tldr.mjs';
+
+// tldr writes info log lines to stderr and its JSON envelope to stdout, so a
+// failure is read from the envelope first — stdout, then stderr — and only
+// falls back to raw text when neither stream carries one.
+
+// No --replace fallback: --replace overwrites the operator's pause, conditions,
+// env, and misfire grace, which is the loss --merge exists to prevent.
+const TLDR_WITHOUT_MERGE_REASON =
+  'tldr-agents does not support "schedule --merge"; install tldr 0.1.1-local.f6cac003eb94 or later';
+
+export function scheduleFailureReason(result) {
+  const reason = helmFailureReason(result);
+  return rejectsMerge(result) ? `${TLDR_WITHOUT_MERGE_REASON} (${reason})` : reason;
+}
+
+// An older tldr parses unknown flags loosely, so it ignores --merge and then
+// refuses the existing id as a duplicate; a current tldr never returns
+// duplicate_id under --merge. A strict parser names the flag instead.
+function rejectsMerge({ stdout, stderr }) {
+  const text = `${stdout ?? ''}\n${stderr ?? ''}`;
+  return text.includes('duplicate_id') || text.includes('--merge');
+}
+
+// A spawn `error` (a timeout is ETIMEDOUT, with a null status) is the failure.
+export function helmFailureReason({ stdout, stderr, status, error }) {
+  if (error) {
+    return error.code === 'ETIMEDOUT'
+      ? `tldr-agents timed out after ${tldrTimeoutMs()} ms`
+      : error.message;
+  }
+  const envelopeReason = reasonFromEnvelope(parseEnvelope(stdout) ?? parseEnvelope(stderr));
+  if (envelopeReason) return envelopeReason;
+  const text = (stderr || stdout)?.trim();
+  if (!text) return `tldr-agents tasks exited ${status}`;
+  return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+}
+
+function reasonFromEnvelope(envelope) {
+  if (!envelope) return null;
+  const message = envelope.errors?.[0]?.message || envelope.data?.activation?.health?.reason;
+  const validationErrors = Array.isArray(envelope.validation_errors)
+    ? envelope.validation_errors.join(', ')
+    : '';
+  if (!message) return validationErrors ? `validation errors: ${validationErrors}` : null;
+  return validationErrors ? `${message} (validation errors: ${validationErrors})` : message;
+}
+
+// The whole stream first; else the last line that parses, since a stream may
+// carry log lines ahead of the envelope.
+function parseEnvelope(output) {
+  const text = output?.trim();
+  if (!text) return null;
+  const candidates = [text, ...text.split('\n').reverse()];
+  for (const candidate of candidates) {
+    const parsed = parseObject(candidate.trim());
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+function parseObject(text) {
+  if (!text.startsWith('{')) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/scripts/cli/sessions.mjs

@@ -9,6 +9,8 @@ import {
   isInside,
   validateName,
 } from './core.mjs';
+import { resolvedAgentDir } from '../../hooks/hook_runtime.mjs';
+import { agentIdOf } from './agent-id.mjs';
 
 // The session index is global across installs — the specialists work needs one
 // file a client can read whichever root it drives. Attribution is therefore a
@@ -55,9 +57,11 @@ export function unattributableSessionCount() {
   return readIndex().filter((row) => !row.agentDir).length;
 }
 
-function attributed(row, rootReal, agent) {
+// `--agent` filters by the directory the id or current name resolves to, so a
+// session recorded under an earlier name still belongs to the agent.
+function attributed(row, rootReal, agentHome) {
   if (!row.agentDir) return false;
-  if (agent && row.agentName !== agent) return false;
+  if (agentHome && resolvedAgentDir(row.agentDir) !== agentHome) return false;
   return isInside(row.agentDir, rootReal);
 }
 
@@ -76,8 +80,11 @@ export function readSessions({ json, agent, invalidOption }) {
   if (agent !== undefined) validateName(agent, json);
   checkAgentsRoot(json);
   const agentsRoot = resolve(AGENTS_ROOT);
+  // The hook records a realpath; the agent's folder may have moved since.
+  const agentHome =
+    agent === undefined ? null : join(resolvedAgentDir(AGENTS_ROOT), agentIdOf(agent));
   const sessions = readIndex()
-    .filter((row) => attributed(row, agentsRoot, agent))
+    .filter((row) => attributed(row, agentsRoot, agentHome))
     .map(publishedRow);
 
   if (json) {

package/scripts/cli/skills-check.mjs

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { agentDir, checkAgentsRoot, contractOk, exitJsonError, validateName } from './core.mjs';
+import { assertNotArchived } from './archived.mjs';
+import { assertContainedAgentDir } from './lifecycle.mjs';
+import { tokenRecord } from './scaffold.mjs';
+
+// The skill method's hard ceiling per file. A file at 80% of it must be split
+// before it grows further, so the check warns there and fails only over it.
+export const SKILL_TOKEN_CEILING = 2000;
+const SKILL_WARN_AT = Math.round(SKILL_TOKEN_CEILING * 0.8);
+const SKILL_SURFACES = ['.claude/skills', '.agents/skills'];
+const TOKENIZER = 'estimated:chars-and-words-v1';
+
+function skillFileStatus(estimatedTokens) {
+  if (estimatedTokens > SKILL_TOKEN_CEILING) return 'fail';
+  if (estimatedTokens >= SKILL_WARN_AT) return 'warn';
+  return 'ok';
+}
+
+function markdownFiles(skillDir) {
+  return readdirSync(skillDir, { recursive: true })
+    .filter((file) => file.endsWith('.md') && statSync(join(skillDir, file)).isFile())
+    .sort();
+}
+
+// Every SKILL.md and reference file under each skill in one skills dir. A skills
+// dir that does not exist measures as empty, not as an error.
+export function measureSkillsRoot(skillsRoot) {
+  if (!existsSync(skillsRoot)) return [];
+  const skills = readdirSync(skillsRoot)
+    .filter((skill) => statSync(join(skillsRoot, skill)).isDirectory())
+    .sort();
+  return skills.flatMap((skill) =>
+    markdownFiles(join(skillsRoot, skill)).map((file) =>
+      measureFile(skill, file, join(skillsRoot, skill, file)),
+    ),
+  );
+}
+
+function measureFile(skill, file, path) {
+  const { estimatedTokens, chars } = tokenRecord(readFileSync(path, 'utf8'));
+  return {
+    skill,
+    file,
+    path,
+    estimatedTokens,
+    chars,
+    status: skillFileStatus(estimatedTokens),
+    overBy: Math.max(0, estimatedTokens - SKILL_TOKEN_CEILING),
+  };
+}
+
+// <home>/references/*.md: linked facts held at the same ceiling. Top level only;
+// a home without the dir measures as empty.
+function measureReferences(dir) {
+  const root = join(dir, 'references');
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((file) => file.endsWith('.md') && statSync(join(root, file)).isFile())
+    .sort()
+    .map((file) => ({ surface: 'references', ...measureFile('', file, join(root, file)) }));
+}
+
+function refuseSkills(message, fields, json) {
+  if (json) exitJsonError('invalid_spec', message, fields);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function resolveCheckedAgent(name, json) {
+  validateName(name);
+  checkAgentsRoot();
+  assertNotArchived(name);
+  const dir = resolve(agentDir(name));
+  if (!existsSync(dir)) {
+    const message = `Agent "${name}" not found at ${dir}`;
+    if (json) exitJsonError('agent_not_found', message, { name });
+    console.error(message);
+    process.exit(1);
+  }
+  assertContainedAgentDir(name, dir);
+  return dir;
+}
+
+function skillsReport(name, dir) {
+  const files = SKILL_SURFACES.flatMap((surface) =>
+    measureSkillsRoot(join(dir, surface)).map((file) => ({ surface, ...file })),
+  ).concat(measureReferences(dir));
+  const counts = { ok: 0, warn: 0, fail: 0 };
+  for (const file of files) counts[file.status] += 1;
+  return {
+    agent: name,
+    dir,
+    tokenizer: TOKENIZER,
+    ceiling: SKILL_TOKEN_CEILING,
+    warnAt: SKILL_WARN_AT,
+    passed: counts.fail === 0,
+    counts,
+    files,
+  };
+}
+
+function statusLabel(file) {
+  if (file.status === 'fail') return `FAIL over by ${file.overBy}`;
+  if (file.status === 'warn') return `WARN split before ${SKILL_TOKEN_CEILING}`;
+  return 'OK';
+}
+
+function printSkillsReport(report) {
+  console.log(`${report.agent} skills check`);
+  console.log(`tokenizer: ${report.tokenizer}`);
+  console.log(`ceiling: ${report.ceiling} tokens per file, warn at ${report.warnAt}`);
+  console.log('');
+  for (const file of report.files) {
+    const label = [file.surface, file.skill, file.file].filter(Boolean).join('/');
+    console.log(
+      `${label.padEnd(48)} ${String(file.estimatedTokens).padStart(5)} / ${report.ceiling} tokens  ${statusLabel(file)}`,
+    );
+  }
+  console.log('');
+  console.log(report.passed ? 'PASS' : 'FAIL');
+}
+
+// `skills check <agent> [--json]`. A failing file is a finding, not a fault of
+// the command: the report still publishes with ok: true, and the exit code
+// carries the verdict so a nightly run can branch on it.
+export function checkSkills({ action, name, json, invalidOption }) {
+  if (invalidOption !== undefined) {
+    refuseSkills(
+      `Unknown skills option: ${invalidOption}. Use skills check <agent> [--json].`,
+      { option: invalidOption },
+      json,
+    );
+  }
+  if (action !== 'check') {
+    refuseSkills(
+      `Unknown skills action: ${action ?? '(none)'}. Use skills check <agent> [--json].`,
+      { action: action ?? null },
+      json,
+    );
+  }
+  const report = skillsReport(name, resolveCheckedAgent(name, json));
+  if (json) contractOk('skills', report);
+  else printSkillsReport(report);
+  process.exitCode = report.passed ? 0 : 1;
+}