skillio 0.1.3 → 0.1.5

package/README.md

@@ -9,29 +9,93 @@ Audit and manage AI agent skills for Claude Code and OpenAI Codex.
 
 ```sh
 # one-off (no install needed)
-npx skillio audit --agent claude --period 7d
-pnpm dlx skillio audit --agent codex --period 2w
+npx skillio --agent claude --period 7d
+pnpm dlx skillio --agent codex --period 2w
 
-# global install
-npm install -g skillio
+# global install — provides both `skillio` and `skl` commands in $PATH
+npm install -g skillio       # recommended
 pnpm add -g skillio
 ```
 
+### Local install (per-project)
+
+If you'd rather pin `skillio` to a single project (e.g. for CI) instead of
+installing globally:
+
+```sh
+npm install -D skillio       # adds to devDependencies
+pnpm add -D skillio
+yarn add -D skillio
+bun add -d skillio
+```
+
+Then run via your package manager — both `skillio` and `skl` are exposed:
+
+```sh
+npx skillio                  # works from any subdir of the project
+pnpm exec skl                # short alias
+yarn skl
+bun x skillio
+```
+
+You can also wire it into `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "audit:skills": "skl"
+  }
+}
+```
+
+…then `npm run audit:skills`.
+
+## Updating
+
+> Already have `skillio` installed? Get the latest version:
+
+```sh
+npm install -g skillio@latest        # recommended
+pnpm add -g skillio@latest
+```
+
+If you're on `0.1.3` or older — please upgrade. Newer versions add per-repo
+scoping, the `skl` short alias, and saner defaults (`skillio` with no flags now
+audits both Claude Code and Codex over all time).
+
 ## Usage
 
 ```sh
-skillio --agent claude --period 7d         # audit last 7 days (default subcommand)
-skillio audit --agent claude --period 7d   # audit last 7 days (attributed mode)
-skillio audit --agent codex --mode activations  # codex activations
-skillio audit -a claude codex --period 2w  # both agents, space-separated
-skillio audit -a claude,codex --period 2w  # both agents, comma-separated
-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
+# 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
+skillio remove --dry-run brainstorming # preview removal
 ```
 
+### Scope (per-repo vs global)
+
+`skillio` / `skl` automatically picks a scope based on your current directory:
+
+| where you run it | scope |
+|------------------|-------|
+| inside a git repo | that repo only (data filtered to its path) |
+| in `$HOME` exactly | global — all repos on this machine |
+| anywhere with `-g` / `--global` | global override |
+| with `--root <dir>` | that exact dir, treated as global |
+
 ## What it does
 
 - **Audit skill usage** — parse agent session logs and count which skills were invoked, when, and how often
@@ -39,23 +103,25 @@ skillio remove --dry-run brainstorming     # preview removal
 
 ## Options
 
-### `skillio` / `skillio audit`
+### `skillio` (audit)
 
-Audits skill usage from agent session logs. `audit` is the default subcommand when the first argument is an audit flag.
+Audits skill usage from agent session logs. This is the default operation —
+no subcommand keyword is needed.
 
 ```sh
 skillio --agent claude --period 7d
-skillio audit --agent codex --mode activations
+skillio --agent codex --mode activations
 ```
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `-a, --agent` | required | `claude-code`/`claude`, `codex`, comma- or space-separated |
-| `-p, --period` | `7d` | `7d`, `2w`, `1m`, `1y` |
+| `-a, --agent` | both | `claude-code`/`claude`, `codex` — pass both space-separated (`-a claude-code codex`) or repeat the flag (`-a claude -a codex`) |
+| `-p, --period` | `all` | `7d`, `2w`, `1m`, `1y`, `all` |
 | `--since` | — | `yyyy-mm-dd`, overrides `--period` |
-| `--mode` | `attributed` | `attributed` \| `activations` \| `mentions` |
+| `--mode` | `attributed` (claude) / `activations` (codex) | `attributed` \| `activations` \| `mentions` |
 | `--format` | `text` | `text` \| `json` |
