portable-agent-layer 0.71.0 → 0.72.0

package/src/tools/session-summary.ts

@@ -3,227 +3,20 @@
  * Designed to be called from the `pal` wrapper script.
  *
  * Usage: bun run tools/session-summary.ts --session <sessionId>
+ *
+ * The reading, the arithmetic and the formatting are in lib/session-usage.ts.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { costOfUsage } from "../hooks/lib/models";
-
-// ── Types ──
-
-interface Usage {
-  input: number;
-  output: number;
-  cacheWrite5m: number;
-  cacheWrite1h: number;
-  cacheRead: number;
-  cost: number;
-  calls: number;
-  models: Set<string>;
-  durationMs: number;
-}
-
-// ── Core Functions ──
-
-function findSessionFile(
-  sessionId: string,
-  claudeDir: string
-): { filepath: string; project: string } | null {
-  if (!existsSync(claudeDir)) return null;
-
-  const projectDirs = readdirSync(claudeDir, { withFileTypes: true }).filter((d) =>
-    d.isDirectory()
-  );
-
-  for (const dir of projectDirs) {
-    const projPath = resolve(claudeDir, dir.name);
-    const projName = dir.name.split("-").pop() ?? dir.name;
-
-    const directFile = resolve(projPath, `${sessionId}.jsonl`);
-    if (existsSync(directFile)) {
-      return { filepath: directFile, project: projName };
-    }
-  }
-
-  // Fallback: scan most recently modified files
-  let latest: { filepath: string; project: string; mtime: number } | null = null;
-
-  for (const dir of readdirSync(claudeDir, { withFileTypes: true }).filter((d) =>
-    d.isDirectory()
-  )) {
-    const projPath = resolve(claudeDir, dir.name);
-    const projName = dir.name.split("-").pop() ?? dir.name;
-
-    let files: string[];
-    try {
-      files = readdirSync(projPath).filter((f) => f.endsWith(".jsonl"));
-    } catch {
-      continue;
-    }
-
-    for (const file of files) {
-      const filepath = resolve(projPath, file);
-      try {
-        const mtime = Bun.file(filepath).lastModified;
-        if (!latest || mtime > latest.mtime) {
-          latest = { filepath, project: projName, mtime };
-        }
-      } catch {
-        /* skip */
-      }
-    }
-  }
-
-  return latest;
-}
-
-function parseSession(filepath: string, sessionId: string): Usage {
-  const usage: Usage = {
-    input: 0,
-    output: 0,
-    cacheWrite5m: 0,
-    cacheWrite1h: 0,
-    cacheRead: 0,
-    cost: 0,
-    calls: 0,
-    models: new Set(),
-    durationMs: 0,
-  };
-
-  const content = readFileSync(filepath, "utf-8");
-  let firstTs = "";
-  let lastTs = "";
-
-  for (const line of content.split("\n")) {
-    if (!line) continue;
-
-    try {
-      const d = JSON.parse(line) as {
-        type?: string;
-        timestamp?: string;
-        sessionId?: string;
-        message?: {
-          model?: string;
-          usage?: {
-            input_tokens?: number;
-            output_tokens?: number;
-            cache_creation_input_tokens?: number;
-            cache_read_input_tokens?: number;
-            cache_creation?: {
-              ephemeral_5m_input_tokens?: number;
-              ephemeral_1h_input_tokens?: number;
-            };
-          };
-        };
-      };
-
-      if (d.sessionId !== sessionId) continue;
-
-      if (d.timestamp) {
-        firstTs ??= d.timestamp;
-        lastTs = d.timestamp;
-      }
+import { claudeProjectsDir, sessionSummary } from "./lib/session-usage";
 
-      if (d.type !== "assistant") continue;
-      const u = d.message?.usage;
-      const model = d.message?.model;
-      if (!u || !model) continue;
-
-      const input = u.input_tokens ?? 0;
-      const output = u.output_tokens ?? 0;
-      const cr = u.cache_read_input_tokens ?? 0;
-      const cw5m = u.cache_creation?.ephemeral_5m_input_tokens;
-      const cw1h = u.cache_creation?.ephemeral_1h_input_tokens;
-      const hasBreakdown = cw5m !== undefined || cw1h !== undefined;
-      const cacheWrite5m = hasBreakdown
-        ? (cw5m ?? 0)
-        : (u.cache_creation_input_tokens ?? 0);
-      const cacheWrite1h = cw1h ?? 0;
-
-      usage.cost += costOfUsage(model, {
-        input,
-        output,
-        cacheWrite5m,
-        cacheWrite1h,
-        cacheRead: cr,
-      });
-
-      usage.input += input;
-      usage.output += output;
-      usage.cacheWrite5m += cacheWrite5m;
-      usage.cacheWrite1h += cacheWrite1h;
-      usage.cacheRead += cr;
-      usage.calls++;
-      usage.models.add(model);
-    } catch {
-      /* skip */
-    }
-  }
-
-  if (firstTs && lastTs) {
-    usage.durationMs = new Date(lastTs).getTime() - new Date(firstTs).getTime();
-  }
-
-  return usage;
-}
-
-// ── Format helpers ──
-
-function fmtTokens(n: number): string {
-  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
-  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
-  return String(n);
-}
-
-function fmtCost(n: number): string {
-  if (n >= 1) return `$${n.toFixed(2)}`;
-  return `$${n.toFixed(4)}`;
-}
-
-function fmtDuration(ms: number): string {
-  const mins = Math.floor(ms / 60_000);
-  if (mins < 1) return "<1m";
-  if (mins < 60) return `${mins}m`;
-  const hrs = Math.floor(mins / 60);
-  const rem = mins % 60;
-  return rem > 0 ? `${hrs}h ${rem}m` : `${hrs}h`;
-}
-
-// ── CLI ──
-
-function run() {
-  const { values: args } = parseArgs({
+if (import.meta.main) {
+  const { values } = parseArgs({
     options: { session: { type: "string" } },
     strict: false,
   });
 
-  const sessionId = typeof args.session === "string" ? args.session : "";
-  if (!sessionId) process.exit(0);
-
-  const claudeDir = resolve(homedir(), ".claude", "projects");
-  const file = findSessionFile(sessionId, claudeDir);
-  if (!file) process.exit(0);
-
-  const usage = parseSession(file.filepath, sessionId);
-  if (usage.calls === 0) process.exit(0);
-
-  const totalTokens =
-    usage.input +
-    usage.output +
-    usage.cacheWrite5m +
-    usage.cacheWrite1h +
-    usage.cacheRead;
-  const model = [...usage.models].map((m) => m.replace("claude-", "")).join(", ");
-
-  const dim = "\x1b[2m";
-  const reset = "\x1b[0m";
-  const cyan = "\x1b[36m";
-
-  console.log(
-    `\n${dim}Session: ${file.project} · ${model} · ${fmtDuration(usage.durationMs)} · ${fmtTokens(totalTokens)} tokens · ${usage.calls} calls · ${cyan}${fmtCost(usage.cost)}${reset}`
-  );
+  const sessionId = typeof values.session === "string" ? values.session : "";
+  const summary = sessionSummary(sessionId, claudeProjectsDir());
+  if (summary) console.log(summary);
 }
-
-if (import.meta.main) run();

package/src/tools/skill-doctor.ts

@@ -1,446 +1,16 @@
+#!/usr/bin/env bun
 /**
  * skill-doctor — static evaluator for a SKILL.md against Anthropic's
- * skill-authoring best practices. Checks only what is mechanically verifiable:
- * name/description constraints, body length, point-of-view, and reference depth.
+ * skill-authoring best practices.
  *
- * Library:  import { lintSkill, formatReport } from ".../skill-doctor"
- * Script:   bun src/tools/skill-doctor.ts <skill-dir-or-name>
- *           (resolves a path, or a name under ~/.pal/skills/)
- * CLI:      pal cli skill doctor <name>   (see src/cli/skill.ts)
- */
-
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, extname, relative, resolve } from "node:path";
-import { palHome } from "../hooks/lib/paths";
-import { declaredTriggers } from "../hooks/lib/skill-triggers";
-
-type Level = "pass" | "warn" | "error";
-
-interface DoctorFinding {
-  level: Level;
-  check: string;
-  message: string;
-}
-
-export interface DoctorReport {
-  dir: string;
-  name: string | null;
-  findings: DoctorFinding[];
-  errors: number;
-  warnings: number;
-}
-
-interface ParsedSkill {
-  name: string | null;
-  description: string | null;
-  descriptionQuoted: boolean;
-  triggers: string[];
-  shipped: boolean;
-  license: string | null;
-  derivedFrom: string | null;
-  body: string;
-}
-
-const SHIPPED_SOURCE = "portable-agent-layer";
-
-const RESERVED_WORDS = ["anthropic", "claude"];
-const MAX_NAME = 64;
-const MAX_DESCRIPTION = 1024;
-const MAX_BODY_LINES = 500;
-const MIN_TRIGGERS = 3;
-
-/** File extensions worth scanning for hardcoded paths (SKILL.md + its scripts). */
-const SCANNABLE_EXT = new Set([".md", ".ts", ".js", ".mjs", ".cjs", ".sh", ".py"]);
-
-/** Machine/user-specific absolute paths that will not survive an export to
- * another machine or user: POSIX home dirs and Windows user profiles. Portable
- * forms ($HOME, ~, %USERPROFILE%, env vars) are deliberately not matched. */
-const ABSOLUTE_PATH_RE =
-  /(?:\/(?:Users|home)\/[A-Za-z0-9._-]+|\/root\/[A-Za-z0-9._-]|[A-Za-z]:\\Users\\[A-Za-z0-9._-]+)/;
-
-/** Collect SKILL.md and sibling script files, skipping vendored/VCS trees. */
-function collectSkillFiles(skillDir: string): string[] {
-  const out: string[] = [];
-  const walk = (dir: string) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
-      const full = resolve(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.isFile() && SCANNABLE_EXT.has(extname(entry.name))) out.push(full);
-    }
-  };
-  walk(skillDir);
-  return out;
-}
-
-/** Find machine-specific absolute paths across a skill's files. */
-function findAbsolutePaths(skillDir: string): string[] {
-  const hits: string[] = [];
-  for (const file of collectSkillFiles(skillDir)) {
-    const rel = relative(skillDir, file).replaceAll("\\", "/");
-    const lines = readFileSync(file, "utf-8").split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      const m = ABSOLUTE_PATH_RE.exec(lines[i]);
-      if (m) hits.push(`${rel}:${i + 1} → ${m[0]}`);
-    }
-  }
-  return hits;
-}
-
-/** Split a SKILL.md into frontmatter fields and body. */
-function parseSkill(content: string): ParsedSkill {
-  const parts = content.split(/^---\s*$/m);
-  if (parts.length < 3) {
-    return {
-      name: null,
-      description: null,
-      descriptionQuoted: false,
-      triggers: [],
-      shipped: false,
-      license: null,
-      derivedFrom: null,
-      body: content,
-    };
-  }
-  const frontmatter = parts[1];
-  const body = parts.slice(2).join("---");
-  const name = /^name:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
-  const rawDescription = /^description:[ \t]*(.*?)\s*$/m.exec(frontmatter)?.[1] ?? null;
-  const descriptionQuoted =
-    rawDescription !== null &&
-    rawDescription.length >= 2 &&
-    rawDescription.startsWith('"') &&
-    rawDescription.endsWith('"');
-  const description = descriptionQuoted ? rawDescription.slice(1, -1) : rawDescription;
-  return {
-    name,
-    description,
-    descriptionQuoted,
-    triggers: declaredTriggers(frontmatter),
-    shipped: metadataField(frontmatter, "source") === SHIPPED_SOURCE,
-    license: topLevelField(frontmatter, "license"),
-    derivedFrom: metadataField(frontmatter, "derived-from"),
-    body,
-  };
-}
-
-/** Value of a top-level `key:` line in the frontmatter, unquoted. */
-function topLevelField(frontmatter: string, key: string): string | null {
-  return (
-    new RegExp(String.raw`^${key}:\s*"?(.+?)"?\s*$`, "m").exec(frontmatter)?.[1] ?? null
-  );
-}
-
-/** Value of an indented `key:` line under the `metadata:` block, unquoted. */
-function metadataField(frontmatter: string, key: string): string | null {
-  return (
-    new RegExp(String.raw`^[ \t]+${key}:\s*"?(.+?)"?\s*$`, "m").exec(frontmatter)?.[1] ??
-    null
-  );
-}
-
-/** Render triggers for a report line: `"a", "b"` or `"a" then "b"`. */
-function quoteList(triggers: string[], separator: string): string {
-  return triggers.map((trigger) => `"${trigger}"`).join(separator);
-}
-
-/**
- * The triggers every skill must declare first: its own name, then the
- * de-hyphenated form a user would actually type. A single-word name has only
- * the one form, and the parser dedupes anyway, so it requires just itself.
+ * Usage: bun src/tools/skill-doctor.ts <skill-dir-or-name>
+ *        (resolves a path, or a name under ~/.pal/skills/)
+ *
+ * The checks live in src/tools/lib/skill-doctor.ts; this file only turns argv
+ * into a report and a report into an exit code.
  */
