skillio 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ihororlovskyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# skillio
+
+[![npm version](https://img.shields.io/npm/v/skillio)](https://www.npmjs.com/package/skillio)
+[![CI](https://github.com/ihororlovskyi/skillio/actions/workflows/ci.yml/badge.svg)](https://github.com/ihororlovskyi/skillio/actions/workflows/ci.yml)
+
+Audit and manage AI agent skills for Claude Code and OpenAI Codex.
+
+## Installation
+
+```sh
+# one-off (no install needed)
+npx skillio audit --agent claude --period 7d
+pnpm dlx skillio audit --agent codex --period 2w
+
+# global install
+npm install -g skillio
+pnpm add -g skillio
+```
+
+## 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
+skillio remove brainstorming writing-plans  # remove multiple skills
+skillio remove --dry-run brainstorming     # preview removal
+```
+
+## 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
+
+## Options
+
+### `skillio` / `skillio audit`
+
+Audits skill usage from agent session logs. `audit` is the default subcommand when the first argument is an audit flag.
+
+```sh
+skillio --agent claude --period 7d
+skillio audit --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` |
+| `--since` | — | `yyyy-mm-dd`, overrides `--period` |
+| `--mode` | `attributed` | `attributed` \| `activations` \| `mentions` |
+| `--format` | `text` | `text` \| `json` |
+| `--root` | — | Override agent sessions directory |
+| `--scan-all-files` | — | Ignore file mtime, read everything |
+
+### Modes
+
+- **`attributed`** — entries with an `attributionSkill` field set by Claude Code. This is the default and most reliable Claude mode.
+- **`activations`** — explicit `Skill` tool invocations found anywhere in the entry tree (Claude) or `exec_command_end` events / `<skill>` XML (Codex). This is the default and most reliable Codex mode.
+- **`mentions`** — skill paths (`foo/SKILL.md`) or `superpowers:name` strings found in any string value. This is a broad search mode and can include examples from prompts, specs, or documentation.
+
+### `skillio list` / `ls`
+
+```sh
+skillio list            # local skills-lock.json
+skillio list --global   # ~/.agents/.skill-lock.json
+```
+
+### `skillio remove` / `rm`
+
+```sh
+skillio remove <skill-name>
+skillio remove <skill-one> <skill-two>
+skillio remove --global <skill-name>
+skillio remove --dry-run <skill-name>
+```
+
+## Requirements
+
+- Node.js ≥ 20

package/dist/cli.js

@@ -0,0 +1,1018 @@
+#!/usr/bin/env node
+
+// node_modules/citty/dist/_chunks/libs/scule.mjs
+var NUMBER_CHAR_RE = /\d/;
+var STR_SPLITTERS = [
+  "-",
+  "_",
+  "/",
+  "."
+];
+function isUppercase(char = "") {
+  if (NUMBER_CHAR_RE.test(char))
+    return;
+  return char !== char.toLowerCase();
+}
+function splitByCase(str, separators) {
+  const splitters = separators ?? STR_SPLITTERS;
+  const parts = [];
+  if (!str || typeof str !== "string")
+    return parts;
+  let buff = "";
+  let previousUpper;
+  let previousSplitter;
+  for (const char of str) {
+    const isSplitter = splitters.includes(char);
+    if (isSplitter === true) {
+      parts.push(buff);
+      buff = "";
+      previousUpper = undefined;
+      continue;
+    }
+    const isUpper = isUppercase(char);
+    if (previousSplitter === false) {
+      if (previousUpper === false && isUpper === true) {
+        parts.push(buff);
+        buff = char;
+        previousUpper = isUpper;
+        continue;
+      }
+      if (previousUpper === true && isUpper === false && buff.length > 1) {
+        const lastChar = buff.at(-1);
+        parts.push(buff.slice(0, Math.max(0, buff.length - 1)));
+        buff = lastChar + char;
+        previousUpper = isUpper;
+        continue;
+      }
+    }
+    buff += char;
+    previousUpper = isUpper;
+    previousSplitter = isSplitter;
+  }
+  parts.push(buff);
+  return parts;
+}
+function upperFirst(str) {
+  return str ? str[0].toUpperCase() + str.slice(1) : "";
+}
+function lowerFirst(str) {
+  return str ? str[0].toLowerCase() + str.slice(1) : "";
+}
+function pascalCase(str, opts) {
+  return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => upperFirst(opts?.normalize ? p.toLowerCase() : p)).join("") : "";
+}
+function camelCase(str, opts) {
+  return lowerFirst(pascalCase(str || "", opts));
+}
+function kebabCase(str, joiner) {
+  return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => p.toLowerCase()).join(joiner ?? "-") : "";
+}
+function snakeCase(str) {
+  return kebabCase(str || "", "_");
+}
+
+// node_modules/citty/dist/index.mjs
+import { parseArgs as parseArgs$1 } from "node:util";
+function toArray(val) {
+  if (Array.isArray(val))
+    return val;
+  return val === undefined ? [] : [val];
+}
+function formatLineColumns(lines, linePrefix = "") {
+  const maxLength = [];
+  for (const line of lines)
+    for (const [i, element] of line.entries())
+      maxLength[i] = Math.max(maxLength[i] || 0, element.length);
+  return lines.map((l) => l.map((c, i) => linePrefix + c[i === 0 ? "padStart" : "padEnd"](maxLength[i])).join("  ")).join(`
+`);
+}
+function resolveValue(input) {
+  return typeof input === "function" ? input() : input;
+}
+var CLIError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "CLIError";
+    this.code = code;
+  }
+};
+function parseRawArgs(args = [], opts = {}) {
+  const booleans = new Set(opts.boolean || []);
+  const strings = new Set(opts.string || []);
+  const aliasMap = opts.alias || {};
+  const defaults = opts.default || {};
+  const aliasToMain = /* @__PURE__ */ new Map;
+  const mainToAliases = /* @__PURE__ */ new Map;
+  for (const [key, value] of Object.entries(aliasMap)) {
+    const targets = value;
+    for (const target of targets) {
+      aliasToMain.set(key, target);
+      if (!mainToAliases.has(target))
+        mainToAliases.set(target, []);
+      mainToAliases.get(target).push(key);
+      aliasToMain.set(target, key);
+      if (!mainToAliases.has(key))
+        mainToAliases.set(key, []);
+      mainToAliases.get(key).push(target);
+    }
+  }
+  const options = {};
+  function getType(name) {
+    if (booleans.has(name))
+      return "boolean";
+    const aliases = mainToAliases.get(name) || [];
+    for (const alias of aliases)
+      if (booleans.has(alias))
+        return "boolean";
+    return "string";
+  }
+  function isStringType(name) {
+    if (strings.has(name))
+      return true;
+    const aliases = mainToAliases.get(name) || [];
+    for (const alias of aliases)
+      if (strings.has(alias))
+        return true;
+    return false;
+  }
+  const allOptions = new Set([
+    ...booleans,
+    ...strings,
+    ...Object.keys(aliasMap),
+    ...Object.values(aliasMap).flat(),
+    ...Object.keys(defaults)
+  ]);
+  for (const name of allOptions)
+    if (!options[name])
+      options[name] = {
+        type: getType(name),
+        default: defaults[name]
+      };
+  for (const [alias, main] of aliasToMain.entries())
+    if (alias.length === 1 && options[main] && !options[main].short)
+      options[main].short = alias;
+  const processedArgs = [];
+  const negatedFlags = {};
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") {
+      processedArgs.push(...args.slice(i));
+      break;
+    }
+    if (arg.startsWith("--no-")) {
+      const flagName = arg.slice(5);
+      negatedFlags[flagName] = true;
+      continue;
+    }
+    processedArgs.push(arg);
+  }
+  let parsed;
+  try {
+    parsed = parseArgs$1({
+      args: processedArgs,
+      options: Object.keys(options).length > 0 ? options : undefined,
+      allowPositionals: true,
+      strict: false
+    });
+  } catch {
+    parsed = {
+      values: {},
+      positionals: processedArgs
+    };
+  }
+  const out = { _: [] };
+  out._ = parsed.positionals;
+  for (const [key, value] of Object.entries(parsed.values)) {
+    let coerced = value;
+    if (getType(key) === "boolean" && typeof value === "string")
+      coerced = value !== "false";
+    else if (isStringType(key) && typeof value === "boolean")
+      coerced = "";
+    out[key] = coerced;
+  }
+  for (const [name] of Object.entries(negatedFlags)) {
+    out[name] = false;
+    const mainName = aliasToMain.get(name);
+    if (mainName)
+      out[mainName] = false;
+    const aliases = mainToAliases.get(name);
+    if (aliases)
+      for (const alias of aliases)
+        out[alias] = false;
+  }
+  for (const [alias, main] of aliasToMain.entries()) {
+    if (out[alias] !== undefined && out[main] === undefined)
+      out[main] = out[alias];
+    if (out[main] !== undefined && out[alias] === undefined)
+      out[alias] = out[main];
+    if (out[alias] !== out[main] && defaults[main] === out[main])
+      out[main] = out[alias];
+  }
+  return out;
+}
+var noColor = /* @__PURE__ */ (() => {
+  const env = globalThis.process?.env ?? {};
+  return env.NO_COLOR === "1" || env.TERM === "dumb" || env.TEST || env.CI;
+})();
+var _c = (c, r = 39) => (t) => noColor ? t : `\x1B[${c}m${t}\x1B[${r}m`;
+var bold = /* @__PURE__ */ _c(1, 22);
+var cyan = /* @__PURE__ */ _c(36);
+var gray = /* @__PURE__ */ _c(90);
+var underline = /* @__PURE__ */ _c(4, 24);
+function parseArgs(rawArgs, argsDef) {
+  const parseOptions = {
+    boolean: [],
+    string: [],
+    alias: {},
+    default: {}
+  };
+  const args = resolveArgs(argsDef);
+  for (const arg of args) {
+    if (arg.type === "positional")
+      continue;
+    if (arg.type === "string" || arg.type === "enum")
+      parseOptions.string.push(arg.name);
+    else if (arg.type === "boolean")
+      parseOptions.boolean.push(arg.name);
+    if (arg.default !== undefined)
+      parseOptions.default[arg.name] = arg.default;
+    if (arg.alias)
+      parseOptions.alias[arg.name] = arg.alias;
+    const camelName = camelCase(arg.name);
+    const kebabName = kebabCase(arg.name);
+    if (camelName !== arg.name || kebabName !== arg.name) {
+      const existingAliases = toArray(parseOptions.alias[arg.name] || []);
+      if (camelName !== arg.name && !existingAliases.includes(camelName))
+        existingAliases.push(camelName);
+      if (kebabName !== arg.name && !existingAliases.includes(kebabName))
+        existingAliases.push(kebabName);
+      if (existingAliases.length > 0)
+        parseOptions.alias[arg.name] = existingAliases;
+    }
+  }
+  const parsed = parseRawArgs(rawArgs, parseOptions);
+  const [...positionalArguments] = parsed._;
+  const parsedArgsProxy = new Proxy(parsed, { get(target, prop) {
+    return target[prop] ?? target[camelCase(prop)] ?? target[kebabCase(prop)];
+  } });
+  for (const [, arg] of args.entries())
+    if (arg.type === "positional") {
+      const nextPositionalArgument = positionalArguments.shift();
+      if (nextPositionalArgument !== undefined)
+        parsedArgsProxy[arg.name] = nextPositionalArgument;
+      else if (arg.default === undefined && arg.required !== false)
+        throw new CLIError(`Missing required positional argument: ${arg.name.toUpperCase()}`, "EARG");
+      else
+        parsedArgsProxy[arg.name] = arg.default;
+    } else if (arg.type === "enum") {
+      const argument = parsedArgsProxy[arg.name];
+      const options = arg.options || [];
+      if (argument !== undefined && options.length > 0 && !options.includes(argument))
+        throw new CLIError(`Invalid value for argument: ${cyan(`--${arg.name}`)} (${cyan(argument)}). Expected one of: ${options.map((o) => cyan(o)).join(", ")}.`, "EARG");
+    } else if (arg.required && parsedArgsProxy[arg.name] === undefined)
+      throw new CLIError(`Missing required argument: --${arg.name}`, "EARG");
+  return parsedArgsProxy;
+}
+function resolveArgs(argsDef) {
+  const args = [];
+  for (const [name, argDef] of Object.entries(argsDef || {}))
+    args.push({
+      ...argDef,
+      name,
+      alias: toArray(argDef.alias)
+    });
+  return args;
+}
+async function resolvePlugins(plugins) {
+  return Promise.all(plugins.map((p) => resolveValue(p)));
+}
+function defineCommand(def) {
+  return def;
+}
+async function runCommand(cmd, opts) {
+  const cmdArgs = await resolveValue(cmd.args || {});
+  const parsedArgs = parseArgs(opts.rawArgs, cmdArgs);
+  const context = {
+    rawArgs: opts.rawArgs,
+    args: parsedArgs,
+    data: opts.data,
+    cmd
+  };
+  const plugins = await resolvePlugins(cmd.plugins ?? []);
+  let result;
+  let runError;
+  try {
+    for (const plugin of plugins)
+      await plugin.setup?.(context);
+    if (typeof cmd.setup === "function")
+      await cmd.setup(context);
+    const subCommands = await resolveValue(cmd.subCommands);
+    if (subCommands && Object.keys(subCommands).length > 0) {
+      const subCommandArgIndex = findSubCommandIndex(opts.rawArgs, cmdArgs);
+      const explicitName = opts.rawArgs[subCommandArgIndex];
+      if (explicitName) {
+        const subCommand = await _findSubCommand(subCommands, explicitName);
+        if (!subCommand)
+          throw new CLIError(`Unknown command ${cyan(explicitName)}`, "E_UNKNOWN_COMMAND");
+        await runCommand(subCommand, { rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1) });
+      } else {
+        const defaultSubCommand = await resolveValue(cmd.default);
+        if (defaultSubCommand) {
+          if (cmd.run)
+            throw new CLIError(`Cannot specify both 'run' and 'default' on the same command.`, "E_DEFAULT_CONFLICT");
+          const subCommand = await _findSubCommand(subCommands, defaultSubCommand);
+          if (!subCommand)
+            throw new CLIError(`Default sub command ${cyan(defaultSubCommand)} not found in subCommands.`, "E_UNKNOWN_COMMAND");
+          await runCommand(subCommand, { rawArgs: opts.rawArgs });
+        } else if (!cmd.run)
+          throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+      }
+    }
+    if (typeof cmd.run === "function")
+      result = await cmd.run(context);
+  } catch (error) {
+    runError = error;
+  }
+  const cleanupErrors = [];
+  if (typeof cmd.cleanup === "function")
+    try {
+      await cmd.cleanup(context);
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  for (const plugin of [...plugins].reverse())
+    try {
+      await plugin.cleanup?.(context);
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+  if (runError)
+    throw runError;
+  if (cleanupErrors.length === 1)
+    throw cleanupErrors[0];
+  if (cleanupErrors.length > 1)
+    throw new Error("Multiple cleanup errors", { cause: cleanupErrors });
+  return { result };
+}
+async function resolveSubCommand(cmd, rawArgs, parent) {
+  const subCommands = await resolveValue(cmd.subCommands);
+  if (subCommands && Object.keys(subCommands).length > 0) {
+    const subCommandArgIndex = findSubCommandIndex(rawArgs, await resolveValue(cmd.args || {}));
+    const subCommandName = rawArgs[subCommandArgIndex];
+    const subCommand = await _findSubCommand(subCommands, subCommandName);
+    if (subCommand)
+      return resolveSubCommand(subCommand, rawArgs.slice(subCommandArgIndex + 1), cmd);
+  }
+  return [cmd, parent];
+}
+async function _findSubCommand(subCommands, name) {
+  if (name in subCommands)
+    return resolveValue(subCommands[name]);
+  for (const sub of Object.values(subCommands)) {
+    const resolved = await resolveValue(sub);
+    const meta = await resolveValue(resolved?.meta);
+    if (meta?.alias) {
+      if (toArray(meta.alias).includes(name))
+        return resolved;
+    }
+  }
+}
+function findSubCommandIndex(rawArgs, argsDef) {
+  for (let i = 0;i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--")
+      return -1;
+    if (arg.startsWith("-")) {
+      if (!arg.includes("=") && _isValueFlag(arg, argsDef))
+        i++;
+      continue;
+    }
+    return i;
+  }
+  return -1;
+}
+function _isValueFlag(flag, argsDef) {
+  const name = flag.replace(/^-{1,2}/, "");
+  const normalized = camelCase(name);
+  for (const [key, def] of Object.entries(argsDef)) {
+    if (def.type !== "string" && def.type !== "enum")
+      continue;
+    if (normalized === camelCase(key))
+      return true;
+    if ((Array.isArray(def.alias) ? def.alias : def.alias ? [def.alias] : []).includes(name))
+      return true;
+  }
+  return false;
+}
+async function showUsage(cmd, parent) {
+  try {
+    console.log(await renderUsage(cmd, parent) + `
+`);
+  } catch (error) {
+    console.error(error);
+  }
+}
+var negativePrefixRe = /^no[-A-Z]/;
+async function renderUsage(cmd, parent) {
+  const cmdMeta = await resolveValue(cmd.meta || {});
+  const cmdArgs = resolveArgs(await resolveValue(cmd.args || {}));
+  const parentMeta = await resolveValue(parent?.meta || {});
+  const commandName = `${parentMeta.name ? `${parentMeta.name} ` : ""}` + (cmdMeta.name || process.argv[1]);
+  const argLines = [];
+  const posLines = [];
+  const commandsLines = [];
+  const usageLine = [];
+  for (const arg of cmdArgs)
+    if (arg.type === "positional") {
+      const name = arg.name.toUpperCase();
+      const isRequired = arg.required !== false && arg.default === undefined;
+      posLines.push([cyan(name + renderValueHint(arg)), renderDescription(arg, isRequired)]);
+      usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
+    } else {
+      const isRequired = arg.required === true && arg.default === undefined;
+      const argStr = [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(", ") + renderValueHint(arg);
+      argLines.push([cyan(argStr), renderDescription(arg, isRequired)]);
+      if (arg.type === "boolean" && (arg.default === true || arg.negativeDescription) && !negativePrefixRe.test(arg.name)) {
+        const negativeArgStr = [...(arg.alias || []).map((a) => `--no-${a}`), `--no-${arg.name}`].join(", ");
+        argLines.push([cyan(negativeArgStr), [arg.negativeDescription, isRequired ? gray("(Required)") : ""].filter(Boolean).join(" ")]);
+      }
+      if (isRequired)
+        usageLine.push(`--${arg.name}` + renderValueHint(arg));
+    }
+  if (cmd.subCommands) {
+    const commandNames = [];
+    const subCommands = await resolveValue(cmd.subCommands);
+    for (const [name, sub] of Object.entries(subCommands)) {
+      const meta = await resolveValue((await resolveValue(sub))?.meta);
+      if (meta?.hidden)
+        continue;
+      const aliases = toArray(meta?.alias);
+      const label = [name, ...aliases].join(", ");
+      commandsLines.push([cyan(label), meta?.description || ""]);
+      commandNames.push(name, ...aliases);
+    }
+    usageLine.push(commandNames.join("|"));
+  }
+  const usageLines = [];
+  const version = cmdMeta.version || parentMeta.version;
+  usageLines.push(gray(`${cmdMeta.description} (${commandName + (version ? ` v${version}` : "")})`), "");
+  const hasOptions = argLines.length > 0 || posLines.length > 0;
+  usageLines.push(`${underline(bold("USAGE"))} ${cyan(`${commandName}${hasOptions ? " [OPTIONS]" : ""} ${usageLine.join(" ")}`)}`, "");
+  if (posLines.length > 0) {
+    usageLines.push(underline(bold("ARGUMENTS")), "");
+    usageLines.push(formatLineColumns(posLines, "  "));
+    usageLines.push("");
+  }
+  if (argLines.length > 0) {
+    usageLines.push(underline(bold("OPTIONS")), "");
+    usageLines.push(formatLineColumns(argLines, "  "));
+    usageLines.push("");
+  }
+  if (commandsLines.length > 0) {
+    usageLines.push(underline(bold("COMMANDS")), "");
+    usageLines.push(formatLineColumns(commandsLines, "  "));
+    usageLines.push("", `Use ${cyan(`${commandName} <command> --help`)} for more information about a command.`);
+  }
+  return usageLines.filter((l) => typeof l === "string").join(`
+`);
+}
+function renderValueHint(arg) {
+  const valueHint = arg.valueHint ? `=<${arg.valueHint}>` : "";
+  const fallbackValueHint = valueHint || `=<${snakeCase(arg.name)}>`;
+  if (!arg.type || arg.type === "positional" || arg.type === "boolean")
+    return valueHint;
+  if (arg.type === "enum" && arg.options?.length)
+    return `=<${arg.options.join("|")}>`;
+  return fallbackValueHint;
+}
+function renderDescription(arg, required) {
+  const requiredHint = required ? gray("(Required)") : "";
+  const defaultHint = arg.default === undefined ? "" : gray(`(Default: ${arg.default})`);
+  return [
+    arg.description,
+    requiredHint,
+    defaultHint
+  ].filter(Boolean).join(" ");
+}
+async function runMain(cmd, opts = {}) {
+  const rawArgs = opts.rawArgs || process.argv.slice(2);
+  const showUsage$1 = opts.showUsage || showUsage;
+  try {
+    const builtinFlags = await _resolveBuiltinFlags(cmd);
+    if (builtinFlags.help.length > 0 && rawArgs.some((arg) => builtinFlags.help.includes(arg))) {
+      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
+      process.exit(0);
+    } else if (rawArgs.length === 1 && builtinFlags.version.includes(rawArgs[0])) {
+      const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
+      if (!meta?.version)
+        throw new CLIError("No version specified", "E_NO_VERSION");
+      console.log(meta.version);
+    } else
+      await runCommand(cmd, { rawArgs });
+  } catch (error) {
+    if (error instanceof CLIError) {
+      await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
+      console.error(error.message);
+    } else
+      console.error(error, `
+`);
+    process.exit(1);
+  }
+}
+async function _resolveBuiltinFlags(cmd) {
+  const argsDef = await resolveValue(cmd.args || {});
+  const userNames = /* @__PURE__ */ new Set;
+  const userAliases = /* @__PURE__ */ new Set;
+  for (const [name, def] of Object.entries(argsDef)) {
+    userNames.add(name);
+    for (const alias of toArray(def.alias))
+      userAliases.add(alias);
+  }
+  return {
+    help: _getBuiltinFlags("help", "h", userNames, userAliases),
+    version: _getBuiltinFlags("version", "v", userNames, userAliases)
+  };
+}
+function _getBuiltinFlags(long, short, userNames, userAliases) {
+  if (userNames.has(long) || userAliases.has(long))
+    return [];
+  if (userNames.has(short) || userAliases.has(short))
+    return [`--${long}`];
+  return [`--${long}`, `-${short}`];
+}
+
+// src/readers/claude.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+
+// src/utils/walk.ts
+function walk(value, visit) {
+  visit(value);
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, visit);
+  } else if (value !== null && typeof value === "object") {
+    for (const item of Object.values(value))
+      walk(item, visit);
+  }
+}
+
+// src/extractors/activations.ts
+function extractClaudeActivations(entry) {
+  const skills = [];
+  walk(entry, (node) => {
+    if (typeof node !== "object" || node === null)
+      return;
+    const n = node;
+    if (n.type === "tool_use" && n.name === "Skill" && typeof n.input === "object") {
+      const skill = n.input.skill;
+      if (typeof skill === "string")
+        skills.push(skill);
+    }
+  });
+  return skills;
+}
+function skillNameFromPath(p) {
+  const parts = p.replace("/SKILL.md", "").split("/");
+  return parts[parts.length - 1] ?? null;
+}
+function extractCodexActivations(entry) {
+  if (typeof entry !== "object" || entry === null)
+    return [];
+  const e = entry;
+  const payload = e.payload;
+  if (e.type === "response_item" && payload?.type === "message" && payload?.role === "user") {
+    const skills = new Set;
+    const content = payload?.content ?? [];
+    for (const item of content) {
+      const i = item;
+      if (i.type === "input_text" && typeof i.text === "string") {
+        for (const m of i.text.matchAll(/<skill>\s*<name>([^<]+)<\/name>/g)) {
+          if (m[1] !== undefined)
+            skills.add(m[1]);
+        }
+      }
+    }
+    return [...skills];
+  }
+  if (e.type === "event_msg" && payload?.type === "exec_command_end") {
+    const cmds = payload?.parsed_cmd ?? [];
+    const paths = new Set;
+    for (const cmd of cmds) {
+      if (typeof cmd.path === "string" && cmd.path.endsWith("/SKILL.md")) {
+        paths.add(cmd.path);
+      }
+    }
+    return [...paths].map(skillNameFromPath).filter((s) => s !== null);
+  }
+  return [];
+}
+
+// src/extractors/attributed.ts
+function extractAttributed(entry) {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+    return [];
+  const skill = entry.attributionSkill;
+  return typeof skill === "string" ? [skill] : [];
+}
+
+// src/extractors/mentions.ts
+function extractClaudeMentions(entry) {
+  const seen = new Set;
+  walk(entry, (node) => {
+    if (typeof node !== "string")
+      return;
+    for (const m of node.matchAll(/(?:^|[":\s])((?:[a-z0-9-]+:)?[a-z0-9][a-z0-9-]{1,})\/SKILL\.md\b/g)) {
+      if (m[1] !== undefined)
+        seen.add(m[1]);
+    }
+    for (const m of node.matchAll(/\bsuperpowers:([a-z0-9-]+)\b/g)) {
+      if (m[1] !== undefined)
+        seen.add(`superpowers:${m[1]}`);
+    }
+  });
+  return [...seen];
+}
+function extractCodexMentions(entry) {
+  const seen = new Set;
+  walk(entry, (node) => {
+    if (typeof node !== "string")
+      return;
+    for (const m of node.matchAll(/\/([^/)\]\s]+)\/SKILL\.md\b/g)) {
+      if (m[1] !== undefined)
+        seen.add(m[1]);
+    }
+    for (const m of node.matchAll(/\$([a-z0-9][a-z0-9-]{1,})\b/g)) {
+      if (m[1] !== undefined)
+        seen.add(m[1]);
+    }
+  });
+  return [...seen];
+}
+
+// src/utils/expand-home.ts
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+function expandHome(p) {
+  if (p === "~")
+    return homedir();
+  if (p.startsWith("~/"))
+    return join(homedir(), p.slice(2));
+  return resolve(p);
+}
+
+// src/utils/jsonl.ts
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join as join2 } from "node:path";
+function* findJsonlFiles(dir, since) {
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const path = join2(dir, item.name);
+    if (item.isDirectory()) {
+      yield* findJsonlFiles(path, since);
+    } else if (item.isFile() && item.name.endsWith(".jsonl")) {
+      if (!since || statSync(path).mtime >= since)
+        yield path;
+    }
+  }
+}
+function isRecentEntry(entry, since) {
+  if (typeof entry !== "object" || entry === null)
+    return true;
+  const e = entry;
+  if (typeof e.timestamp === "string") {
+    const d = new Date(e.timestamp);
+    return Number.isNaN(d.getTime()) || d >= since;
+  }
+  if (typeof e.ts === "number")
+    return new Date(e.ts * 1000) >= since;
+  return true;
+}
+
+// src/readers/claude.ts
+function extractSkills(entry, mode) {
+  if (mode === "attributed")
+    return extractAttributed(entry);
+  if (mode === "activations")
+    return extractClaudeActivations(entry);
+  return extractClaudeMentions(entry);
+}
+function readClaudeUsage(options) {
+  const root = expandHome(options.root ?? "~/.claude/projects");
+  const counts = new Map;
+  let filesRead = 0;
+  let linesRead = 0;
+  const since = options.scanAllFiles ? undefined : options.since;
+  for (const file of findJsonlFiles(root, since)) {
+    filesRead++;
+    for (const line of readFileSync2(file, "utf8").split(`
+`)) {
+      if (!line.trim())
+        continue;
+      linesRead++;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!isRecentEntry(entry, options.since))
+        continue;
+      for (const skill of extractSkills(entry, options.mode)) {
+        counts.set(skill, (counts.get(skill) ?? 0) + 1);
+      }
+    }
+  }
+  return { counts, filesRead, linesRead };
+}
+
+// src/readers/codex.ts
+import { existsSync, readFileSync as readFileSync3 } from "node:fs";
+function readCodexUsage(options) {
+  return options.mode === "mentions" ? readCodexMentions(options) : readCodexActivations(options);
+}
+function readCodexActivations(options) {
+  const root = expandHome(options.root ?? "~/.codex/sessions");
+  const counts = new Map;
+  let filesRead = 0;
+  let linesRead = 0;
+  const since = options.scanAllFiles ? undefined : options.since;
+  for (const file of findJsonlFiles(root, since)) {
+    filesRead++;
+    for (const line of readFileSync3(file, "utf8").split(`
+`)) {
+      if (!line.trim())
+        continue;
+      linesRead++;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!isRecentEntry(entry, options.since))
+        continue;
+      for (const skill of extractCodexActivations(entry)) {
+        counts.set(skill, (counts.get(skill) ?? 0) + 1);
+      }
+    }
+  }
+  return { counts, filesRead, linesRead };
+}
+function readCodexMentions(options) {
+  const historyPath = expandHome(options.history ?? "~/.codex/history.jsonl");
+  const counts = new Map;
+  let linesRead = 0;
+  if (!existsSync(historyPath))
+    return { counts, filesRead: 0, linesRead: 0 };
+  for (const line of readFileSync3(historyPath, "utf8").split(`
+`)) {
+    if (!line.trim())
+      continue;
+    linesRead++;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecentEntry(entry, options.since))
+      continue;
+    for (const skill of extractCodexMentions(entry)) {
+      counts.set(skill, (counts.get(skill) ?? 0) + 1);
+    }
+  }
+  return { counts, filesRead: 1, linesRead };
+}
+
+// src/utils/period.ts
+var UNITS = { d: 1, w: 7, m: 30, y: 365 };
+var MS_PER_DAY = 24 * 60 * 60 * 1000;
+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;
+  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) => {
+    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".`);
+  });
+  return [...new Set(normalized)];
+}
+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) {
+  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);
+  if (Number.isNaN(since.getTime())) {
+    console.error(`Invalid --since value: ${args.since}`);
+    process.exit(1);
+  }
+  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"]
+      });
+      results.push({
+        agent,
+        mode,
+        rows: toRows(result.counts),
+        stats: { filesRead: result.filesRead, linesRead: result.linesRead }
+      });
+    } else {
+      const mode = args.mode ?? "activations";
+      const result = readCodexUsage({
+        since,
+        mode,
+        root: args.root,
+        scanAllFiles: args["scan-all-files"]
+      });
+      results.push({
+        agent,
+        mode,
+        rows: toRows(result.counts),
+        stats: { filesRead: result.filesRead, linesRead: result.linesRead }
+      });
+    }
+  }
+  if (args.format === "json") {
+    const output = results.map(({ agent, mode, rows }) => ({
+      agent,
+      mode,
+      since: since.toISOString(),
+      skills: rows
+    }));
+    console.log(JSON.stringify(output.length === 1 ? output[0] : output, null, 2));
+    return;
+  }
+  for (const { agent, mode, rows, stats } of results) {
+    console.log(`
+${agent} skill usage since ${since.toISOString().slice(0, 10)} (${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}`);
+    }
+  }
+}
+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" }
+  },
+  async run({ args }) {
+    try {
+      await runAudit(args);
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : String(e));
+      process.exit(1);
+    }
+  }
+});
+
+// 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";
+function getLockPath(global) {
+  return global ? join3(homedir2(), ".agents", ".skill-lock.json") : "skills-lock.json";
+}
+function readLock(path) {
+  if (!existsSync2(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`);
+  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))
+    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 };
+}
+
+// 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));
+  }
+});
+
+// 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: {
+    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 = existsSync3(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 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");
+}
+var main = defineCommand({
+  meta: {
+    name: "skillio",
+    version: "0.1.1",
+    description: "Audit and manage AI agent skills"
+  },
+  subCommands: {
+    audit: auditCommand,
+    list: listCommand,
+    ls: listCommand,
+    remove: removeCommand,
+    rm: removeCommand
+  }
+});
+runMain(main);

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "skillio",
+  "version": "0.1.1",
+  "description": "Audit and manage AI agent skills for Claude Code and Codex",
+  "license": "MIT",
+  "author": "ihororlovskyi",
+  "homepage": "https://github.com/ihororlovskyi/skillio#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ihororlovskyi/skillio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ihororlovskyi/skillio/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "claude",
+    "codex",
+    "audit",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "skillio": "dist/cli.js",
+    "skl": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "~/.bun/bin/bun run node_modules/.bin/bunup",
+    "lint": "biome check src/",
+    "format": "biome format --write src/",
+    "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "release": "changeset publish",
+    "prepublishOnly": "biome check src/ && vitest run && ~/.bun/bin/bun run node_modules/.bin/bunup && vitest run --config vitest.e2e.config.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^25.6.2",
+    "bunup": "^0.16.31",
+    "citty": "^0.2.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}