-| `--root` | — | Override agent sessions directory |
+| `-g, --global` | `false` | Force global scope (ignore current directory) |
+| `--root` | — | Override agent sessions directory; implies global |
 | `--scan-all-files` | — | Ignore file mtime, read everything |
 
 ### Modes

package/dist/cli.js

@@ -545,6 +545,10 @@ 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/readers/claude.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 
@@ -729,7 +733,64 @@ function readClaudeUsage(options) {
 }
 
 // src/readers/codex.ts
-import { existsSync, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } 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";
+function detectScope(opts) {
+  const home = opts.home ?? homedir2();
+  if (opts.global || opts.rootOverride)
+    return { global: true };
+  if (norm(opts.cwd) === norm(home))
+    return { global: true };
+  return { global: false, projectRoot: findGitRoot(opts.cwd) ?? opts.cwd };
+}
+function isPathInProject(path, projectRoot) {
+  const p = norm(path);
+  const r = norm(projectRoot);
+  return p === r || p.startsWith(`${r}/`);
+}
+function encodeClaudeProjectDir(absPath) {
+  return absPath.replaceAll("/", "-");
+}
+function findGitRoot(start) {
+  let dir = start;
+  while (true) {
+    if (existsSync(join3(dir, ".git")))
+      return dir;
+    const parent = dirname(dir);
+    if (parent === dir)
+      return;
+    dir = parent;
+  }
+}
+function norm(p) {
+  return p.toLowerCase().replace(/\/+$/, "");
+}
+
+// src/readers/codex.ts
+function readSessionCwd(file) {
+  let head;
+  try {
+    head = readFileSync3(file, "utf8");
+  } catch {
+    return;
+  }
+  const lines = head.split(`
+`, 30);
+  for (const line of lines) {
+    if (!line.trim())
+      continue;
+    try {
+      const e = JSON.parse(line);
+      if (e.type === "session_meta" && typeof e.payload?.cwd === "string")
+        return e.payload.cwd;
+    } catch {}
+  }
+  return;
+}
 function readCodexUsage(options) {
   return options.mode === "mentions" ? readCodexMentions(options) : readCodexActivations(options);
 }
