skillio 0.1.4 → 0.1.6

package/README.md

@@ -66,23 +66,24 @@ audits both Claude Code and Codex over all time).
 ## Usage
 
 ```sh
-# from any repo: scoped to that repo
-skl                                    # both agents, all-time, this repo only
-skl -a claude --period 7d              # claude only, last 7 days, this repo
-
-# from $HOME (or anywhere with -g): global, all repos on this machine
-cd ~ && skl                            # auto-global when cwd === $HOME
-skl -g                                 # force global from any repo
-skl --global --period 1m               # global, last 30 days
-
-skillio …                              # same binary, longer alias
-skillio -a claude-code codex           # both agents (space-separated)
-skillio -a claude -a codex             # equivalent: repeated --agent flag
-skillio list                           # list skills in local skills-lock.json
-skillio list --global                  # list from ~/.agents/.skill-lock.json
-skillio remove brainstorming           # remove skill from lock
-skillio remove brainstorming writing-plans  # remove multiple skills
-skillio remove --dry-run brainstorming # preview removal
+# bare command — quick summary across global + local sources, with verdict
+skl
+skillio                                # equivalent
+
+# subcommands
+skl ls                                 # list skills per source with diffs
+skl cost                               # ambient ballast cost (frontmatter tokens) per skill
+skl usage                              # consumption: usage count × frontmatter tokens
+skl rm brainstorming                   # remove from lock + delete on-disk dir (with Y/n prompt)
+skl rm brainstorming writing-plans     # remove multiple
+skl rm --yes brainstorming             # skip confirmation
+skl rm --dry-run brainstorming         # preview only
+
+# scope flags
+skl -g                                 # force global scope on any subcommand
+skl usage -p 7d                        # last 7 days
+skl usage -a claude-code codex         # both agents (space-separated)
+skl usage -a claude -a codex           # equivalent: repeated --agent flag
 ```
 
 ### Scope (per-repo vs global)
@@ -96,26 +97,38 @@ skillio remove --dry-run brainstorming # preview removal
 | anywhere with `-g` / `--global` | global override |
 | with `--root <dir>` | that exact dir, treated as global |
 
+> Bare `skl` (no subcommand) ignores `-g` — it always shows both Global and Local sections plus a grand Total.
+
 ## What it does
 
-- **Audit skill usage** — parse agent session logs and count which skills were invoked, when, and how often
-- **Manage a skills lock** — list and remove skills from a local or global lock file
+- **Summary** (`skl`) — counts and tokens across `.claude/skills`, `.agents/skills`, and `skills-lock.json` for both global and local scopes, with a cleanup verdict.
+- **Audit skill usage** (`skl usage`) — parse agent session logs and count which skills were invoked, when, and how often.
+- **Manage a skills lock** (`skl ls`, `skl rm`) — inspect and remove skills from a local or global lock file.
 
 ## Options
 
-### `skillio` (audit)
+### Global flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-h, --help` | — | Show help and exit |
+| `-v, --version` | — | Show version and exit |
+| `-g, --global` | `false` | Use global scope (ignore current directory) |
+| `-p, --period` | `all` | Period for `usage`: `30sec`, `5min`, `12h`, `7d`, `2w`, `1m`, `1y`, `all` |
+| `-a, --agent` | both | Agent for `usage`: `claude-code` (alias `claude`), `codex` — pass both space-separated (`-a claude-code codex`) or repeat the flag |
+
+### `skillio usage` / `us`
 
-Audits skill usage from agent session logs. This is the default operation —
-no subcommand keyword is needed.
+Audits skill usage from agent session logs.
 
 ```sh
-skillio --agent claude --period 7d
-skillio --agent codex --mode activations
+skillio usage --agent claude --period 7d
+skillio usage --agent codex --mode activations
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `-a, --agent` | both | `claude-code`/`claude`, `codex` — pass both space-separated (`-a claude-code codex`) or repeat the flag (`-a claude -a codex`) |
+| `-a, --agent` | both | `claude-code`/`claude`, `codex` |
 | `-p, --period` | `all` | `7d`, `2w`, `1m`, `1y`, `all` |
 | `--since` | — | `yyyy-mm-dd`, overrides `--period` |
 | `--mode` | `attributed` (claude) / `activations` (codex) | `attributed` \| `activations` \| `mentions` |
@@ -137,6 +150,13 @@ skillio list            # local skills-lock.json
 skillio list --global   # ~/.agents/.skill-lock.json
 ```
 
+### `skillio cost` / `co`
+
+```sh
+skillio cost            # local: per-skill frontmatter tokens with verdict
+skillio cost --global   # same, against ~/.agents/.skill-lock.json
+```
+
 ### `skillio remove` / `rm`
 
 ```sh
@@ -144,6 +164,7 @@ skillio remove <skill-name>
 skillio remove <skill-one> <skill-two>
 skillio remove --global <skill-name>
 skillio remove --dry-run <skill-name>
+skillio remove --yes <skill-name>      # skip confirmation prompt
 ```
 
 ## Requirements

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli.ts
-import { createRequire } from "node:module";
+import { createRequire as createRequire2 } from "node:module";
 
 // node_modules/citty/dist/_chunks/libs/scule.mjs
 var NUMBER_CHAR_RE = /\d/;
@@ -545,12 +547,524 @@ function _getBuiltinFlags(long, short, userNames, userAliases) {
   return [`--${long}`, `-${short}`];
 }
 
