skillio 0.1.12 → 0.1.14

package/README.md

@@ -2,6 +2,11 @@
 
 [![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)
+[![CodeQL](https://github.com/ihororlovskyi/skillio/actions/workflows/codeql.yml/badge.svg)](https://github.com/ihororlovskyi/skillio/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ihororlovskyi/skillio/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ihororlovskyi/skillio)
+[![codecov](https://codecov.io/gh/ihororlovskyi/skillio/branch/main/graph/badge.svg)](https://codecov.io/gh/ihororlovskyi/skillio)
+[![license](https://img.shields.io/npm/l/skillio)](https://github.com/ihororlovskyi/skillio/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/skillio)](https://www.npmjs.com/package/skillio)
 
 Audit and manage AI agent skills for Claude Code and OpenAI Codex.
 
@@ -73,13 +78,16 @@ skillio                                # equivalent
 # subcommands
 skl ls                                 # list skills per source with diffs
 skl cost                               # ambient ballast cost (frontmatter tokens) per skill
-skl cst                                # alias for cost
+skl cs                                 # alias for cost (also: cst)
 skl usage                              # consumption: usage count × frontmatter tokens
 skl usg                                # alias for usage
-skl rm brainstorming                   # remove from lock + delete on-disk dir (with Y/n prompt)
+skl rm brainstorming                   # delete on-disk dir; lock kept (Y/n prompt)
 skl rm brainstorming writing-plans     # remove multiple
+skl rm .                               # remove all skills in scope (lock kept)
+skl rm . -fl                           # remove all, including lock entries
 skl rm --yes brainstorming             # skip confirmation
 skl rm --dry-run brainstorming         # preview only
+skl rm --force-lock brainstorming      # also remove the lock entry (-fl)
 
 # scope flags
 skl -g                                 # force global scope on any subcommand
@@ -114,7 +122,7 @@ skl usage -a claude -a codex           # equivalent: repeated --agent flag
 | `-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` |
+| `-p, --period` | `all` | Period for `usage`: `60s`, `30m`, `12h`, `7d`, `2w`, `6mo`, `all` (note: `1m` = 1 minute, `1mo` = 30 days) |
 | `-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`
@@ -129,9 +137,9 @@ skillio usage --agent codex --mode activations
 | Flag | Default | Description |
 |------|---------|-------------|
 | `-a, --agent` | both | `claude-code`/`claude`, `codex` |
-| `-p, --period` | `all` | `7d`, `2w`, `1m`, `1y`, `all` |
+| `-p, --period` | `all` | `60s`, `30m`, `24h`, `7d`, `2w`, `6mo`, `all` |
 | `--since` | — | `yyyy-mm-dd`, overrides `--period` |
-| `--mode` | `attributed` (claude) / `activations` (codex) | `attributed` \| `activations` \| `mentions` |
+| `--mode` | `merged` (claude) / `activations` (codex) | `merged` \| `attributed` \| `activations` \| `mentions` |
 | `--format` | `text` | `text` \| `json` |
 | `-g, --global` | `false` | Force global scope (ignore current directory) |
 | `--root` | — | Override agent sessions directory; implies global |
@@ -139,9 +147,10 @@ skillio usage --agent codex --mode activations
 
 ### 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.
+- **`merged`** — per-session union of `attributed` and `activations` (`max` per skill). Default for Claude.
+- **`attributed`** — entries with an `attributionSkill` field set by Claude Code.
+- **`activations`** — explicit `Skill` tool invocations (Claude) or read-like `exec_command_end` events / `<skill>` XML (Codex). Default for Codex.
+- **`mentions`** — skill paths (`foo/SKILL.md`) or `superpowers:name` strings found anywhere. Broadest signal; can include matches from prompts, specs, or documentation.
 
 ### `skillio list` / `ls`
 
@@ -150,7 +159,7 @@ skillio list            # local skills-lock.json
 skillio list --global   # ~/.agents/.skill-lock.json
 ```
 
-### `skillio cost` / `co`
+### `skillio cost` / `cs`
 
 ```sh
 skillio cost            # local: per-skill frontmatter tokens with verdict
@@ -160,13 +169,37 @@ skillio cost --global   # same, against ~/.agents/.skill-lock.json
 ### `skillio remove` / `rm`
 
 ```sh
-skillio remove <skill-name>
+skillio remove <skill-name>               # delete on-disk dir; lock kept
 skillio remove <skill-one> <skill-two>
+skillio remove .                          # remove all skills in scope (lock kept)
+skillio remove . -fl                      # remove all, including lock entries
+skillio remove --force-lock <skill-name>  # also remove the lock entry (alias -fl)
+skillio remove --lock-only <skill-name>   # only the lock entry; keep on disk
 skillio remove --global <skill-name>
-skillio remove --dry-run <skill-name>
-skillio remove --yes <skill-name>      # skip confirmation prompt
+skillio remove --dry-run <skill-name>     # preview only
+skillio remove --yes <skill-name>         # skip confirmation prompt
 ```
 
+### Shell completion
+
+`skl completion <shell>` prints a completion script. Sourced once in your
+rc-file, it tab-completes subcommands and dynamic skill names for `skl rm`.
+
+```sh
+# bash (one-time setup)
+skl completion bash >> ~/.bashrc
+
+# zsh
+skl completion zsh >> ~/.zshrc
+
+# fish
+skl completion fish | source            # one-off in current shell
+skl completion fish > ~/.config/fish/completions/skl.fish
+```
+
+`skl list --names` prints one skill name per line (no headers, no colors) and
+is what the completion script calls under the hood.
+
 ## Requirements
 
 - Node.js ≥ 20

package/dist/cli.js

@@ -558,6 +558,166 @@ function _getBuiltinFlags(long, short, userNames, userAliases) {
   return [`--${long}`, `-${short}`];
 }
 
+// src/commands/completion.ts
+var BASH = `# skillio bash completion
+# Install: source <(skl completion bash)
+_skillio_completions() {
+  local cur prev words cword
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  local cmds="list ls remove rm cost cs cst usage us usg completion"
+  if [ "\${COMP_CWORD}" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "\${cmds} -h --help -v --version" -- "\${cur}") )
+    return 0
+  fi
+
+  local sub="\${COMP_WORDS[1]}"
+  case "\${sub}" in
+    rm|remove)
+      if [[ "\${cur}" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-g --global --dry-run -y --yes --force-lock -fl --lock-only -h --help" -- "\${cur}") )
+      else
+        local names
+        local scope=""
+        for w in "\${COMP_WORDS[@]}"; do
+          if [ "\${w}" = "-g" ] || [ "\${w}" = "--global" ]; then scope="-g"; fi
+        done
+        names="$(skl list --names \${scope} 2>/dev/null)"
+        COMPREPLY=( $(compgen -W "\${names}" -- "\${cur}") )
+      fi
+      return 0
+      ;;
+    completion)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+}
+complete -F _skillio_completions skl
+complete -F _skillio_completions skillio
+`;
+var ZSH = `# skillio zsh completion
+# Install: source <(skl completion zsh)
+_skillio() {
+  local -a cmds
+  cmds=(
+    'list:List skills per source'
+    'ls:Alias for list'
+    'remove:Delete on-disk skill dirs'
+    'rm:Alias for remove'
+    'cost:Show ambient ballast cost'
+    'cs:Alias for cost'
+    'cst:Alias for cost'
+    'usage:Show skill usage'
+    'us:Alias for usage'
+    'usg:Alias for usage'
+    'completion:Print shell completion script'
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' cmds
+    return
+  fi
+  local sub=\${words[2]}
+  case $sub in
+    rm|remove)
+      if [[ \${words[CURRENT]} == -* ]]; then
+        _values 'flag' \\
+          '-g[global scope]' '--global[global scope]' \\
+          '--dry-run[print plan without deleting]' \\
+          '-y[skip confirmation]' '--yes[skip confirmation]' \\
+          '--force-lock[also remove lock entry]' '-fl[alias for --force-lock]' \\
+          '--lock-only[remove only lock entry, keep disk]'
+      else
+        local scope=""
+        for w in \${words[@]}; do
+          if [[ $w == "-g" || $w == "--global" ]]; then scope="-g"; fi
+        done
+        local -a names
+        names=(\${(f)"$(skl list --names $scope 2>/dev/null)"})
+        compadd -- $names
+      fi
+      ;;
+    completion)
+      _values 'shell' bash zsh fish
+      ;;
+  esac
+}
+compdef _skillio skl skillio
+`;
+var FISH = `# skillio fish completion
+# Install: skl completion fish | source
+function __skillio_skill_names
+  set -l scope ""
+  for w in (commandline -opc)
+    if test "$w" = "-g" -o "$w" = "--global"
+      set scope "-g"
+    end
+  end
+  skl list --names $scope 2>/dev/null
+end
+
+function __skillio_needs_command
+  set -l cmd (commandline -opc)
+  test (count $cmd) -le 1
+end
+
+function __skillio_using_subcommand
+  set -l cmd (commandline -opc)
+  if test (count $cmd) -lt 2; return 1; end
+  test "$cmd[2]" = "$argv[1]"
+end
+
+complete -c skl -n __skillio_needs_command -a 'list ls remove rm cost cs cst usage us usg completion'
+complete -c skillio -n __skillio_needs_command -a 'list ls remove rm cost cs cst usage us usg completion'
+
+for sub in rm remove
+  complete -c skl -n "__skillio_using_subcommand $sub" -f -a '(__skillio_skill_names)'
+  complete -c skillio -n "__skillio_using_subcommand $sub" -f -a '(__skillio_skill_names)'
+  complete -c skl -n "__skillio_using_subcommand $sub" -s g -l global -d 'Use global scope'
+  complete -c skl -n "__skillio_using_subcommand $sub" -l dry-run -d 'Print plan without deleting'
+  complete -c skl -n "__skillio_using_subcommand $sub" -s y -l yes -d 'Skip confirmation prompt'
+  complete -c skl -n "__skillio_using_subcommand $sub" -l force-lock -d 'Also remove lock entry'
+  complete -c skl -n "__skillio_using_subcommand $sub" -o fl -d 'Alias for --force-lock'
+  complete -c skl -n "__skillio_using_subcommand $sub" -l lock-only -d 'Remove only lock entry, keep disk'
+end
+
+for sub in completion
+  complete -c skl -n "__skillio_using_subcommand $sub" -f -a 'bash zsh fish'
+  complete -c skillio -n "__skillio_using_subcommand $sub" -f -a 'bash zsh fish'
+end
+`;
+var completionCommand = defineCommand({
+  meta: {
+    description: "Print shell completion script (bash, zsh, fish)"
+  },
+  args: {
+    shell: {
+      type: "positional",
+      required: true,
+      description: "Target shell: bash, zsh, or fish"
+    }
+  },
+  run({ args }) {
+    const shell = String(args.shell ?? "");
+    switch (shell) {
+      case "bash":
+        process.stdout.write(BASH);
+        return;
+      case "zsh":
+        process.stdout.write(ZSH);
+        return;
+      case "fish":
+        process.stdout.write(FISH);
+        return;
+      default:
+        console.error(`unknown shell: ${shell || "(none)"} — supported: bash, zsh, fish`);
+        process.exit(1);
+    }
+  }
+});
+
 // src/commands/cost.ts
 function classify(total) {
   if (total < 1000)
@@ -608,7 +768,7 @@ var costCommand = defineCommand({
       console.log(`${cyan(r.name)}${namePad}  ${tokenCell}${tokenPad}${suffix}`);
     }
     console.log("");
-    console.log(`Total: ~${total} tok across ${rows.length} skills    ${paint(message)}`);
+    console.log(`Total: ~${total} tok across ${rows.length} skills    ${paint(message)}  ·  method: chars/4, yaml-frontmatter`);
   }
 });
 
@@ -650,7 +810,12 @@ function bySource(records, roots, lockLabel) {
 var listCommand = defineCommand({
   meta: { description: "List skills per source with install-type coloring and lock orphan filter" },
   args: {
-    global: { type: "boolean", alias: "g", default: false, description: "Use global scope" }
+    global: { type: "boolean", alias: "g", default: false, description: "Use global scope" },
+    names: {
+      type: "boolean",
+      default: false,
+      description: "Print one skill name per line (no header, no colors) — for completion scripts"
+    }
   },
   run({ args }) {
     const lockPath = getLockPath(args.global);
@@ -663,6 +828,18 @@ var listCommand = defineCommand({
     };
     const lockLabel = args.global ? ".agents/.skill-lock.json" : "skills-lock.json";
     const rows = bySource(records, roots, lockLabel);
+    if (args.names) {
+      const all = new Set;
+      for (const n of rows.agents.names)
+        all.add(n.name);
+      for (const n of rows.claude.names)
+        all.add(n.name);
+      for (const n of rows.lock.names)
+        all.add(n.name);
+      for (const name of [...all].sort())
+        console.log(name);
+      return;
+    }
     console.log(args.global ? "Global" : "Local");
     const claudeSet = new Set(rows.claude.names.map((n) => n.name));
     const agentsSet = new Set(rows.agents.names.map((n) => n.name));
@@ -702,13 +879,9 @@ var listCommand = defineCommand({
     const claudeNames = rows.claude.names.map((n) => n.name);
     const agentsNames = rows.agents.names.map((n) => n.name);
     const lockNames = rows.lock.names.map((n) => n.name);
-    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 diffs = [];
-    if (lockOnly.length) {
-      diffs.push(`skills-lock.json has ${lockOnly.length} skill${lockOnly.length === 1 ? "" : "s"} missing on disk: ${lockOnly.map(cyan).join(", ")}`);
-    }
     if (claudeNotInLock.length) {
       diffs.push(`.claude/skills has ${claudeNotInLock.length} skill${claudeNotInLock.length === 1 ? "" : "s"} not in lock: ${claudeNotInLock.map(cyan).join(", ")}`);
     }
@@ -855,17 +1028,28 @@ function fileCount(dir) {
   }
   return n;
 }
-function printPlan(plan, modifyLock) {
+function printPlan(plan, modifyLock, lockOnly) {
   const { target } = plan;
   console.log(`Will remove ${q(target.name)}:`);
   if (target.inLock) {
-    if (modifyLock)
+    if (lockOnly || modifyLock)
       console.log("  - skills-lock.json");
     else
       console.log("  - skills-lock.json (kept; use --force-lock to remove lock entry)");
   } else {
     console.log("  - skills-lock.json (not in lock)");
   }
+  if (lockOnly) {
+    if (target.claudeDir)
+      console.log(`  - .claude/skills/${target.name}/  (kept; --lock-only)`);
+    else
+      console.log("  - .claude/skills/  (not found)");
+    if (target.agentsDir)
+      console.log(`  - .agents/skills/${target.name}/  (kept; --lock-only)`);
+    else
+      console.log("  - .agents/skills/  (not found)");
+    return;
+  }
   if (target.claudeDir)
     console.log(`  - .claude/skills/${target.name}/  (${plan.claudeFileCount} files)`);
   else
@@ -883,19 +1067,35 @@ var removeCommand = defineCommand({
     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" },
-    all: { type: "boolean", default: false, description: "Remove every skill in scope" },
     "force-lock": {
       type: "boolean",
       default: false,
       description: "Also remove entry from skills-lock.json (default is to keep lock untouched)"
+    },
+    "lock-only": {
+      type: "boolean",
+      default: false,
+      description: "Remove only the skills-lock.json entry; keep on-disk directories"
     }
   },
   async run({ args }) {
-    const { global: isGlobal, "dry-run": dryRun, yes, all, "force-lock": modifyLock } = args;
+    const {
+      global: isGlobal,
+      "dry-run": dryRun,
+      yes,
+      "force-lock": modifyLock,
+      "lock-only": lockOnly
+    } = args;
+    if (lockOnly && modifyLock) {
+      console.error("--lock-only is mutually exclusive with --force-lock");
+      process.exit(1);
+    }
     const subcmdIdx = process.argv.findIndex((a) => a === "remove" || a === "rm");
-    const names = process.argv.slice(subcmdIdx + 1).filter((a) => !a.startsWith("-"));
+    const rawNames = process.argv.slice(subcmdIdx + 1).filter((a) => !a.startsWith("-"));
+    const all = rawNames.includes(".");
+    const names = rawNames.filter((n) => n !== ".");
     if (all && names.length > 0) {
-      console.error("--all is mutually exclusive with positional skill names");
+      console.error('"." (all skills) is mutually exclusive with positional skill names');
       process.exit(1);
     }
     if (!all && names.length === 0) {
@@ -920,43 +1120,63 @@ var removeCommand = defineCommand({
       agentsFileCount: t.agentsDir ? fileCount(t.agentsDir) : undefined
     }));
     for (const p of plans) {
-      printPlan(p, modifyLock);
+      printPlan(p, modifyLock, lockOnly);
       console.log("");
     }
     if (dryRun)
       return;
     if (!yes) {
-      const promptText = all ? `Remove ALL ${plans.length} skills?` : "Proceed?";
-      const ok = await confirm(promptText);
+      let question = "Proceed?";
+      if (all) {
+        const subject = lockOnly ? `ALL ${plans.length} lock entries (disk preserved)` : `ALL ${plans.length} skills`;
+        question = `Remove ${subject}?`;
+      }
+      const ok = await confirm(question);
       if (!ok) {
         console.log("Aborted");
         process.exit(1);
       }
     }
     const allowedRoots = [isGlobal ? homedir2() : dirname2(resolve3(lockPath)), homedir2()];
+    const removed = (s) => red("removed") + s;
+    const kept = (s) => green("kept") + s;
+    const skipped = (s) => yellow("skipped") + s;
     for (const { target } of plans) {
+      console.log("");
+      console.log(q(target.name));
+      if (lockOnly) {
+        if (target.agentsDir)
+          console.log(kept(" .agents/skills (--lock-only)"));
+        else
+          console.log(skipped(" .agents/skills (not found)"));
+        if (target.claudeDir)
+          console.log(kept(" .claude/skills (--lock-only)"));
+        else
+          console.log(skipped(" .claude/skills (not found)"));
+      } else {
+        if (target.agentsDir) {
+          const r = rmSkillDir(target.agentsDir, { allowedRoots });
+          console.log(removed(` from .agents/skills (${r.fileCount} files)`));
+        } else {
+          console.log(skipped(" .agents/skills (not found)"));
+        }
+        if (target.claudeDir) {
+          const r = rmSkillDir(target.claudeDir, { allowedRoots });
+          console.log(removed(` from .claude/skills (${r.fileCount} files)`));
+        } else {
+          console.log(skipped(" .claude/skills (not found)"));
+        }
+      }
       if (target.inLock) {
-        if (modifyLock) {
+        if (lockOnly || modifyLock) {
           const r = removeSkillFromLock(lockPath, target.name);
           if (r.removed)
-            console.log(`Removed ${q(target.name)} from skills-lock.json`);
+            console.log(removed(" from skills-lock.json"));
         } else {
-          console.log(`Kept ${q(target.name)} in skills-lock.json (no --force-lock)`);
+          console.log(kept(" in 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 ${q(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 ${q(target.name)} from .agents/skills (${r.fileCount} files)`);
-      } else {
-        console.log("Skipped .agents/skills (not found)");
+        console.log(skipped(" skills-lock.json (not in lock)"));
       }
     }
   }
@@ -1146,7 +1366,7 @@ function extractClaudeMentions(entry) {
     }
     for (const m of node.matchAll(/\bsuperpowers:([a-z0-9-]+)\b/g)) {
       if (m[1] !== undefined)
-        seen.add(`superpowers:${m[1]}`);
+        seen.add(m[1]);
     }
   });
   return [...seen];
@@ -1217,7 +1437,7 @@ function* findJsonlFiles(dir, since) {
 }
 function isRecentEntry(entry, since) {
   if (typeof entry !== "object" || entry === null)
-    return true;
+    return false;
   const e = entry;
   if (typeof e.timestamp === "string") {
     const d = new Date(e.timestamp);
@@ -1225,7 +1445,7 @@ function isRecentEntry(entry, since) {
   }
   if (typeof e.ts === "number")
     return new Date(e.ts * 1000) >= since;
-  return true;
+  return false;
 }
 
 // src/readers/claude.ts
@@ -1240,6 +1460,7 @@ function readClaudeUsage(options) {
     let prevSkill = null;
     const sessionAttr = new Map;
     const sessionAct = new Map;
+    const sessionMen = new Map;
     for (const line of readFileSync2(file, "utf8").split(`
 `)) {
       if (!line.trim())
@@ -1271,7 +1492,7 @@ function readClaudeUsage(options) {
       }
       if (options.mode === "mentions") {
         for (const skill of extractClaudeMentions(entry)) {
-          counts.set(skill, (counts.get(skill) ?? 0) + 1);
+          sessionMen.set(skill, (sessionMen.get(skill) ?? 0) + 1);
         }
       }
     }
@@ -1281,6 +1502,9 @@ function readClaudeUsage(options) {
     } else if (options.mode === "activations") {
       for (const [k, v] of sessionAct)
         counts.set(k, (counts.get(k) ?? 0) + v);
+    } else if (options.mode === "mentions") {
+      for (const [k, v] of sessionMen)
+        counts.set(k, (counts.get(k) ?? 0) + v);
     } else if (options.mode === "merged") {
       const keys = new Set([...sessionAttr.keys(), ...sessionAct.keys()]);
       for (const k of keys) {
@@ -1418,19 +1642,21 @@ var SECOND_MS = 1000;
 var MINUTE_MS = 60 * SECOND_MS;
 var HOUR_MS = 60 * MINUTE_MS;
 var DAY_MS = 24 * HOUR_MS;
+var MONTH_MS = 30 * DAY_MS;
 var UNITS_MS = {
   s: SECOND_MS,
   m: MINUTE_MS,
   h: HOUR_MS,
   d: DAY_MS,
-  w: 7 * DAY_MS
+  w: 7 * DAY_MS,
+  mo: MONTH_MS
 };
 function parsePeriod(period) {
   if (period === "all")
     return Number.POSITIVE_INFINITY;
-  const match = period.match(/^(\d+)([smhdw])$/);
+  const match = period.match(/^(\d+)(mo|[smhdw])$/);
   if (!match) {
-    throw new Error(`Invalid period: "${period}". Use values like 60s, 30m, 24h, 30d, 2w, all.`);
+    throw new Error(`Invalid period: "${period}". Use values like 60s, 30m, 24h, 30d, 2w, 6mo, all.`);
   }
   const unit = UNITS_MS[match[2] ?? ""] ?? 0;
   return Number(match[1]) * unit;
@@ -1441,7 +1667,8 @@ function pad(n, width) {
   return String(n).padStart(width);
 }
 function formatUsageRow(row) {
-  return `${pad(row.count, row.countWidth)} ${cyan(row.name)}`;
+  const suffix = row.installed === false ? ` ${red("(missing)")}` : "";
+  return `${pad(row.count, row.countWidth)} ${cyan(row.name)}${suffix}`;
 }
 function parseAgents(agent) {
   if (!agent)
@@ -1465,7 +1692,7 @@ var usageArgs = {
     type: "string",
     alias: "p",
     default: "all",
-    description: "60s, 30m, 24h, 30d, 2w, all"
+    description: "60s, 30m, 24h, 30d, 2w, 6mo, all"
   },
   since: { type: "string", description: "yyyy-mm-dd, overrides --period" },
   mode: {
@@ -1534,15 +1761,13 @@ async function runUsage(args) {
         name,
         count: counts.get(name) ?? 0,
         tokens: rec?.frontmatterTokens,
-        status: rec?.status ?? "ok"
+        installed: rec !== undefined && rec.status !== "missing"
       };
     });
     const rows = allRows.filter((r) => r.count > 0);
     rows.sort((a, b) => {
-      const aOk = a.status === "ok";
-      const bOk = b.status === "ok";
-      if (aOk !== bOk)
-        return aOk ? -1 : 1;
+      if (a.installed !== b.installed)
+        return a.installed ? -1 : 1;
       if (b.count !== a.count)
         return b.count - a.count;
       return a.name.localeCompare(b.name);
@@ -1558,7 +1783,8 @@ async function runUsage(args) {
         skill: r.name,
         count: r.count,
         tokensPerSkill: r.tokens ?? null,
-        consumption: (r.tokens ?? 0) * r.count
+        consumption: (r.tokens ?? 0) * r.count,
+        installed: r.installed
       }))
     }));
     console.log(JSON.stringify(output.length === 1 ? output[0] : output, null, 2));
@@ -1577,7 +1803,7 @@ async function runUsage(args) {
       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 }));
+      console.log(formatUsageRow({ count: r.count, name: r.name, countWidth, installed: r.installed }));
       distinct.add(r.name);
     }
     grandActivations += activations;
@@ -1724,11 +1950,12 @@ var SUBCOMMAND_NAMES = new Set([
   "remove",
   "rm",
   "cost",
-  "co",
+  "cs",
   "cst",
   "usage",
   "us",
-  "usg"
+  "usg",
+  "completion"
 ]);
 function reorderRootFlagsToSubcommand(argv) {
   const tail = argv.slice(2);
@@ -1742,7 +1969,10 @@ function reorderRootFlagsToSubcommand(argv) {
     return argv;
   return [argv[0] ?? "", argv[1] ?? "", sub, ...before, ...after];
 }
-process.argv = reorderRootFlagsToSubcommand(mergeAgentArgs(process.argv));
+function normalizeShortFlags(argv) {
+  return argv.map((tok) => tok === "-fl" ? "--force-lock" : tok);
+}
+process.argv = reorderRootFlagsToSubcommand(normalizeShortFlags(mergeAgentArgs(process.argv)));
 function printRootHelp() {
   const lines = [
     `Audit and manage AI agent skills (skillio v${version})`,
@@ -1754,15 +1984,16 @@ function printRootHelp() {
     "  -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`: 60s, 30m, 24h, 30d, 2w, all (default: all)",
+    "  -p, --period     Period for `usage`: 60s, 30m, 24h, 30d, 2w, 6mo, 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, cst    Show ambient ballast cost (per-skill frontmatter tokens) sorted desc",
-    "  usage, us, usg   Show skill usage × cost (consumption) with missed rows"
+    "  list, ls         List skills per source: install type, lock orphans, disk/lock diff",
+    "  remove, rm       Delete on-disk skill dirs; lock kept unless --force-lock",
+    "  cost, cs, cst    Show ambient ballast cost (per-skill frontmatter tokens) sorted desc",
+    "  usage, us, usg   Show skill usage × cost (consumption) with missed rows",
+    "  completion       Print shell completion script (bash, zsh, fish)"
   ];
   console.log(lines.join(`
 `));
@@ -1774,6 +2005,45 @@ function isRootHelp(argv) {
     return false;
   return args.includes("--help") || args.includes("-h");
 }
+function isRemoveHelp(argv) {
+  const args = argv.slice(2);
+  const first = args[0];
+  if (first !== "remove" && first !== "rm")
+    return false;
+  return args.includes("--help") || args.includes("-h");
+}
+function printRemoveHelp() {
+  const lines = [
+    "Remove skills from on-disk dirs (lock preserved unless --force-lock).",
+    "",
+    "USAGE skillio remove [SKILL...] [OPTIONS]",
+    "       skillio rm [SKILL...] [OPTIONS]",
+    "",
+    "ARGUMENTS",
+    "",
+    '  SKILL...         One or more skill names. Use "." to target every skill in scope.',
+    "",
+    "OPTIONS",
+    "",
+    "  -g, --global       Use global scope (default: false)",
+    "      --dry-run      Print plan without deleting",
+    '  -y, --yes          Skip confirmation prompt (non-TTY only for ".")',
+    "      --force-lock   Also remove entry from skills-lock.json (default: lock preserved)",
+    "  -fl                Alias for --force-lock",
+    "      --lock-only    Remove only the lock entry; keep on-disk directories",
+    "",
+    "EXAMPLES",
+    "",
+    "  skillio rm brainstorming",
+    "  skillio rm brainstorming writing-plans --yes",
+    "  skillio rm . --dry-run",
+    "  skillio rm . -fl",
+    "  skillio rm --force-lock obsolete-skill",
+    "  skillio rm --lock-only stale-entry"
+  ];
+  console.log(lines.join(`
+`));
+}
 function firstPositional(argv) {
   for (let i = 2;i < argv.length; i++) {
     const tok = argv[i];
@@ -1819,7 +2089,7 @@ var main = defineCommand({
       return;
     const interactive = process.stdout.isTTY && process.stdin.isTTY;
     if (interactive) {
-      const { runPicker } = await import("./shared/chunk-j1p4zpqy.js");
+      const { runPicker } = await import("./shared/chunk-vwrhawsv.js");
       const status = await runPicker({
         global: args.global ?? false
       });
@@ -1837,11 +2107,12 @@ var main = defineCommand({
     remove: removeCommand,
     rm: removeCommand,
     cost: costCommand,
-    co: costCommand,
+    cs: costCommand,
     cst: costCommand,
     usage: usageCommand,
     us: usageCommand,
-    usg: usageCommand
+    usg: usageCommand,
+    completion: completionCommand
   }
 });
 (async () => {
@@ -1849,6 +2120,10 @@ var main = defineCommand({
     printRootHelp();
     return;
   }
+  if (isRemoveHelp(process.argv)) {
+    printRemoveHelp();
+    return;
+  }
   if (isRootVersion(process.argv)) {
     console.log(version);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillio",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Audit and manage AI agent skills for Claude Code and Codex",
   "license": "MIT",
   "author": "ihororlovskyi",
@@ -45,6 +45,7 @@
     "lint": "biome check src/",
     "format": "biome format --write src/",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "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"
@@ -53,6 +54,7 @@
     "@biomejs/biome": "^2.4.14",
     "@changesets/cli": "^2.31.0",
     "@types/node": "^25.6.2",
+    "@vitest/coverage-v8": "^4.1.6",
     "bunup": "^0.16.31",
     "citty": "^0.2.2",
     "typescript": "^6.0.3",