@@ -740,6 +801,11 @@ function readCodexActivations(options) {
   let linesRead = 0;
   const since = options.scanAllFiles ? undefined : options.since;
   for (const file of findJsonlFiles(root, since)) {
+    if (options.projectRoot) {
+      const sessionCwd = readSessionCwd(file);
+      if (!sessionCwd || !isPathInProject(sessionCwd, options.projectRoot))
+        continue;
+    }
     filesRead++;
     for (const line of readFileSync3(file, "utf8").split(`
 `)) {
@@ -765,7 +831,7 @@ function readCodexMentions(options) {
   const historyPath = expandHome(options.history ?? "~/.codex/history.jsonl");
   const counts = new Map;
   let linesRead = 0;
-  if (!existsSync(historyPath))
+  if (!existsSync2(historyPath))
     return { counts, filesRead: 0, linesRead: 0 };
   for (const line of readFileSync3(historyPath, "utf8").split(`
 `)) {
@@ -788,26 +854,40 @@ 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) {
-  const match = period.match(/^(\d+)([dwmy])$/);
-  if (!match)
-    throw new Error(`Invalid period: "${period}". Use values like 7d, 2w, 1m, 1y.`);
-  const unit = UNITS[match[2] ?? ""] ?? 1;
+  if (period === "all")
+    return Number.POSITIVE_INFINITY;
+  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
 function parseAgents(agent) {
   if (!agent)
-    throw new Error("--agent is required. Use --agent claude-code, --agent codex, or both.");
-  const normalized = agent.split(",").map((a) => a.trim()).map((a) => {
+    return ["claude-code", "codex"];
+  const normalized = 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".`);
+    throw new Error(`Unknown agent: "${a}". Use "claude-code" or "codex" (space-separated for both: -a claude-code codex).`);
   });
   return [...new Set(normalized)];
 }
@@ -816,21 +896,26 @@ function toRows(counts) {
 }
 async function runAudit(args) {
   const agents = parseAgents(args.agent);
-  const since = args.since ? new Date(`${args.since}T00:00:00`) : new Date(Date.now() - parsePeriod(args.period) * 24 * 60 * 60 * 1000);
+  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));
+  const scanAllFiles = allTime || args["scan-all-files"];
   if (Number.isNaN(since.getTime())) {
     console.error(`Invalid --since value: ${args.since}`);
     process.exit(1);
   }
+  const scope = detectScope({
+    global: args.global,
+    rootOverride: !!args.root,
+    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 results = [];
   for (const agent of agents) {
     if (agent === "claude-code") {
       const mode = args.mode ?? "attributed";
-      const result = readClaudeUsage({
-        since,
-        mode,
-        root: args.root,
-        scanAllFiles: args["scan-all-files"]
-      });
+      const result = claudeRootMissing ? { counts: new Map, filesRead: 0, linesRead: 0 } : readClaudeUsage({ since, mode, root: claudeRoot, scanAllFiles });
       results.push({
         agent,
         mode,
@@ -843,7 +928,8 @@ async function runAudit(args) {
         since,
         mode,
         root: args.root,
-        scanAllFiles: args["scan-all-files"]
+        scanAllFiles,
+        projectRoot: scope.projectRoot
       });
       results.push({
         agent,
@@ -863,9 +949,12 @@ async function runAudit(args) {
     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 since ${since.toISOString().slice(0, 10)} (${mode})`);
+${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.");
@@ -876,90 +965,176 @@ ${agent} skill usage since ${since.toISOString().slice(0, 10)} (${mode})`);
     }
   }
 }
-var auditCommand = defineCommand({
-  meta: { description: "Audit skill usage from agent session logs" },
-  args: {
-    agent: { type: "string", alias: "a", description: "claude-code, codex, or comma-separated" },
-    period: { type: "string", alias: "p", default: "7d", description: "7d, 2w, 1m, 1y" },
-    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" },
-    "scan-all-files": { type: "boolean", default: false, description: "Ignore file mtime" }
+var auditArgs = {
+  agent: {
+    type: "string",
+    alias: "a",
+    description: "claude-code, codex (default: both; pass space-separated for both)"
   },
-  async run({ args }) {
-    try {
-      await runAudit(args);
-    } catch (e) {
-      console.error(e instanceof Error ? e.message : String(e));
-      process.exit(1);
-    }
+  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 (ignore current directory)"
   }
-});
+};
 
 // src/lock/file.ts
-import {
-  copyFileSync,
-  existsSync as existsSync2,
-  mkdirSync,
-  readFileSync as readFileSync4,
-  renameSync,
-  writeFileSync
-} from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { basename, dirname, join as join3 } from "node:path";
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync4, renameSync, writeFileSync } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname2, join as join5 } from "node:path";
 function getLockPath(global) {
-  return global ? join3(homedir2(), ".agents", ".skill-lock.json") : "skills-lock.json";
+  return global ? join5(homedir3(), ".agents", ".skill-lock.json") : "skills-lock.json";
 }
 function readLock(path) {
-  if (!existsSync2(path))
+  if (!existsSync4(path))
     return { skills: {} };
   return JSON.parse(readFileSync4(path, "utf8"));
 }
 function writeLock(path, lock) {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = join3(dirname(path), `.${Date.now()}.skill-lock.json`);
+  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 getBackupPath(path) {
-  return join3(dirname(path), ".tmp", `${basename(path)}.bak`);
-}
-function backupLock(path) {
-  const backupPath = getBackupPath(path);
-  mkdirSync(dirname(backupPath), { recursive: true });
-  copyFileSync(path, backupPath);
-  return backupPath;
-}
-function removeSkillFromLock(path, skill, { skipBackup = false } = {}) {
-  if (!existsSync2(path))
+function removeSkillFromLock(path, skill) {
+  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 };
+  return { removed: true };
 }
 
+// src/utils/skill-files.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname3, join as join6, resolve as resolve2 } from "node:path";
+var CHARS_PER_TOKEN = 4;
+function getSkillPathCandidates(name, lockPath, isGlobal) {
+  if (isGlobal) {
+    return [
+      join6(homedir4(), ".claude", "skills", name, "SKILL.md"),
+      join6(homedir4(), ".agents", "skills", name, "SKILL.md")
+    ];
+  }
+  return [join6(dirname3(resolve2(lockPath)), ".claude", "skills", name, "SKILL.md")];
+}
+function findSkillFile(name, lockPath, isGlobal) {
+  for (const p of getSkillPathCandidates(name, lockPath, isGlobal)) {
+    if (existsSync5(p))
+      return p;
+  }
+  return;
+}
+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);
+}
+function countFrontmatterTokens(filePath) {
+  const content = readFileSync5(filePath, "utf8");
+  const fm = extractFrontmatter(content);
+  if (fm === undefined)
+    return;
+  return estimateTokens(fm);
+}
+
+// src/commands/cost.ts
+var costCommand = defineCommand({
+  meta: {
+    description: "Estimate ambient token cost (frontmatter) of each skill in the lock file"
+  },
+  args: {
+    global: { type: "boolean", alias: "g", default: false, description: "Use global lock file" },
+    json: { type: "boolean", default: false, description: "Output as JSON" }
+  },
+  run({ args }) {
+    const lockPath = getLockPath(args.global);
+    const lock = readLock(lockPath);
+    const names = Object.keys(lock.skills).sort();
+    const rows = names.map((skill) => {
+      const file = findSkillFile(skill, lockPath, args.global);
+      if (!file)
+        return { skill, tokens: "missing" };
+      const tokens = countFrontmatterTokens(file);
+      if (tokens === undefined)
+        return { skill, tokens: "no-frontmatter" };
+      return { skill, tokens };
+    });
+    if (args.json) {
+      console.log(JSON.stringify(rows, null, 2));
+      return;
+    }
+    if (rows.length === 0) {
+      console.log(`No skills in ${lockPath}`);
+      return;
+    }
+    const nameWidth = Math.max(...rows.map((r) => r.skill.length));
+    let total = 0;
+    let missing = 0;
+    for (const r of rows) {
+      let cell;
+      if (typeof r.tokens === "number") {
+        cell = `~${r.tokens} tok`;
+        total += r.tokens;
+      } else if (r.tokens === "missing") {
+        cell = "missing";
+        missing += 1;
+      } else {
+        cell = "(no frontmatter)";
+      }
+      console.log(`${r.skill.padEnd(nameWidth)}  ${cell}`);
+    }
+    console.log("");
+    const tail = missing > 0 ? ` (${missing} missing)` : "";
+    console.log(`Total: ~${total} tok across ${rows.length} skills${tail}`);
+  }
+});
+
 // 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" }
+    global: { type: "boolean", alias: "g", default: false, description: "Use global lock file" },
+    json: { type: "boolean", default: false, description: "Output as JSON array" }
   },
   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));
+    if (args.json) {
+      console.log(JSON.stringify(skills, null, 2));
+      return;
+    }
+    if (skills.length === 0) {
+      console.log(`No skills in ${path}`);
+      return;
+    }
+    for (const skill of skills)
+      console.log(skill);
+    console.log("");
+    console.log(`Total: ${skills.length} skill${skills.length === 1 ? "" : "s"} in ${path}`);
   }
 });
 
 // src/commands/remove.ts