-// src/commands/audit.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { join as join4 } from "node:path";
+// src/lock/file.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+function getLockPath(global) {
+  return global ? join(homedir(), ".agents", ".skill-lock.json") : "skills-lock.json";
+}
+function readLock(path) {
+  if (!existsSync(path))
+    return { skills: {} };
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function writeLock(path, lock) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.${Date.now()}.skill-lock.json`);
+  writeFileSync(tmp, `${JSON.stringify(lock, null, 2)}
+`);
+  renameSync(tmp, path);
+}
+function removeSkillFromLock(path, skill) {
+  if (!existsSync(path))
+    return { removed: false };
+  const lock = readLock(path);
+  if (!Object.hasOwn(lock.skills, skill))
+    return { removed: false };
+  delete lock.skills[skill];
+  writeLock(path, lock);
+  return { removed: true };
+}
+
+// src/utils/ansi.ts
+var enabled = false;
+function setColorEnabled(value) {
+  enabled = value;
+}
+function detectColorSupport() {
+  if (process.env.NO_COLOR)
+    return false;
+  return Boolean(process.stdout.isTTY);
+}
+function green(s) {
+  return enabled ? `\x1B[32m${s}\x1B[0m` : s;
+}
+function yellow(s) {
+  return enabled ? `\x1B[33m${s}\x1B[0m` : s;
+}
+function red(s) {
+  return enabled ? `\x1B[31m${s}\x1B[0m` : s;
+}
+
+// src/utils/discover-skills.ts
+import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync3, statSync } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
+
+// src/utils/skill-files.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+var CHARS_PER_TOKEN = 4;
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match?.[1];
+}
+function estimateTokens(text) {
+  return Math.round(text.length / CHARS_PER_TOKEN);
+}
+
+// src/utils/discover-skills.ts
+function resolveRoots(input) {
+  if (input.isGlobal) {
+    return {
+      claude: join3(homedir3(), ".claude", "skills"),
+      agents: join3(homedir3(), ".agents", "skills")
+    };
+  }
+  const repo = dirname3(resolve2(input.lockPath));
+  return {
+    claude: join3(repo, ".claude", "skills"),
+    agents: join3(repo, ".agents", "skills")
+  };
+}
+function listSkillNames(root) {
+  if (!root || !existsSync3(root))
+    return [];
+  return readdirSync(root).filter((name) => {
+    const skill = join3(root, name, "SKILL.md");
+    return existsSync3(skill) && statSync(skill).isFile();
+  });
+}
+function tokensFromFile(path) {
+  const content = readFileSync3(path, "utf8");
+  const fm = extractFrontmatter(content);
+  if (fm === undefined)
+    return { status: "no-frontmatter" };
+  return { tokens: estimateTokens(fm), status: "ok" };
+}
+function discoverSkills(input) {
+  const roots = resolveRoots(input);
+  const lock = readLock(input.lockPath);
+  const lockNames = Object.keys(lock.skills);
+  const claudeNames = listSkillNames(roots.claude);
+  const agentsNames = listSkillNames(roots.agents);
+  const all = new Set([...lockNames, ...claudeNames, ...agentsNames]);
+  const out = new Map;
+  for (const name of all) {
+    const sources = [];
+    if (lockNames.includes(name))
+      sources.push("lock");
+    if (claudeNames.includes(name))
+      sources.push(".claude");
+    if (agentsNames.includes(name))
+      sources.push(".agents");
+    let skillFile;
+    if (claudeNames.includes(name) && roots.claude) {
+      skillFile = join3(roots.claude, name, "SKILL.md");
+    } else if (agentsNames.includes(name) && roots.agents) {
+      skillFile = join3(roots.agents, name, "SKILL.md");
+    }
+    if (!skillFile) {
+      out.set(name, { name, sources, status: "missing" });
+      continue;
+    }
+    const { tokens, status } = tokensFromFile(skillFile);
+    out.set(name, { name, sources, skillFile, frontmatterTokens: tokens, status });
+  }
+  return out;
+}
+
+// src/commands/cost.ts
+function classify(total) {
+  if (total < 1000)
+    return { verdict: "ok", message: "OK — keep it lean", paint: green };
+  if (total <= 1500)
+    return { verdict: "plan", message: "time to plan some cleanup", paint: yellow };
+  return { verdict: "cleanup", message: "ballast — clean it up", paint: red };
+}
+function sortRows(records) {
+  const ok = records.filter((r) => r.status === "ok");
+  const rest = records.filter((r) => r.status !== "ok");
+  ok.sort((a, b) => (b.frontmatterTokens ?? 0) - (a.frontmatterTokens ?? 0) || a.name.localeCompare(b.name));
+  rest.sort((a, b) => a.name.localeCompare(b.name));
+  return [...ok, ...rest];
+}
+var costCommand = defineCommand({
+  meta: { description: "Show ambient ballast cost (per-skill frontmatter tokens) sorted desc" },
+  args: {
+    global: { type: "boolean", alias: "g", default: false, description: "Use global scope" }
+  },
+  run({ args }) {
+    const lockPath = getLockPath(args.global);
+    const map = discoverSkills({ isGlobal: args.global, cwd: process.cwd(), lockPath });
+    const rows = sortRows([...map.values()]);
+    const total = rows.reduce((acc, r) => acc + (r.frontmatterTokens ?? 0), 0);
+    const { message, paint } = classify(total);
+    console.log(args.global ? "Global" : "Local");
+    console.log("");
+    if (rows.length === 0) {
+      console.log(`No skills in ${lockPath}`);
+      return;
+    }
+    const nameWidth = Math.max(...rows.map((r) => r.name.length));
+    for (const r of rows) {
+      let cell;
+      if (r.status === "ok")
+        cell = `~${r.frontmatterTokens} tok`;
+      else if (r.status === "missing")
+        cell = "missing";
+      else
+        cell = "(no frontmatter)";
+      console.log(`${r.name.padEnd(nameWidth)}  ${cell}`);
+    }
+    console.log("");
+    console.log(`Total: ~${total} tok across ${rows.length} skills    ${paint(message)}`);
+  }
+});
+
+// src/commands/list.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname4, join as join4, resolve as resolve3 } from "node:path";
+function bySource(records) {
+  const claudeNames = records.filter((r) => r.sources.includes(".claude")).map((r) => r.name).sort();
+  const agentsNames = records.filter((r) => r.sources.includes(".agents")).map((r) => r.name).sort();
+  const lockNames = records.filter((r) => r.sources.includes("lock")).map((r) => r.name).sort();
+  const sumTokens = (names) => names.reduce((acc, n) => acc + (records.find((r) => r.name === n)?.frontmatterTokens ?? 0), 0);
+  return {
+    claude: {
+      label: ".claude/skills",
+      names: claudeNames,
+      tokens: sumTokens(claudeNames),
+      exists: true
+    },
+    agents: {
+      label: ".agents/skills",
+      names: agentsNames,
+      tokens: sumTokens(agentsNames),
+      exists: true
+    },
+    lock: {
+      label: "skills-lock.json",
+      names: lockNames,
+      tokens: sumTokens(lockNames),
+      exists: true
+    }
+  };
+}
+function agentsDirExists(isGlobal, lockPath) {
+  if (isGlobal) {
+    return existsSync4(join4(process.env.HOME ?? "", ".agents", "skills"));
+  }
+  return existsSync4(join4(dirname4(resolve3(lockPath)), ".agents", "skills"));
+}
+var listCommand = defineCommand({
+  meta: { description: "List skills per source with totals and lock-vs-disk diff" },
+  args: {
+    global: { type: "boolean", alias: "g", default: false, description: "Use global scope" }
+  },
+  run({ args }) {
+    const lockPath = getLockPath(args.global);
+    const map = discoverSkills({ isGlobal: args.global, cwd: process.cwd(), lockPath });
+    const records = [...map.values()];
+    const rows = bySource(records);
+    const showAgents = agentsDirExists(args.global, lockPath) || rows.agents.names.length > 0;
+    const claudeNames = rows.claude.names;
+    const agentsNames = rows.agents.names;
+    const lockNames = rows.lock.names;
+    const lockOnly = lockNames.filter((n) => !claudeNames.includes(n) && !agentsNames.includes(n));
+    const claudeNotInLock = claudeNames.filter((n) => !lockNames.includes(n));
+    const agentsNotInLock = agentsNames.filter((n) => !lockNames.includes(n));
+    const sourceRows = [rows.claude];
+    if (showAgents)
+      sourceRows.push(rows.agents);
+    sourceRows.push(rows.lock);
+    const labelWidth = Math.max(...sourceRows.map((r) => r.label.length));
+    const countCells = sourceRows.map((r) => r.names.length === 0 ? "(empty)" : `${r.names.length} skill${r.names.length === 1 ? "" : "s"}`);
+    const countWidth = Math.max(...countCells.map((c) => c.length));
+    for (let i = 0;i < sourceRows.length; i++) {
+      const row = sourceRows[i];
+      if (!row)
+        continue;
+      const countCell = countCells[i] ?? "";
+      const namesText = row.names.length ? row.names.join(" ") : "";
+      const line = `${row.label.padEnd(labelWidth)} : ${countCell.padEnd(countWidth)}${namesText ? ` : ${namesText}` : ""}`;
+      console.log(line.trimEnd());
+    }
+    const diffs = [];
+    if (lockOnly.length) {
+      diffs.push(`skills-lock.json has ${lockOnly.length} skill${lockOnly.length === 1 ? "" : "s"} missing on disk: ${lockOnly.join(", ")}`);
+    }
+    if (claudeNotInLock.length) {
+      diffs.push(`.claude/skills has ${claudeNotInLock.length} skill${claudeNotInLock.length === 1 ? "" : "s"} not in lock: ${claudeNotInLock.join(", ")}`);
+    }
+    if (agentsNotInLock.length) {
+      diffs.push(`.agents/skills has ${agentsNotInLock.length} skill${agentsNotInLock.length === 1 ? "" : "s"} not in lock: ${agentsNotInLock.join(", ")}`);
+    }
+    if (diffs.length) {
+      console.log("");
+      for (const line of diffs)
+        console.log(line);
+    }
+  }
+});
+
+// src/commands/remove.ts
+import { existsSync as existsSync6 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname5, join as join6, resolve as resolve5 } from "node:path";
+
+// src/utils/confirm.ts
+import { createInterface } from "node:readline/promises";
+async function confirm(question, opts = {}) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const rl = createInterface({
+    input,
+    output
+  });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+// src/utils/fs-rm.ts
+import { existsSync as existsSync5, lstatSync, readdirSync as readdirSync2, rmSync } from "node:fs";
+import { join as join5, resolve as resolve4 } from "node:path";
+function isInside(target, root) {
+  const t = resolve4(target);
+  const r = resolve4(root);
+  return t === r || t.startsWith(`${r}/`);
+}
+function countFiles(path) {
+  if (!existsSync5(path))
+    return 0;
+  const stat = lstatSync(path);
+  if (stat.isFile())
+    return 1;
+  if (!stat.isDirectory())
+    return 0;
+  let n = 0;
+  for (const entry of readdirSync2(path)) {
+    n += countFiles(join5(path, entry));
+  }
+  return n;
+}
+function rmSkillDir(path, opts) {
+  const safe = opts.allowedRoots.some((root) => isInside(path, root));
+  if (!safe) {
+    throw new Error(`Refusing to delete: "${path}" is outside allowed roots`);
+  }
+  if (!existsSync5(path))
+    return { removed: false, fileCount: 0 };
+  const fileCount = countFiles(path);
+  rmSync(path, { recursive: true, force: true });
+  return { removed: true, fileCount };
+}
+
+// src/commands/remove.ts
+function buildTarget(name, isGlobal, lockPath) {
+  const lock = readLock(lockPath);
+  const inLock = Object.hasOwn(lock.skills, name);
+  const baseClaude = isGlobal ? join6(homedir4(), ".claude", "skills") : join6(dirname5(resolve5(lockPath)), ".claude", "skills");
+  const baseAgents = isGlobal ? join6(homedir4(), ".agents", "skills") : join6(dirname5(resolve5(lockPath)), ".agents", "skills");
+  const claudeDir = existsSync6(join6(baseClaude, name)) ? join6(baseClaude, name) : undefined;
+  const agentsDir = existsSync6(join6(baseAgents, name)) ? join6(baseAgents, name) : undefined;
+  return { name, inLock, claudeDir, agentsDir };
+}
+function fileCount(dir) {
+  const { readdirSync: readdirSync3, statSync: statSync2 } = __require("node:fs");
+  let n = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    const stat = statSync2(cur);
+    if (stat.isFile())
+      n++;
+    else if (stat.isDirectory())
+      for (const e of readdirSync3(cur))
+        stack.push(join6(cur, e));
+  }
+  return n;
+}
+function printPlan(plan) {
+  const { target } = plan;
+  console.log(`Will remove "${target.name}":`);
+  if (target.inLock)
+    console.log("  - skills-lock.json");
+  else
+    console.log("  - skills-lock.json (not in lock)");
+  if (target.claudeDir)
+    console.log(`  - .claude/skills/${target.name}/  (${plan.claudeFileCount} files)`);
+  else
+    console.log("  - .claude/skills/  (not found)");
+  if (target.agentsDir)
+    console.log(`  - .agents/skills/${target.name}/  (${plan.agentsFileCount} files)`);
+  else
+    console.log("  - .agents/skills/  (not found)");
+}
+var removeCommand = defineCommand({
+  meta: { description: "Remove one or more skills from lock and delete their on-disk directories" },
+  args: {
+    global: { type: "boolean", alias: "g", default: false, description: "Use global scope" },
+    "dry-run": { type: "boolean", default: false, description: "Print plan, do not delete" },
+    yes: { type: "boolean", alias: "y", default: false, description: "Skip confirmation prompt" }
+  },
+  async run({ args }) {
+    const { global: isGlobal, "dry-run": dryRun, yes } = args;
+    const subcmdIdx = process.argv.findIndex((a) => a === "remove" || a === "rm");
+    const names = process.argv.slice(subcmdIdx + 1).filter((a) => !a.startsWith("-"));
+    if (names.length === 0) {
+      console.error("No skill names provided");
+      process.exit(1);
+    }
+    const lockPath = getLockPath(isGlobal);
+    const targets = names.map((n) => buildTarget(n, isGlobal, lockPath));
+    const orphan = targets.filter((t) => !t.inLock && !t.claudeDir && !t.agentsDir);
+    if (orphan.length) {
+      for (const o of orphan)
+        console.log(`"${o.name}" is not in lock or on disk`);
+      process.exit(1);
+    }
+    const plans = targets.map((t) => ({
+      target: t,
+      claudeFileCount: t.claudeDir ? fileCount(t.claudeDir) : undefined,
+      agentsFileCount: t.agentsDir ? fileCount(t.agentsDir) : undefined
+    }));
+    for (const p of plans) {
+      printPlan(p);
+      console.log("");
+    }
+    if (dryRun)
+      return;
+    if (!yes) {
+      const ok = await confirm("Proceed?");
+      if (!ok) {
+        console.log("Aborted");
+        process.exit(1);
+      }
+    }
+    const allowedRoots = [
+      isGlobal ? homedir4() : dirname5(resolve5(lockPath)),
+      homedir4()
+    ];
+    for (const { target } of plans) {
+      if (target.inLock) {
+        const r = removeSkillFromLock(lockPath, target.name);
+        if (r.removed)
+          console.log(`Removed "${target.name}" from skills-lock.json`);
+      } else {
+        console.log(`Skipped skills-lock.json (not in lock)`);
+      }
+      if (target.claudeDir) {
+        const r = rmSkillDir(target.claudeDir, { allowedRoots });
+        console.log(`Removed "${target.name}" from .claude/skills (${r.fileCount} files)`);
+      } else {
+        console.log("Skipped .claude/skills (not found)");
+      }
+      if (target.agentsDir) {
+        const r = rmSkillDir(target.agentsDir, { allowedRoots });
+        console.log(`Removed "${target.name}" from .agents/skills (${r.fileCount} files)`);
+      } else {
+        console.log("Skipped .agents/skills (not found)");
+      }
+    }
+  }
+});
+
+// src/commands/summary.ts
+function classify2(total) {
+  if (total < 1000)
+    return { verdict: "ok", message: "OK — keep it lean", paint: green };
+  if (total <= 1500)
+    return { verdict: "plan", message: "time to plan some cleanup", paint: yellow };
+  return { verdict: "cleanup", message: "ballast — clean it up", paint: red };
+}
+function bucketTokens(records, source) {
+  return records.filter((r) => r.sources.includes(source)).reduce((acc, r) => acc + (r.frontmatterTokens ?? 0), 0);
+}
+function bucketCount(records, source) {
+  return records.filter((r) => r.sources.includes(source)).length;
+}
+function buildSection(opts) {
+  const lockPath = getLockPath(opts.isGlobal);
+  const records = [
+    ...discoverSkills({ isGlobal: opts.isGlobal, cwd: opts.cwd, lockPath }).values()
+  ];
+  const rows = [
+    {
+      label: `${opts.prefix}.claude/skills`,
+      count: bucketCount(records, ".claude"),
+      tokens: bucketTokens(records, ".claude")
+    },
+    {
+      label: `${opts.prefix}.agents/skills`,
+      count: bucketCount(records, ".agents"),
+      tokens: bucketTokens(records, ".agents")
+    },
+    {
+      label: `${opts.prefix}skills-lock.json`,
+      count: bucketCount(records, "lock"),
+      tokens: bucketTokens(records, "lock")
+    }
+  ];
+  const totalTokens = records.reduce((acc, r) => acc + (r.frontmatterTokens ?? 0), 0);
+  const totalCount = records.length;
+  return {
+    title: opts.isGlobal ? "Global" : "Local",
+    rows,
+    totalCount,
+    totalTokens
+  };
+}
+function formatRow(row, labelW, countW, tokenW) {
+  const countCell = row.count === 0 ? "(empty)" : `${row.count} skill${row.count === 1 ? "" : "s"}`;
+  const tokensCell = `~${row.tokens} tok`;
+  return `${row.label.padEnd(labelW)} : ${countCell.padEnd(countW)}  ${tokensCell.padStart(tokenW)}`;
+}
+function renderSection(section) {
+  const labelW = Math.max(...section.rows.map((r) => r.label.length));
+  const countCells = section.rows.map((r) => r.count === 0 ? "(empty)" : `${r.count} skill${r.count === 1 ? "" : "s"}`);
+  const countW = Math.max(...countCells.map((c) => c.length));
+  const tokenW = Math.max(...section.rows.map((r) => `~${r.tokens} tok`.length));
+  return [section.title, ...section.rows.map((r) => formatRow(r, labelW, countW, tokenW))];
+}
+function runSummary(args) {
+  const cwd = process.cwd();
+  const global = buildSection({ isGlobal: true, cwd, prefix: "~/" });
+  const local = buildSection({ isGlobal: false, cwd, prefix: "" });
+  const lines = [];
+  lines.push(...renderSection(global));
+  lines.push("");
+  lines.push(...renderSection(local));
+  lines.push("");
+  const grandTokens = global.totalTokens + local.totalTokens;
+  const grandCount = global.totalCount + local.totalCount;
+  const { message, paint } = classify2(grandTokens);
+  lines.push(`Total: ${grandCount} skills  ~${grandTokens} tok    ${paint(message)}`);
+  console.log(lines.join(`
+`));
+}
+var summaryCommand = defineCommand({
+  meta: { description: "Show skill counts and tokens across global + local sources" },
+  args: {
+    global: { type: "boolean", alias: "g", default: false, description: "Use global scope" }
+  },
+  run({ args }) {
+    runSummary({ global: args.global });
+  }
+});
+
+// src/commands/usage.ts
+import { existsSync as existsSync9 } from "node:fs";
+import { join as join10 } from "node:path";
 
 // src/readers/claude.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 
 // src/utils/walk.ts
 function walk(value, visit) {
@@ -658,26 +1172,26 @@ function extractCodexMentions(entry) {
 }
 
 // src/utils/expand-home.ts
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { homedir as homedir5 } from "node:os";
+import { join as join7, resolve as resolve6 } from "node:path";
 function expandHome(p) {
   if (p === "~")
-    return homedir();
+    return homedir5();
   if (p.startsWith("~/"))
-    return join(homedir(), p.slice(2));
-  return resolve(p);
+    return join7(homedir5(), p.slice(2));
+  return resolve6(p);
 }
 
 // src/utils/jsonl.ts
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join as join2 } from "node:path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync4, statSync as statSync2 } from "node:fs";
+import { join as join8 } from "node:path";
 function* findJsonlFiles(dir, since) {
-  for (const item of readdirSync(dir, { withFileTypes: true })) {
-    const path = join2(dir, item.name);
+  for (const item of readdirSync3(dir, { withFileTypes: true })) {
+    const path = join8(dir, item.name);
     if (item.isDirectory()) {
       yield* findJsonlFiles(path, since);
     } else if (item.isFile() && item.name.endsWith(".jsonl")) {
-      if (!since || statSync(path).mtime >= since)
+      if (!since || statSync2(path).mtime >= since)
         yield path;
     }
   }
@@ -711,7 +1225,7 @@ function readClaudeUsage(options) {
   const since = options.scanAllFiles ? undefined : options.since;
   for (const file of findJsonlFiles(root, since)) {
     filesRead++;
-    for (const line of readFileSync2(file, "utf8").split(`
+    for (const line of readFileSync5(file, "utf8").split(`
 `)) {
       if (!line.trim())
         continue;
@@ -733,14 +1247,14 @@ function readClaudeUsage(options) {
 }
 
 // src/readers/codex.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
 
 // src/utils/scope.ts
-import { existsSync } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { dirname, join as join3 } from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { dirname as dirname6, join as join9 } from "node:path";
 function detectScope(opts) {
-  const home = opts.home ?? homedir2();
+  const home = opts.home ?? homedir6();
   if (opts.global || opts.rootOverride)
     return { global: true };
   if (norm(opts.cwd) === norm(home))
@@ -758,9 +1272,9 @@ function encodeClaudeProjectDir(absPath) {
 function findGitRoot(start) {
   let dir = start;
   while (true) {
-    if (existsSync(join3(dir, ".git")))
+    if (existsSync7(join9(dir, ".git")))
       return dir;
-    const parent = dirname(dir);
+    const parent = dirname6(dir);
     if (parent === dir)
       return;
     dir = parent;
@@ -774,7 +1288,7 @@ function norm(p) {
 function readSessionCwd(file) {
   let head;
   try {
-    head = readFileSync3(file, "utf8");
+    head = readFileSync6(file, "utf8");
   } catch {
     return;
   }
@@ -807,7 +1321,7 @@ function readCodexActivations(options) {
         continue;
     }
     filesRead++;
-    for (const line of readFileSync3(file, "utf8").split(`
+    for (const line of readFileSync6(file, "utf8").split(`
 `)) {
       if (!line.trim())
         continue;
@@ -831,9 +1345,9 @@ function readCodexMentions(options) {
   const historyPath = expandHome(options.history ?? "~/.codex/history.jsonl");
   const counts = new Map;
   let linesRead = 0;
-  if (!existsSync2(historyPath))
+  if (!existsSync8(historyPath))
     return { counts, filesRead: 0, linesRead: 0 };
-  for (const line of readFileSync3(historyPath, "utf8").split(`
+  for (const line of readFileSync6(historyPath, "utf8").split(`
 `)) {
     if (!line.trim())
       continue;
@@ -854,38 +1368,77 @@ function readCodexMentions(options) {
 }
 
 // src/utils/period.ts
-var UNITS = { d: 1, w: 7, m: 30, y: 365 };
-var MS_PER_DAY = 24 * 60 * 60 * 1000;
+var SECOND_MS = 1000;
+var MINUTE_MS = 60 * SECOND_MS;
+var HOUR_MS = 60 * MINUTE_MS;
+var DAY_MS = 24 * HOUR_MS;
+var UNITS_MS = {
+  sec: SECOND_MS,
+  min: MINUTE_MS,
+  h: HOUR_MS,
+  d: DAY_MS,
+  w: 7 * DAY_MS,
+  m: 30 * DAY_MS,
+  y: 365 * DAY_MS
+};
 function parsePeriod(period) {
   if (period === "all")
     return Number.POSITIVE_INFINITY;
-  const match = period.match(/^(\d+)([dwmy])$/);
-  if (!match)
-    throw new Error(`Invalid period: "${period}". Use values like 7d, 2w, 1m, 1y, all.`);
-  const unit = UNITS[match[2] ?? ""] ?? 1;
+  const match = period.match(/^(\d+)(sec|min|[hdwmy])$/);
+  if (!match) {
+    throw new Error(`Invalid period: "${period}". Use values like 30sec, 5min, 12h, 7d, 2w, 1m, 1y, all.`);
+  }
+  const unit = UNITS_MS[match[2] ?? ""] ?? 0;
   return Number(match[1]) * unit;
 }
 
-// src/commands/audit.ts
+// src/commands/usage.ts
+function pad(n, width) {
+  return String(n).padStart(width);
+}
+function formatUsageRow(row) {
+  return `${pad(row.count, row.countWidth)} ${row.name}`;
+}
 function parseAgents(agent) {
   if (!agent)
     return ["claude-code", "codex"];
-  const normalized = agent.split("\x1F").map((a) => a.trim()).filter(Boolean).map((a) => {
+  const out = agent.split("\x1F").map((a) => a.trim()).filter(Boolean).map((a) => {
     if (a === "codex")
       return "codex";
     if (["claude", "claude-code", "claudecode"].includes(a))
       return "claude-code";
     throw new Error(`Unknown agent: "${a}". Use "claude-code" or "codex" (space-separated for both: -a claude-code codex).`);
   });
-  return [...new Set(normalized)];
+  return [...new Set(out)];
 }
-function toRows(counts) {
-  return [...counts.entries()].sort(([sa, ca], [sb, cb]) => cb - ca || sa.localeCompare(sb)).map(([skill, count]) => ({ skill, count }));
-}
-async function runAudit(args) {
+var usageArgs = {
+  agent: {
+    type: "string",
+    alias: "a",
+    description: "claude-code, codex (default: both)"
+  },
+  period: {
+    type: "string",
+    alias: "p",
+    default: "all",
+    description: "30sec, 5min, 12h, 7d, 2w, 1m, 1y, all"
+  },
+  since: { type: "string", description: "yyyy-mm-dd, overrides --period" },
+  mode: { type: "string", description: "attributed | activations | mentions" },
+  format: { type: "string", default: "text", description: "text | json" },
+  root: { type: "string", description: "Override agent sessions directory; implies global" },
+  "scan-all-files": { type: "boolean", default: false, description: "Ignore file mtime" },
+  global: {
+    type: "boolean",
+    alias: "g",
+    default: false,
+    description: "Force global scope"
+  }
+};
+async function runUsage(args) {
   const agents = parseAgents(args.agent);
   const allTime = !args.since && args.period === "all";
-  const since = args.since ? new Date(`${args.since}T00:00:00`) : args.period === "all" ? new Date(0) : new Date(Date.now() - parsePeriod(args.period) * 24 * 60 * 60 * 1000);
+  const since = args.since ? new Date(`${args.since}T00:00:00`) : args.period === "all" ? new Date(0) : new Date(Date.now() - parsePeriod(args.period));
   const scanAllFiles = allTime || args["scan-all-files"];
   if (Number.isNaN(since.getTime())) {
     console.error(`Invalid --since value: ${args.since}`);
@@ -897,21 +1450,26 @@ async function runAudit(args) {
     cwd: process.cwd()
   });
   const claudeProjectsRoot = expandHome("~/.claude/projects");
-  const claudeRoot = args.root ?? (scope.projectRoot ? join4(claudeProjectsRoot, encodeClaudeProjectDir(scope.projectRoot)) : claudeProjectsRoot);
-  const claudeRootMissing = !args.root && !!scope.projectRoot && !existsSync3(claudeRoot);
+  const claudeRoot = args.root ?? (scope.projectRoot ? join10(claudeProjectsRoot, encodeClaudeProjectDir(scope.projectRoot)) : claudeProjectsRoot);
+  const claudeRootMissing = !args.root && !!scope.projectRoot && !existsSync9(claudeRoot);
+  const lockPath = getLockPath(args.global);
+  const skillUniverse = discoverSkills({
+    isGlobal: args.global,
+    cwd: process.cwd(),
+    lockPath
+  });
   const results = [];
   for (const agent of agents) {
+    let counts;
+    let stats;
+    let mode;
     if (agent === "claude-code") {
-      const mode = args.mode ?? "attributed";
+      mode = args.mode ?? "attributed";
       const result = claudeRootMissing ? { counts: new Map, filesRead: 0, linesRead: 0 } : readClaudeUsage({ since, mode, root: claudeRoot, scanAllFiles });
-      results.push({
-        agent,
-        mode,
-        rows: toRows(result.counts),
-        stats: { filesRead: result.filesRead, linesRead: result.linesRead }
-      });
+      counts = result.counts;
+      stats = { filesRead: result.filesRead, linesRead: result.linesRead };
     } else {
-      const mode = args.mode ?? "activations";
+      mode = args.mode ?? "activations";
       const result = readCodexUsage({
         since,
         mode,
@@ -919,165 +1477,167 @@ async function runAudit(args) {
         scanAllFiles,
         projectRoot: scope.projectRoot
       });
-      results.push({
-        agent,
-        mode,
-        rows: toRows(result.counts),
-        stats: { filesRead: result.filesRead, linesRead: result.linesRead }
-      });
+      counts = result.counts;
+      stats = { filesRead: result.filesRead, linesRead: result.linesRead };
     }
+    const universeNames = new Set([...skillUniverse.keys(), ...counts.keys()]);
+    const rows = [...universeNames].map((name) => {
+      const rec = skillUniverse.get(name);
+      return {
+        name,
+        count: counts.get(name) ?? 0,
+        tokens: rec?.frontmatterTokens,
+        status: rec?.status ?? "ok"
+      };
+    });
+    rows.sort((a, b) => {
+      const aOk = a.status === "ok";
+      const bOk = b.status === "ok";
+      if (aOk !== bOk)
+        return aOk ? -1 : 1;
+      if (b.count !== a.count)
+        return b.count - a.count;
+      return a.name.localeCompare(b.name);
+    });
+    results.push({ agent, mode, rows, stats });
   }
   if (args.format === "json") {
     const output = results.map(({ agent, mode, rows }) => ({
       agent,
       mode,
       since: since.toISOString(),
-      skills: rows
+      skills: rows.map((r) => ({
+        skill: r.name,
+        count: r.count,
+        tokensPerSkill: r.tokens ?? null,
+        consumption: (r.tokens ?? 0) * r.count
+      }))
     }));
     console.log(JSON.stringify(output.length === 1 ? output[0] : output, null, 2));
     return;
   }
-  const sinceLabel = allTime ? "all-time" : `since ${since.toISOString().slice(0, 10)}`;
-  const scopeLabel = scope.global ? "global" : scope.projectRoot ?? "global";
-  console.log(`Scope: ${scopeLabel}${scope.global ? "" : "  (use -g for global)"}`);
-  for (const { agent, mode, rows, stats } of results) {
-    console.log(`
-${agent} skill usage ${sinceLabel} (${mode})`);
-    console.log(`Files read: ${stats.filesRead}; JSONL lines read: ${stats.linesRead}`);
-    if (rows.length === 0) {
-      console.log("No skills found.");
-    } else {
-      const maxLen = Math.max(...rows.map((r) => String(r.count).length));
-      for (const r of rows)
-        console.log(`${String(r.count).padStart(maxLen)} ${r.skill}`);
+  const periodLabel = args.since ? `since ${args.since}` : args.period ?? "all";
+  const scopeHeader = scope.global ? "Global" : "Local";
+  console.log(scopeHeader);
+  const distinct = new Set;
+  let grandActivations = 0;
+  for (const { agent, rows } of results) {
+    const activations = rows.reduce((acc, r) => acc + r.count, 0);
+    console.log("");
+    console.log(`${agent} ${rows.length} skill${rows.length === 1 ? "" : "s"} ${activations} time${activations === 1 ? "" : "s"} by ${periodLabel}`);
+    if (rows.length === 0)
+      continue;
+    const countWidth = Math.max(...rows.map((r) => String(r.count).length));
+    for (const r of rows) {
+      console.log(formatUsageRow({ count: r.count, name: r.name, countWidth }));
+      distinct.add(r.name);
     }
+    grandActivations += activations;
   }
+  console.log("");
+  console.log(`Total: ${distinct.size} skill${distinct.size === 1 ? "" : "s"} usage ${grandActivations} time${grandActivations === 1 ? "" : "s"}`);
 }
-var auditArgs = {
-  agent: {
-    type: "string",
-    alias: "a",
-    description: "claude-code, codex (default: both; pass space-separated for both)"
-  },
-  period: { type: "string", alias: "p", default: "all", description: "7d, 2w, 1m, 1y, all" },
-  since: { type: "string", description: "yyyy-mm-dd, overrides --period" },
-  mode: { type: "string", description: "attributed | activations | mentions" },
-  format: { type: "string", default: "text", description: "text | json" },
-  root: { type: "string", description: "Override agent sessions directory; implies global" },
-  "scan-all-files": { type: "boolean", default: false, description: "Ignore file mtime" },
-  global: {
-    type: "boolean",
-    alias: "g",
-    default: false,
-    description: "Force global scope (ignore current directory)"
+var usageCommand = defineCommand({
+  meta: { description: "Show skill usage x cost (consumption) with missed rows" },
+  args: usageArgs,
+  async run({ args }) {
+    try {
+      await runUsage(args);
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
   }
-};
+});
 
-// src/lock/file.ts
-import {
-  copyFileSync,
-  existsSync as existsSync4,
-  mkdirSync,
-  readFileSync as readFileSync4,
-  renameSync,
-  writeFileSync
-} from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { basename, dirname as dirname2, join as join5 } from "node:path";
-function getLockPath(global) {
-  return global ? join5(homedir3(), ".agents", ".skill-lock.json") : "skills-lock.json";
-}
-function readLock(path) {
-  if (!existsSync4(path))
-    return { skills: {} };
-  return JSON.parse(readFileSync4(path, "utf8"));
+// src/utils/update-check.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "node:fs";
+import { get } from "node:https";
+import { homedir as homedir7 } from "node:os";
+import { dirname as dirname7, join as join11 } from "node:path";
+var PKG = "skillio";
+var TTL_MS = 24 * 60 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 1500;
+function getCachePath() {
+  return join11(homedir7(), ".cache", "skillio", "version.json");
 }
-function writeLock(path, lock) {
-  mkdirSync(dirname2(path), { recursive: true });
-  const tmp = join5(dirname2(path), `.${Date.now()}.skill-lock.json`);
-  writeFileSync(tmp, `${JSON.stringify(lock, null, 2)}
-`);
-  renameSync(tmp, path);
+function compareVersions(a, b) {
+  const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0;i < 3; i += 1) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db)
+      return da - db;
+  }
+  return 0;
 }
-function getBackupPath(path) {
-  return join5(dirname2(path), ".tmp", `${basename(path)}.bak`);
+function readCache(path = getCachePath()) {
+  try {
+    return JSON.parse(readFileSync7(path, "utf8"));
+  } catch {
+    return;
+  }
 }
-function backupLock(path) {
-  const backupPath = getBackupPath(path);
-  mkdirSync(dirname2(backupPath), { recursive: true });
-  copyFileSync(path, backupPath);
-  return backupPath;
+function writeCache(cache, path = getCachePath()) {
+  try {
+    mkdirSync2(dirname7(path), { recursive: true });
+    writeFileSync2(path, JSON.stringify(cache));
+  } catch {}
 }
-function removeSkillFromLock(path, skill, { skipBackup = false } = {}) {
-  if (!existsSync4(path))
-    return { removed: false };
-  const lock = readLock(path);
-  if (!Object.hasOwn(lock.skills, skill))
-    return { removed: false };
-  const backupPath = skipBackup ? undefined : backupLock(path);
-  delete lock.skills[skill];
-  writeLock(path, lock);
-  return { removed: true, backupPath };
+function fetchLatest() {
+  return new Promise((resolve7) => {
+    const req = get(`https://registry.npmjs.org/${PKG}/latest`, { timeout: FETCH_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        resolve7(undefined);
+        return;
+      }
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          const data = JSON.parse(body);
+          resolve7(typeof data.version === "string" ? data.version : undefined);
+        } catch {
+          resolve7(undefined);
+        }
+      });
+    });
+    req.on("error", () => resolve7(undefined));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve7(undefined);
+    });
+  });
 }
-
-// src/commands/list.ts
-var listCommand = defineCommand({
-  meta: { description: "List skills in the lock file" },
-  args: {
-    global: { type: "boolean", alias: "g", default: false, description: "Use global lock file" }
-  },
-  run({ args }) {
-    const path = getLockPath(args.global);
-    const lock = readLock(path);
-    const skills = Object.keys(lock.skills).sort();
-    console.log(JSON.stringify(skills, null, 2));
+async function maybePrintUpdateNotice(currentVersion) {
+  if (process.env.SKILLIO_NO_UPDATE_CHECK)
+    return;
+  const now = Date.now();
+  const cache = readCache();
+  let latest = cache?.latest;
+  if (!cache || now - cache.checkedAt > TTL_MS) {
+    const fetched = await fetchLatest();
+    if (fetched) {
+      latest = fetched;
+      writeCache({ checkedAt: now, latest });
+    }
   }
-});
+  if (latest && compareVersions(latest, currentVersion) > 0) {
+    process.stderr.write(`
+Update available: ${currentVersion} → ${latest}
+Run: npm i -g skillio
 
-// src/commands/remove.ts
-import { existsSync as existsSync5 } from "node:fs";
-var removeCommand = defineCommand({
-  meta: { description: "Remove one or more skills from the lock file" },
-  args: {
-    global: { type: "boolean", alias: "g", default: false, description: "Use global lock file" },
-    "dry-run": { type: "boolean", default: false, description: "Print without making changes" }
-  },
-  run({ args }) {
-    const { global: isGlobal, "dry-run": dryRun } = args;
-    const subcmdIdx = process.argv.findIndex((a) => a === "remove" || a === "rm");
-    const skills = process.argv.slice(subcmdIdx + 1).filter((a) => !a.startsWith("-"));
-    if (skills.length === 0) {
-      console.error("No skill names provided");
-      process.exit(1);
-    }
-    const path = getLockPath(isGlobal);
-    if (dryRun) {
-      for (const skill of skills) {
-        console.log(`Would remove "${skill}" from ${path}`);
-      }
-      return;
-    }
-    const backupPath = existsSync5(path) ? backupLock(path) : undefined;
-    for (const skill of skills) {
-      const result = removeSkillFromLock(path, skill, { skipBackup: true });
-      if (result.removed) {
-        console.log(`Removed "${skill}" from ${path}`);
-      } else {
-        console.log(`"${skill}" is not in ${path}`);
-      }
-    }
-    if (backupPath)
-      console.log(`Backup: ${backupPath}`);
-    const updated = readLock(path);
-    console.log(JSON.stringify(Object.keys(updated.skills).sort(), null, 2));
+`);
   }
-});
+}
 
 // src/cli.ts
-var { version } = createRequire(import.meta.url)("../package.json");
-if (process.argv[2] === "audit") {
-  process.argv.splice(2, 1);
-}
+var { version } = createRequire2(import.meta.url)("../package.json");
 function mergeAgentArgs(argv) {
   const out = [];
   const values = [];
@@ -1110,30 +1670,126 @@ function mergeAgentArgs(argv) {
     out.splice(slotIdx, 0, "--agent", values.join("\x1F"));
   return out;
 }
-process.argv = mergeAgentArgs(process.argv);
-var SUBCOMMAND_NAMES = new Set(["list", "ls", "remove", "rm"]);
+var SUBCOMMAND_NAMES = new Set(["list", "ls", "remove", "rm", "cost", "co", "usage", "us"]);
+function reorderRootFlagsToSubcommand(argv) {
+  const tail = argv.slice(2);
+  const subIdx = tail.findIndex((t) => !!t && SUBCOMMAND_NAMES.has(t));
+  if (subIdx <= 0)
+    return argv;
+  const before = tail.slice(0, subIdx);
+  const sub = tail[subIdx];
+  const after = tail.slice(subIdx + 1);
+  if (!sub)
+    return argv;
+  return [argv[0] ?? "", argv[1] ?? "", sub, ...before, ...after];
+}
+process.argv = reorderRootFlagsToSubcommand(mergeAgentArgs(process.argv));
+function printRootHelp() {
+  const lines = [
+    `Audit and manage AI agent skills (skillio v${version})`,
+    "",
+    "USAGE skillio [OPTIONS] [COMMAND]",
+    "",
+    "OPTIONS",
+    "",
+    "  -h, --help       Show this help and exit",
+    "  -v, --version    Show version and exit",
+    "  -g, --global     Use global scope (default: false)",
+    "  -p, --period     Period for `usage`: 30sec, 5min, 12h, 7d, 2w, 1m, 1y, all (default: all)",
+    "  -a, --agent      Agent for `usage`: claude-code, codex (default: both)",
+    "",
+    "COMMANDS",
+    "",
+    "  list, ls         List skills per source with totals and lock-vs-disk diff",
+    "  remove, rm       Remove skills from lock and delete their on-disk dirs",
+    "  cost, co         Show ambient ballast cost (per-skill frontmatter tokens) sorted desc",
+    "  usage, us        Show skill usage × cost (consumption) with missed rows"
+  ];
+  console.log(lines.join(`
+`));
+}
+function isRootHelp(argv) {
+  const args = argv.slice(2);
+  const first = args[0];
+  if (first && SUBCOMMAND_NAMES.has(first))
+    return false;
+  return args.includes("--help") || args.includes("-h");
+}
+function firstPositional(argv) {
+  for (let i = 2;i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok)
+      continue;
+    if (tok.startsWith("-")) {
+      if (tok === "-p" || tok === "--period" || tok === "-a" || tok === "--agent")
+        i++;
+      continue;
+    }
+    return tok;
+  }
+  return null;
+}
+function hasSubcommand(argv) {
+  const tok = firstPositional(argv);
+  return tok !== null && SUBCOMMAND_NAMES.has(tok);
+}
+function unknownCommand(argv) {
+  const tok = firstPositional(argv);
+  if (!tok)
+    return null;
+  if (SUBCOMMAND_NAMES.has(tok))
+    return null;
+  return tok;
+}
+function isRootVersion(argv) {
+  const args = argv.slice(2);
+  const first = args[0];
+  if (first && SUBCOMMAND_NAMES.has(first))
+    return false;
+  return args.includes("--version") || args.includes("-v");
+}
 var main = defineCommand({
   meta: {
     name: "skillio",
     version,
     description: "Audit and manage AI agent skills"
   },
-  args: auditArgs,
+  args: summaryCommand.args,
   async run({ args }) {
-    if (SUBCOMMAND_NAMES.has(process.argv[2] ?? ""))
+    if (hasSubcommand(process.argv))
       return;
-    try {
-      await runAudit(args);
-    } catch (e) {
-      console.error(e instanceof Error ? e.message : String(e));
-      process.exit(1);
-    }
+    await summaryCommand.run?.({
+      args,
+      cmd: summaryCommand,
+      rawArgs: process.argv.slice(2)
+    });
   },
   subCommands: {
     list: listCommand,
     ls: listCommand,
     remove: removeCommand,
-    rm: removeCommand
+    rm: removeCommand,
+    cost: costCommand,
+    co: costCommand,
+    usage: usageCommand,
+    us: usageCommand
   }
 });
-runMain(main);
+(async () => {
+  if (isRootHelp(process.argv)) {
+    printRootHelp();
+    return;
+  }
+  if (isRootVersion(process.argv)) {
+    console.log(version);
+    return;
+  }
+  const unknown = unknownCommand(process.argv);
+  if (unknown) {
+    console.error(`${unknown} - is unknowed, use skl -h for usage`);
+    process.exit(1);
+  }
+  setColorEnabled(detectColorSupport());
+  await maybePrintUpdateNotice(version);
+  runMain(main);
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillio",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Audit and manage AI agent skills for Claude Code and Codex",
   "license": "MIT",
   "author": "ihororlovskyi",