-function leadTriggers(name: string): string[] {
-  const spaced = name.replaceAll("-", " ");
-  return spaced === name ? [name] : [name, spaced];
-}
 
-/** Remove fenced and inline code so prose checks don't trip on examples. */
-function stripCode(s: string): string {
-  return s.replace(/```[\s\S]*?```/g, "").replace(/`[^`]*`/g, "");
-}
-
-/**
- * Evaluate the skill at `skillDir` (a folder containing SKILL.md) and return a
- * structured report. Hard rules from Anthropic's validation surface as errors;
- * best-practice nudges surface as warnings.
- */
-export function lintSkill(skillDir: string): DoctorReport {
-  const findings: DoctorFinding[] = [];
-  const add = (level: Level, check: string, message: string) =>
-    findings.push({ level, check, message });
-
-  if (!existsSync(skillDir)) {
-    add("error", "structure", `No skill directory at ${skillDir}`);
-    return { dir: skillDir, name: null, findings, errors: 1, warnings: 0 };
-  }
-
-  // The runtime only loads a file named exactly `SKILL.md`. On case-insensitive
-  // filesystems (macOS, Windows) `existsSync` would accept `skill.md`, so match
-  // the real on-disk entry, not a case-folded path.
-  const skillFile = readdirSync(skillDir).find((e) => e.toLowerCase() === "skill.md");
-  if (!skillFile) {
-    add("error", "structure", `No SKILL.md found in ${skillDir}`);
-    return { dir: skillDir, name: null, findings, errors: 1, warnings: 0 };
-  }
-  skillFile === "SKILL.md"
-    ? add("pass", "file.name", "skill file is named SKILL.md")
-    : add(
-        "error",
-        "file.name",
-        `skill file is "${skillFile}" — must be exactly "SKILL.md" or the skill is silently ignored`
-      );
-
-  const {
-    name,
-    description,
-    descriptionQuoted,
-    triggers,
-    shipped,
-    license,
-    derivedFrom,
-    body,
-  } = parseSkill(readFileSync(resolve(skillDir, skillFile), "utf-8"));
-
-  // ── provenance (shipped skills only) ──
-  if (shipped) {
-    if (license) add("pass", "license", `licensed ${license}`);
-    else if (derivedFrom)
-      add("pass", "license", `unlicensed by design — derived from ${derivedFrom}`);
-    else
-      add(
-        "warn",
-        "license",
-        "shipped skill declares no license — add `license: MIT`, or `metadata.derived-from: <origin>` when the idea comes from another project"
-      );
-  }
-
-  // The runtime keys a skill by its folder name; a mismatched frontmatter `name`
-  // makes the skill silently fail to load.
-  const folder = basename(skillDir);
-  if (name) {
-    name === folder
-      ? add("pass", "name.folder", `matches folder "${folder}"`)
-      : add(
-          "error",
-          "name.folder",
-          `name "${name}" must equal the folder name "${folder}" verbatim — otherwise the skill is silently ignored`
-        );
-  }
-
-  // ── name ──
-  if (!name) {
-    add("error", "name", "Missing `name` in frontmatter");
-  } else {
-    name.length <= MAX_NAME
-      ? add("pass", "name.length", `${name.length}/${MAX_NAME} chars`)
-      : add("error", "name.length", `${name.length} chars exceeds ${MAX_NAME}`);
-    /^[a-z0-9-]+$/.test(name)
-      ? add("pass", "name.charset", "lowercase letters, numbers, hyphens only")
-      : add(
-          "error",
-          "name.charset",
-          `"${name}" must be lowercase a-z, 0-9, hyphens only`
-        );
-    const reserved = RESERVED_WORDS.find((w) => name.toLowerCase().includes(w));
-    reserved
-      ? add("error", "name.reserved", `contains reserved word "${reserved}"`)
-      : add("pass", "name.reserved", "no reserved words");
-  }
-
-  // ── description ──
-  if (!description) {
-    add("error", "description", "Missing `description` in frontmatter");
-  } else {
-    description.length <= MAX_DESCRIPTION
-      ? add(
-          "pass",
-          "description.length",
-          `${description.length}/${MAX_DESCRIPTION} chars`
-        )
-      : add(
-          "error",
-          "description.length",
-          `${description.length} chars exceeds ${MAX_DESCRIPTION}`
-        );
-    descriptionQuoted
-      ? add("pass", "description.quoted", "value is wrapped in double quotes")
-      : add(
-          "warn",
-          "description.quoted",
-          'value is not wrapped in double quotes — unquoted YAML mis-parses on colons, commas, and quotes; wrap it in "..." (escaping any inner " as \\")'
-        );
-    /<[^>]+>/.test(description)
-      ? add(
-          "warn",
-          "description.xml",
-          "contains angle-bracket content — Anthropic disallows XML tags; rephrase placeholders like <x> in prose"
-        )
-      : add("pass", "description.xml", "no XML tags");
-    /\bwhen/i.test(description)
-      ? add("pass", "description.trigger", "states when to use the skill")
-      : add(
-          "warn",
-          "description.trigger",
-          "no 'when to use' trigger — add 'Use when …' so the dispatcher can match it"
-        );
-    /\b(I can|I['’]ll|I will|I help|you can|you will|you could|you['’]ll)\b/i.test(
-      description
-    )
-      ? add(
-          "warn",
-          "description.pov",
-          "reads first/second person — write descriptions in third person (e.g. 'Processes…', 'Generates…')"
-        )
-      : add("pass", "description.pov", "third person");
-  }
-
-  // ── triggers ──
-  if (triggers.length === 0) {
-    add(
-      "warn",
-      "metadata.triggers",
-      "no metadata.triggers declared — add the words and phrases a prompt would contain so the prompt-time matcher can surface this skill; without them it falls back to keywords mined from the description"
-    );
-  } else if (triggers.length < MIN_TRIGGERS) {
-    add(
-      "warn",
-      "metadata.triggers",
-      `only ${triggers.length} trigger(s) declared — aim for at least ${MIN_TRIGGERS}, mostly multi-word phrases`
-    );
-  } else {
-    add("pass", "metadata.triggers", `${triggers.length} triggers declared`);
-  }
-
-  if (name && triggers.length > 0) {
-    const lead = leadTriggers(name);
-    const actual = triggers.slice(0, lead.length);
-    const wanted = quoteList(lead, " then ");
-    const found = quoteList(actual, ", ") || "nothing";
-    actual.join("\u0000") === lead.join("\u0000")
-      ? add("pass", "metadata.triggers.lead", `leads with ${wanted}`)
-      : add(
-          "warn",
-          "metadata.triggers.lead",
-          `triggers must lead with ${wanted} — found ${found}`
-        );
-  }
-
-  // ── body ──
-  const bodyLines = body.split("\n").length;
-  bodyLines <= MAX_BODY_LINES
-    ? add("pass", "body.length", `${bodyLines}/${MAX_BODY_LINES} lines`)
-    : add(
-        "warn",
-        "body.length",
-        `${bodyLines} lines exceeds ${MAX_BODY_LINES} — split into reference files`
-      );
-
-  const prose = stripCode(body);
-  /\b(I['’]m|I will|I['’]ll|in my experience|my workflow|I wrote|I created)\b/i.test(
-    prose
-  )
-    ? add(
-        "warn",
-        "body.pov",
-        "body uses first-person author voice — write it as second-person instructions to the assistant"
-      )
-    : add("pass", "body.pov", "instructional voice");
-
-  // ── reference depth (one level deep) ──
-  const linkRe = /\[[^\]]+\]\(([^)]+\.md)\)/g;
-  const skillFilePath = resolve(skillDir, skillFile);
-  // A reference back to the entry SKILL.md is a return-link, not a deeper chain.
-  const isDeeperRef = (target: string) =>
-    !/^https?:/.test(target) && resolve(skillDir, target) !== skillFilePath;
-  let nested = false;
-  for (const m of body.matchAll(linkRe)) {
-    const target = m[1];
-    if (!isDeeperRef(target)) continue;
-    const targetPath = resolve(skillDir, target);
-    if (!existsSync(targetPath)) continue;
-    const refContent = readFileSync(targetPath, "utf-8");
-    const onward = [...refContent.matchAll(linkRe)]
-      .map((mm) => mm[1])
-      .filter(isDeeperRef);
-    if (onward.length > 0) {
-      nested = true;
-      add(
-        "warn",
-        "references.depth",
-        `${target} links to further .md files — keep references one level deep from SKILL.md`
-      );
-    }
-  }
-  if (!nested) add("pass", "references.depth", "references are one level deep");
-
-  // ── windows-style paths ──
-  // Skip lines that are deliberate Windows examples (cmd.exe / %ENV% paths) —
-  // a cross-platform skill may legitimately document the Windows invocation.
-  const winPathRe = /\b[\w.-]+\\[\w.-]+\.(py|ts|js|sh|md|json)\b/;
-  const isIntentionalWindows = (line: string) =>
-    /%[A-Z_]+%/.test(line) || /cmd\.exe/i.test(line);
-  body.split("\n").some((l) => winPathRe.test(l) && !isIntentionalWindows(l))
-    ? add("warn", "paths", "Windows-style backslash path found — use forward slashes")
-    : add("pass", "paths", "forward-slash paths");
-
-  // ── machine-specific absolute paths (portability) ──
-  // A personal skill MAY legitimately hardcode a machine-specific path (e.g. a
-  // cloud-mount vault), so this is a warning, never an error — it flags paths
-  // that will not survive being exported to another machine or user.
-  const absHits = findAbsolutePaths(skillDir);
-  if (absHits.length > 0) {
-    const shown = absHits.slice(0, 3).join("; ");
-    const more = absHits.length > 3 ? ` (+${absHits.length - 3} more)` : "";
-    add(
-      "warn",
-      "paths.absolute",
-      `hardcoded absolute path(s) that won't be portable across machines: ${shown}${more} — prefer $HOME/~ or an env var, or ignore if this is an intentional machine-specific mount`
-    );
-  } else {
-    add("pass", "paths.absolute", "no machine-specific absolute paths");
-  }
-
-  const errors = findings.filter((f) => f.level === "error").length;
-  const warnings = findings.filter((f) => f.level === "warn").length;
-  return { dir: skillDir, name, findings, errors, warnings };
-}
-
-/** Render a report as a human-readable string. */
-/** One scannable line per skill for a whole-store run: verdict plus the checks that fired. */
-export function formatSummary(r: DoctorReport): string {
-  const fired = (level: Level) =>
-    r.findings.filter((f) => f.level === level).map((f) => f.check);
-  // The folder name, not the frontmatter name — the folder is what the reader
-  // passes back to `pal cli skill doctor <name>`, and a mismatch between the two
-  // is itself one of the errors this line reports.
-  const name = basename(r.dir).padEnd(20);
-
-  if (r.errors > 0) {
-    return `✗ ${name} ${r.errors} error(s): ${fired("error").join(", ")}`;
-  }
-  if (r.warnings > 0) {
-    return `⚠ ${name} ${r.warnings} warning(s): ${fired("warn").join(", ")}`;
-  }
-  return `✓ ${name} clean`;
-}
-
-export function formatReport(r: DoctorReport): string {
-  const icon = { pass: "✓", warn: "⚠", error: "✗" } as const;
-  const lines = [`skill-doctor: ${r.name ?? "(unparsed)"}  —  ${r.dir}`];
-  for (const f of r.findings) {
-    lines.push(`  ${icon[f.level]} ${f.check}: ${f.message}`);
-  }
-  let verdict: string;
-  if (r.errors > 0) {
-    verdict = `FAIL — ${r.errors} error(s), ${r.warnings} warning(s)`;
-  } else if (r.warnings > 0) {
-    verdict = `OK with ${r.warnings} warning(s)`;
-  } else {
-    verdict = "PASS — all checks clean";
-  }
-  lines.push(`  ${verdict}`);
-  return lines.join("\n");
-}
+import { formatReport, lintSkill, resolveSkillDir } from "./lib/skill-doctor";
 
 if (import.meta.main) {
   const arg = process.argv[2];
@@ -448,12 +18,7 @@ if (import.meta.main) {
     console.error("Usage: bun src/tools/skill-doctor.ts <skill-dir-or-name>");
     process.exit(2);
   }
-  let dir = resolve(arg);
-  if (!existsSync(resolve(dir, "SKILL.md"))) {
-    const byName = resolve(palHome(), "skills", arg);
-    if (existsSync(resolve(byName, "SKILL.md"))) dir = byName;
-  }
-  const report = lintSkill(dir);
+  const report = lintSkill(resolveSkillDir(arg));
   console.log(formatReport(report));
   process.exit(report.errors > 0 ? 1 : 0);
 }