-import { existsSync as existsSync3 } from "node:fs";
 var removeCommand = defineCommand({
   meta: { description: "Remove one or more skills from the lock file" },
   args: {
@@ -981,42 +1156,170 @@ var removeCommand = defineCommand({
       }
       return;
     }
-    const backupPath = existsSync3(path) ? backupLock(path) : undefined;
     for (const skill of skills) {
-      const result = removeSkillFromLock(path, skill, { skipBackup: true });
+      const result = removeSkillFromLock(path, skill);
       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/utils/update-check.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "node:fs";
+import { get } from "node:https";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname4, join as join7 } from "node:path";
+var PKG = "skillio";
+var TTL_MS = 24 * 60 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 1500;
+function getCachePath() {
+  return join7(homedir5(), ".cache", "skillio", "version.json");
+}
+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 readCache(path = getCachePath()) {
+  try {
+    return JSON.parse(readFileSync6(path, "utf8"));
+  } catch {
+    return;
+  }
+}
+function writeCache(cache, path = getCachePath()) {
+  try {
+    mkdirSync2(dirname4(path), { recursive: true });
+    writeFileSync2(path, JSON.stringify(cache));
+  } catch {}
+}
+function fetchLatest() {
+  return new Promise((resolve3) => {
+    const req = get(`https://registry.npmjs.org/${PKG}/latest`, { timeout: FETCH_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        resolve3(undefined);
+        return;
+      }
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          const data = JSON.parse(body);
+          resolve3(typeof data.version === "string" ? data.version : undefined);
+        } catch {
+          resolve3(undefined);
+        }
+      });
+    });
+    req.on("error", () => resolve3(undefined));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve3(undefined);
+    });
+  });
+}
+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/cli.ts
 var { version } = createRequire(import.meta.url)("../package.json");
-var SUBCOMMANDS = new Set(["audit", "list", "ls", "remove", "rm"]);
-var HELP_FLAGS = new Set(["--help", "-h", "--version", "-v"]);
-var firstArg = process.argv[2];
-if (firstArg === undefined || !SUBCOMMANDS.has(firstArg) && !HELP_FLAGS.has(firstArg)) {
-  process.argv.splice(2, 0, "audit");
+if (process.argv[2] === "audit") {
+  process.argv.splice(2, 1);
 }
+function mergeAgentArgs(argv) {
+  const out = [];
+  const values = [];
+  let slotIdx = -1;
+  let i = 0;
+  while (i < argv.length) {
+    const tok = argv[i];
+    if (tok === undefined) {
+      i++;
+      continue;
+    }
+    if (tok === "-a" || tok === "--agent") {
+      if (slotIdx === -1)
+        slotIdx = out.length;
+      let j = i + 1;
+      while (j < argv.length) {
+        const next = argv[j];
+        if (next === undefined || next.startsWith("-"))
+          break;
+        values.push(next);
+        j++;
+      }
+      i = j;
+      continue;
+    }
+    out.push(tok);
+    i++;
+  }
+  if (values.length > 0 && slotIdx !== -1)
+    out.splice(slotIdx, 0, "--agent", values.join("\x1F"));
+  return out;
+}
+process.argv = mergeAgentArgs(process.argv);
+var SUBCOMMAND_NAMES = new Set(["list", "ls", "remove", "rm", "cost"]);
 var main = defineCommand({
   meta: {
     name: "skillio",
     version,
     description: "Audit and manage AI agent skills"
   },
+  args: auditArgs,
+  async run({ args }) {
+    if (SUBCOMMAND_NAMES.has(process.argv[2] ?? ""))
+      return;
+    try {
+      await runAudit(args);
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  },
   subCommands: {
-    audit: auditCommand,
     list: listCommand,
     ls: listCommand,
     remove: removeCommand,
-    rm: removeCommand
+    rm: removeCommand,
+    cost: costCommand
   }
 });
-runMain(main);
+(async () => {
+  await maybePrintUpdateNotice(version);
+  runMain(main);
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillio",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Audit and manage AI agent skills for Claude Code and Codex",
   "license": "MIT",
   "author": "ihororlovskyi",
@@ -23,7 +23,8 @@
   ],
   "type": "module",
   "bin": {
-    "skillio": "dist/cli.js"
+    "skillio": "dist/cli.js",
+    "skl": "dist/cli.js"
   },
   "exports": {
     ".": {