skillstat 0.1.0__py3-none-any.whl

skillstat/cli.py

@@ -0,0 +1,1254 @@
+"""
+skillstat — Diagnose, audit, and optimize your AI agent skill usage.
+
+Supports (auto-detected):
+  - GitHub Copilot CLI  (~/.copilot/session-store.db)
+  - Claude Code         (~/.claude/history.jsonl + session JSONL)
+  - Codex CLI           (~/.codex/sessions/**/*.jsonl)
+  - OpenCode            (~/.local/share/opencode/opencode.db)
+  - Grok CLI            (~/.grok/sessions/)
+  - Droid CLI           (~/.factory/sessions/)
+
+Usage:
+  python3 skill_usage_stats.py                          # interactive
+  python3 skill_usage_stats.py --source copilot --all   # non-interactive
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sqlite3
+from abc import ABC, abstractmethod
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from InquirerPy import inquirer
+from InquirerPy.utils import InquirerPyStyle
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich import box
+
+HOME = Path.home()
+console = Console()
+
+PROMPT_STYLE = InquirerPyStyle(
+    {
+        "questionmark": "#e5c07b bold",
+        "question": "",
+        "pointer": "#61afef bold",
+        "highlighted": "#61afef bold",
+        "answer": "#98c379 bold",
+    }
+)
+
+
+# ── Data Model ──────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SkillCall:
+    skill: str
+    timestamp: str  # ISO-8601
+    project: str
+    session_id: str
+    source: str
+
+
+# ── Provider Interface ──────────────────────────────────────────────────────
+
+
+class Provider(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def available(self) -> bool: ...
+
+    @abstractmethod
+    def collect(self) -> list[SkillCall]: ...
+
+
+# ── GitHub Copilot ──────────────────────────────────────────────────────────
+
+COPILOT_DB = HOME / ".copilot" / "session-store.db"
+SKILL_CONTEXT_RE = re.compile(r'<skill-context\s+name="([^"]+)"')
+
+
+class CopilotProvider(Provider):
+    name = "GitHub Copilot"
+
+    def available(self) -> bool:
+        return COPILOT_DB.exists()
+
+    def collect(self) -> list[SkillCall]:
+        if not self.available():
+            return []
+        conn = sqlite3.connect(COPILOT_DB)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            "SELECT s.id AS sid, s.cwd, t.timestamp AS ts, t.user_message "
+            "FROM sessions s JOIN turns t ON t.session_id = s.id "
+            "WHERE t.user_message LIKE '%<skill-context name=\"%'"
+        ).fetchall()
+        conn.close()
+
+        calls: list[SkillCall] = []
+        for row in rows:
+            for m in SKILL_CONTEXT_RE.finditer(row["user_message"] or ""):
+                calls.append(SkillCall(
+                    skill=m.group(1),
+                    timestamp=row["ts"] or "",
+                    project=row["cwd"] or "",
+                    session_id=row["sid"],
+                    source=self.name,
+                ))
+        return calls
+
+
+# ── Claude Code ─────────────────────────────────────────────────────────────
+
+CLAUDE_HOME = HOME / ".claude"
+CLAUDE_HISTORY = CLAUDE_HOME / "history.jsonl"
+CLAUDE_PROJECTS = CLAUDE_HOME / "projects"
+
+CLAUDE_BUILTINS = {
+    "clear", "model", "usage", "resume", "new", "quit", "exit", "login",
+    "logout", "help", "config", "compact", "doctor", "cost", "effort",
+    "memory", "status", "skills", "permissions", "mcp", "terminal-setup",
+    "remote-env", "remote-control", "fast", "plan", "plugin", "rename",
+    "init", "review", "reload-plugins",
+}
+CLAUDE_SLASH_RE = re.compile(r"^/([a-zA-Z][a-zA-Z0-9_-]*)(?:\s|$)")
+
+
+class ClaudeCodeProvider(Provider):
+    name = "Claude Code"
+
+    def available(self) -> bool:
+        return CLAUDE_HISTORY.exists()
+
+    def collect(self) -> list[SkillCall]:
+        if not self.available():
+            return []
+
+        calls: list[SkillCall] = []
+        seen: set[str] = set()
+
+        # Source 1: history.jsonl — /slash-command invocations
+        self._collect_history(calls, seen)
+        # Source 2: session JSONL — Skill tool_use calls
+        if CLAUDE_PROJECTS.exists():
+            self._collect_projects(calls, seen)
+
+        return calls
+
+    def _collect_history(self, calls: list[SkillCall], seen: set[str]) -> None:
+        try:
+            lines = CLAUDE_HISTORY.read_text().splitlines()
+        except OSError:
+            return
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            display = entry.get("display", "")
+            m = CLAUDE_SLASH_RE.match(display)
+            if not m:
+                continue
+            skill = m.group(1)
+            if skill in CLAUDE_BUILTINS:
+                continue
+            raw_ts = entry.get("timestamp", 0)
+            ts = _ms_to_iso(raw_ts) if isinstance(raw_ts, (int, float)) else ""
+            key = f"{skill}:{raw_ts}"
+            if key in seen:
+                continue
+            seen.add(key)
+            calls.append(SkillCall(
+                skill=skill, timestamp=ts,
+                project=entry.get("project", ""),
+                session_id=entry.get("sessionId", ""),
+                source=self.name,
+            ))
+
+    def _collect_projects(self, calls: list[SkillCall], seen: set[str]) -> None:
+        for fpath in CLAUDE_PROJECTS.rglob("*.jsonl"):
+            self._parse_session_file(fpath, calls, seen)
+
+    def _parse_session_file(self, path: Path, calls: list[SkillCall], seen: set[str]) -> None:
+        try:
+            content = path.read_text()
+        except OSError:
+            return
+        session_id = path.stem
+        project = ""
+        for line in content.splitlines():
+            if not line.strip():
+                continue
+            # Fast cwd extraction
+            if not project and '"cwd"' in line:
+                try:
+                    entry = json.loads(line)
+                    if entry.get("cwd"):
+                        project = entry["cwd"]
+                except (json.JSONDecodeError, KeyError):
+                    pass
+            if '"Skill"' not in line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not project and entry.get("cwd"):
+                project = entry["cwd"]
+            if entry.get("type") != "assistant":
+                continue
+            msg = entry.get("message", {})
+            for part in msg.get("content", []):
+                if not isinstance(part, dict):
+                    continue
+                if part.get("type") != "tool_use" or part.get("name") != "Skill":
+                    continue
+                skill = (part.get("input") or {}).get("skill", "")
+                if not skill or skill in CLAUDE_BUILTINS:
+                    continue
+                raw_ts = entry.get("timestamp", "")
+                ts = raw_ts if isinstance(raw_ts, str) else _ms_to_iso(raw_ts)
+                key = f"{skill}:{ts}"
+                if key in seen:
+                    continue
+                seen.add(key)
+                calls.append(SkillCall(
+                    skill=skill, timestamp=ts,
+                    project=project or entry.get("cwd", ""),
+                    session_id=session_id, source=self.name,
+                ))
+
+
+# ── Codex CLI ───────────────────────────────────────────────────────────────
+
+CODEX_SESSIONS = HOME / ".codex" / "sessions"
+CODEX_SKILL_NAME_RE = re.compile(r"<name>([^<]+)</name>")
+CODEX_BUILTINS = {
+    "exit", "help", "model", "clear", "compact", "undo", "diff",
+    "history", "settings", "version", "approve", "status",
+    "imagegen", "openai-docs", "plugin-creator", "skill-creator", "skill-installer",
+}
+
+
+class CodexProvider(Provider):
+    name = "Codex CLI"
+
+    def available(self) -> bool:
+        return CODEX_SESSIONS.exists()
+
+    def collect(self) -> list[SkillCall]:
+        if not self.available():
+            return []
+        calls: list[SkillCall] = []
+        for fpath in CODEX_SESSIONS.rglob("*.jsonl"):
+            self._parse_session(fpath, calls)
+        return calls
+
+    def _parse_session(self, path: Path, calls: list[SkillCall]) -> None:
+        try:
+            lines = path.read_text().splitlines()
+        except OSError:
+            return
+        project = ""
+        session_id = ""
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if entry.get("type") == "session_meta" and not session_id:
+                project = (entry.get("payload") or {}).get("cwd", "")
+                session_id = (entry.get("payload") or {}).get("id", "")
+            if entry.get("type") == "response_item":
+                payload = entry.get("payload") or {}
+                for part in payload.get("content", []):
+                    if not isinstance(part, dict) or part.get("type") != "input_text":
+                        continue
+                    text = part.get("text", "")
+                    if "<skill>" not in text:
+                        continue
+                    for m in CODEX_SKILL_NAME_RE.finditer(text):
+                        skill = m.group(1)
+                        if skill in CODEX_BUILTINS:
+                            continue
+                        ts = entry.get("timestamp", "")
+                        if isinstance(ts, str):
+                            pass
+                        else:
+                            ts = _ms_to_iso(ts)
+                        calls.append(SkillCall(
+                            skill=skill, timestamp=ts, project=project,
+                            session_id=session_id, source=self.name,
+                        ))
+
+
+# ── Grok CLI ────────────────────────────────────────────────────────────────
+
+GROK_SESSIONS = HOME / ".grok" / "sessions"
+GROK_COMMAND_RE = re.compile(r"<command-name>([^<]+)</command-name>")
+GROK_BUILTINS = {
+    "compact", "always-approve", "context", "plugins", "reload-plugins",
+    "session-info", "imagine", "imagine-video", "feedback", "loop",
+    "help", "memory", "clear", "exit",
+}
+
+
+class GrokProvider(Provider):
+    name = "Grok CLI"
+
+    def available(self) -> bool:
+        return GROK_SESSIONS.exists()
+
+    def collect(self) -> list[SkillCall]:
+        if not self.available():
+            return []
+        calls: list[SkillCall] = []
+        for proj_entry in sorted(GROK_SESSIONS.iterdir()):
+            if not proj_entry.name.startswith("%2F"):
+                continue
+            try:
+                project = proj_entry.name.replace("%2F", "/").replace("%20", " ")
+            except Exception:
+                project = proj_entry.name
+            if not proj_entry.is_dir():
+                continue
+            for session_dir in sorted(proj_entry.iterdir()):
+                if not session_dir.is_dir():
+                    continue
+                seen: set[str] = set()
+                # Source 1: updates.jsonl
+                updates = session_dir / "updates.jsonl"
+                if updates.exists():
+                    self._parse_updates(updates, project, session_dir.name, calls, seen)
+                # Source 2: chat_history.jsonl
+                chat = session_dir / "chat_history.jsonl"
+                if chat.exists():
+                    self._parse_chat(chat, project, session_dir.name, calls, seen)
+        return calls
+
+    def _parse_updates(self, path: Path, project: str, session_id: str,
+                       calls: list[SkillCall], seen: set[str]) -> None:
+        try:
+            lines = path.read_text().splitlines()
+        except OSError:
+            return
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            params = record.get("params") or {}
+            update = params.get("update") or {}
+            if update.get("sessionUpdate") != "user_message_chunk":
+                continue
+            mc = update.get("content") or {}
+            if mc.get("type") != "text":
+                continue
+            text = mc.get("text", "")
+            for m in GROK_COMMAND_RE.finditer(text):
+                skill = m.group(1)
+                if skill in GROK_BUILTINS:
+                    continue
+                seen.add(skill)
+                raw_ts = record.get("timestamp", 0)
+                ts = _epoch_to_iso(raw_ts) if isinstance(raw_ts, (int, float)) else ""
+                calls.append(SkillCall(
+                    skill=skill, timestamp=ts, project=project,
+                    session_id=params.get("sessionId", session_id),
+                    source=self.name,
+                ))
+
+    def _parse_chat(self, path: Path, project: str, session_id: str,
+                    calls: list[SkillCall], seen: set[str]) -> None:
+        try:
+            lines = path.read_text().splitlines()
+        except OSError:
+            return
+        for line in lines:
+            if not line.strip() or "command-name" not in line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if record.get("type") != "user":
+                continue
+            content = record.get("content", "")
+            if isinstance(content, list):
+                text = "".join(p.get("text", "") if isinstance(p, dict) else "" for p in content)
+            elif isinstance(content, str):
+                text = content
+            else:
+                continue
+            if "<background_context>" in text:
+                continue
+            for m in GROK_COMMAND_RE.finditer(text):
+                skill = m.group(1)
+                if skill in GROK_BUILTINS or skill in seen:
+                    continue
+                seen.add(skill)
+                calls.append(SkillCall(
+                    skill=skill, timestamp="", project=project,
+                    session_id=session_id, source=self.name,
+                ))
+
+
+# ── Droid CLI ───────────────────────────────────────────────────────────────
+
+DROID_SESSIONS = HOME / ".factory" / "sessions"
+DROID_SKILL_RE = re.compile(r'Skill "([^"]+)" is now active')
+
+
+class DroidProvider(Provider):
+    name = "Droid CLI"
+
+    def available(self) -> bool:
+        return DROID_SESSIONS.exists()
+
+    def collect(self) -> list[SkillCall]:
+        if not self.available():
+            return []
+        calls: list[SkillCall] = []
+        for fpath in DROID_SESSIONS.rglob("*.jsonl"):
+            self._parse_session(fpath, calls)
+        return calls
+
+    def _parse_session(self, path: Path, calls: list[SkillCall]) -> None:
+        try:
+            lines = path.read_text().splitlines()
+        except OSError:
+            return
+        session_id = ""
+        project = ""
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if entry.get("type") == "session_start":
+                session_id = entry.get("id", "")
+                project = entry.get("cwd", "")
+            if entry.get("type") != "message":
+                continue
+            msg = entry.get("message") or {}
+            for part in msg.get("content", []):
+                if not isinstance(part, dict) or part.get("type") != "tool_result":
+                    continue
+                text = part.get("content", "")
+                if not isinstance(text, str):
+                    continue
+                m = DROID_SKILL_RE.search(text)
+                if not m:
+                    continue
+                ts = entry.get("timestamp", "")
+                if isinstance(ts, str):
+                    pass
+                else:
+                    ts = _ms_to_iso(ts)
+                calls.append(SkillCall(
+                    skill=m.group(1), timestamp=ts, project=project,
+                    session_id=session_id, source=self.name,
+                ))
+
+
+# ── OpenCode ────────────────────────────────────────────────────────────────
+
+OPENCODE_DB = HOME / ".local" / "share" / "opencode" / "opencode.db"
+OPENCODE_BUILTINS = {
+    "bash", "compact", "help", "model", "config", "exit", "clear",
+    "status", "version", "approve", "settings", "list",
+}
+
+
+class OpenCodeProvider(Provider):
+    name = "OpenCode"
+
+    def available(self) -> bool:
+        return OPENCODE_DB.exists()
+
+    def collect(self) -> list[SkillCall]:
+        if not self.available():
+            return []
+        try:
+            conn = sqlite3.connect(OPENCODE_DB)
+            conn.row_factory = sqlite3.Row
+        except Exception:
+            return []
+
+        calls: list[SkillCall] = []
+        try:
+            rows = conn.execute(
+                "SELECT p.data, s.directory, p.session_id "
+                "FROM part p JOIN session s ON p.session_id = s.id "
+                "WHERE json_extract(p.data, '$.type') = 'tool' "
+                "  AND json_extract(p.data, '$.tool') = 'skill'"
+            ).fetchall()
+            for row in rows:
+                try:
+                    data = json.loads(row["data"])
+                except (json.JSONDecodeError, TypeError):
+                    continue
+                state = data.get("state") or {}
+                if state.get("status") != "completed":
+                    continue
+                inp = state.get("input") or {}
+                skill = inp.get("name", "")
+                if not skill or skill in OPENCODE_BUILTINS:
+                    continue
+                time_info = state.get("time") or {}
+                raw_ts = time_info.get("start", "")
+                ts = _ms_to_iso(raw_ts) if isinstance(raw_ts, (int, float)) else raw_ts
+                calls.append(SkillCall(
+                    skill=skill, timestamp=ts,
+                    project=row["directory"] or "",
+                    session_id=row["session_id"] or "",
+                    source=self.name,
+                ))
+        except Exception:
+            pass
+        finally:
+            conn.close()
+        return calls
+
+
+# ── Skill Discovery ────────────────────────────────────────────────────────
+
+SKILL_DIRS = [
+    HOME / ".agents" / "skills",
+    HOME / ".claude" / "skills",
+    HOME / ".copilot" / "skills",
+    HOME / ".copilot" / "installed-plugins",
+    HOME / ".claude" / "plugins",
+]
+
+
+def _discover_in_dir(base: Path) -> set[str]:
+    skills: set[str] = set()
+    if not base.exists():
+        return skills
+    if base.name == "skills":
+        for child in base.iterdir():
+            if child.is_dir() and not child.name.startswith("."):
+                skills.add(child.name)
+        return skills
+    for sd in base.rglob("skills"):
+        if sd.is_dir():
+            for child in sd.iterdir():
+                if child.is_dir() and not child.name.startswith("."):
+                    skills.add(child.name)
+    for child in base.iterdir():
+        if child.is_dir() and not child.name.startswith(".") and any(child.glob("*.md")):
+            skills.add(child.name)
+    return skills
+
+
+def discover_installed_skills() -> list[str]:
+    all_skills: set[str] = set()
+    for d in SKILL_DIRS:
+        all_skills.update(_discover_in_dir(d))
+    return sorted(all_skills)
+
+
+@dataclass
+class SkillHealth:
+    name: str
+    path: Path
+    has_skill_md: bool = False
+    has_description: bool = False
+    has_name_field: bool = False
+    file_size: int = 0
+    issues: list[str] = field(default_factory=list)
+
+
+def _find_skill_path(name: str) -> Path | None:
+    """Locate the directory for a skill by name across all SKILL_DIRS."""
+    for base in SKILL_DIRS:
+        if not base.exists():
+            continue
+        # Direct child
+        candidate = base / name
+        if candidate.is_dir():
+            return candidate
+        # Nested under plugins/*/skills/
+        for sd in base.rglob("skills"):
+            if sd.is_dir():
+                candidate = sd / name
+                if candidate.is_dir():
+                    return candidate
+    return None
+
+
+def check_skill_health(skills: list[str]) -> list[SkillHealth]:
+    """Run health checks on all installed skills."""
+    results: list[SkillHealth] = []
+    for name in skills:
+        path = _find_skill_path(name)
+        if not path:
+            h = SkillHealth(name=name, path=Path("?"))
+            h.issues.append("directory not found")
+            results.append(h)
+            continue
+
+        h = SkillHealth(name=name, path=path)
+
+        # Check for SKILL.md
+        skill_md = path / "SKILL.md"
+        if skill_md.exists():
+            h.has_skill_md = True
+            h.file_size = skill_md.stat().st_size
+            content = skill_md.read_text(errors="replace")
+
+            # Parse YAML frontmatter
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    fm = parts[1]
+                    if re.search(r"^name\s*:", fm, re.MULTILINE):
+                        h.has_name_field = True
+                    if re.search(r"^description\s*:", fm, re.MULTILINE):
+                        h.has_description = True
+
+            if not h.has_name_field:
+                h.issues.append("missing 'name' in frontmatter")
+            if not h.has_description:
+                h.issues.append("missing 'description' in frontmatter")
+            if h.file_size < 50:
+                h.issues.append("SKILL.md too short (<50 bytes)")
+        else:
+            # Maybe has README.md instead
+            readme = path / "README.md"
+            if readme.exists():
+                h.issues.append("has README.md but no SKILL.md")
+            else:
+                h.issues.append("no SKILL.md or README.md")
+
+        results.append(h)
+    return results
+
+
+def render_health_check(results: list[SkillHealth]) -> None:
+    """Render health check results — only show issues."""
+    problems = [h for h in results if h.issues]
+    healthy = len(results) - len(problems)
+
+    if not problems:
+        console.print(f"  [green]✓[/green] Health check: all [bold]{healthy}[/bold] skills are well-formed")
+        return
+
+    console.print(f"  [yellow]⚠[/yellow] Health check: [bold green]{healthy}[/bold green] healthy, [bold yellow]{len(problems)}[/bold yellow] with issues")
+
+    table = Table(
+        box=box.SIMPLE, show_header=True, header_style="bold",
+        border_style="bright_black", padding=(0, 1),
+    )
+    table.add_column("Skill", style="cyan", min_width=20)
+    table.add_column("Issues", style="yellow")
+
+    for h in problems[:15]:
+        table.add_row(h.name, "; ".join(h.issues))
+
+    if len(problems) > 15:
+        table.add_row(f"… +{len(problems) - 15} more", "", style="dim")
+
+    console.print(table)
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+
+def _ms_to_iso(ms: int | float) -> str:
+    try:
+        return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    except (OSError, ValueError, OverflowError):
+        return ""
+
+
+def _epoch_to_iso(s: int | float) -> str:
+    try:
+        return datetime.fromtimestamp(s, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    except (OSError, ValueError, OverflowError):
+        return ""
+
+
+def _fmt_date(iso: str) -> str:
+    if not iso:
+        return "—"
+    try:
+        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+        return dt.strftime("%Y-%m-%d")
+    except ValueError:
+        return iso[:10] if len(iso) >= 10 else iso
+
+
+# ── Report Builder ──────────────────────────────────────────────────────────
+
+
+ALL_PROVIDERS: list[Provider] = [
+    CopilotProvider(),
+    ClaudeCodeProvider(),
+    CodexProvider(),
+    OpenCodeProvider(),
+    GrokProvider(),
+    DroidProvider(),
+]
+
+
+def build_report(
+    calls: list[SkillCall],
+    installed_skills: list[str],
+    sources: list[str],
+    days: int | None,
+) -> dict:
+    # Filter by time window
+    if days is not None:
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        calls = [c for c in calls if c.timestamp >= cutoff]
+
+    sc: Counter[str] = Counter()
+    ss: defaultdict[str, set[str]] = defaultdict(set)
+    sf: dict[str, str] = {}
+    sl: dict[str, str] = {}
+    sp: defaultdict[str, set[str]] = defaultdict(set)
+    s_sources: defaultdict[str, set[str]] = defaultdict(set)
+    sessions: set[str] = set()
+
+    for c in calls:
+        sc[c.skill] += 1
+        ss[c.skill].add(c.session_id)
+        sp[c.skill].add(c.project)
+        s_sources[c.skill].add(c.source)
+        sessions.add(c.session_id)
+        ts = str(c.timestamp) if c.timestamp else ""
+        if ts:
+            if c.skill not in sf or ts < sf[c.skill]:
+                sf[c.skill] = ts
+            if c.skill not in sl or ts > sl[c.skill]:
+                sl[c.skill] = ts
+
+    items = []
+    for name in installed_skills:
+        items.append({
+            "skill_name": name,
+            "load_count": sc.get(name, 0),
+            "session_count": len(ss.get(name, set())),
+            "project_count": len(sp.get(name, set())),
+            "sources": sorted(s_sources.get(name, set())),
+            "first_seen": sf.get(name, ""),
+            "last_seen": sl.get(name, ""),
+        })
+    for name in sc:
+        if name not in installed_skills:
+            items.append({
+                "skill_name": f"{name} (?)",
+                "load_count": sc[name],
+                "session_count": len(ss[name]),
+                "project_count": len(sp[name]),
+                "sources": sorted(s_sources[name]),
+                "first_seen": sf.get(name, ""),
+                "last_seen": sl.get(name, ""),
+            })
+    items.sort(key=lambda x: (-x["load_count"], -x["session_count"], x["skill_name"]))
+
+    used = sum(1 for i in items if i["load_count"] > 0)
+    unused = sum(1 for i in items if i["load_count"] == 0)
+    return {
+        "sources": sources,
+        "window": "all time" if days is None else f"last {days} days",
+        "total_sessions": len(sessions),
+        "total_events": sum(sc.values()),
+        "installed": len(installed_skills),
+        "used": used,
+        "unused": unused,
+        "skills": items,
+        "calls": calls,  # keep raw calls for audit & heatmap
+    }
+
+
+# ── Skill Audit ─────────────────────────────────────────────────────────────
+
+
+@dataclass
+class _SkillSummary:
+    name: str
+    count: int
+    sessions: int
+    projects: int
+    last_used: str  # ISO
+
+
+@dataclass
+class TrendEntry:
+    skill: _SkillSummary
+    recent: int
+    prior: int
+    pct: int  # positive = rising, negative = declining
+
+
+@dataclass
+class SkillAudit:
+    most_used: list[tuple[_SkillSummary, float]]  # (skill, share%)
+    rising: list[TrendEntry]
+    declining: list[TrendEntry]
+    stale: list[_SkillSummary]
+    one_off: list[_SkillSummary]
+    cross_project: list[_SkillSummary]
+
+
+def _parse_ts(iso: str) -> datetime | None:
+    if not iso:
+        return None
+    try:
+        return datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def audit_skills(calls: list[SkillCall], report_skills: list[dict]) -> SkillAudit:
+    """Classify skills into audit categories based on usage trends."""
+    now = datetime.now(timezone.utc)
+    four_weeks_ago = (now - timedelta(days=28)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    eight_weeks_ago = (now - timedelta(days=56)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    # Build SkillSummary from report items
+    summaries: dict[str, _SkillSummary] = {}
+    for item in report_skills:
+        if item["load_count"] == 0:
+            continue
+        summaries[item["skill_name"]] = _SkillSummary(
+            name=item["skill_name"],
+            count=item["load_count"],
+            sessions=item["session_count"],
+            projects=item["project_count"],
+            last_used=item["last_seen"],
+        )
+
+    # Count recent (0-4w) and prior (4-8w) calls per skill
+    recent_counts: Counter[str] = Counter()
+    prior_counts: Counter[str] = Counter()
+    for c in calls:
+        ts = str(c.timestamp) if c.timestamp else ""
+        if not ts:
+            continue
+        if ts >= four_weeks_ago:
+            recent_counts[c.skill] += 1
+        elif ts >= eight_weeks_ago:
+            prior_counts[c.skill] += 1
+
+    skills = list(summaries.values())
+
+    # One-off: used exactly once
+    one_off = [s for s in skills if s.count == 1]
+    one_off_set = {s.name for s in one_off}
+
+    # Stale: last used > 4 weeks ago, not one-off
+    stale = [
+        s for s in skills
+        if s.name not in one_off_set and s.last_used and s.last_used < four_weeks_ago
+    ]
+    stale_set = {s.name for s in stale}
+
+    # Rising: recent >= 1.5× prior
+    rising: list[TrendEntry] = []
+    for s in skills:
+        if s.name in stale_set or s.name in one_off_set:
+            continue
+        rc = recent_counts.get(s.name, 0)
+        pc = prior_counts.get(s.name, 0)
+        if pc > 0 and rc >= pc * 1.5:
+            pct = round((rc / pc - 1) * 100)
+            rising.append(TrendEntry(skill=s, recent=rc, prior=pc, pct=pct))
+    rising.sort(key=lambda t: -t.pct)
+
+    # Declining: recent <= 0.5× prior
+    declining: list[TrendEntry] = []
+    for s in skills:
+        if s.name in stale_set or s.name in one_off_set:
+            continue
+        rc = recent_counts.get(s.name, 0)
+        pc = prior_counts.get(s.name, 0)
+        if pc > 0 and rc <= pc * 0.5:
+            pct = round((1 - rc / pc) * 100)
+            declining.append(TrendEntry(skill=s, recent=rc, prior=pc, pct=pct))
+    declining.sort(key=lambda t: -t.pct)
+
+    rising_set = {t.skill.name for t in rising}
+    declining_set = {t.skill.name for t in declining}
+
+    # Most used (last 4 weeks), excluding already-classified
+    recent_total = sum(recent_counts.values()) or 1
+    most_used: list[tuple[_SkillSummary, float]] = []
+    for s in sorted(skills, key=lambda s: -recent_counts.get(s.name, 0)):
+        if s.name in stale_set or s.name in one_off_set or s.name in rising_set or s.name in declining_set:
+            continue
+        rc = recent_counts.get(s.name, 0)
+        if rc > 0:
+            most_used.append((s, rc / recent_total))
+    most_used = most_used[:10]
+
+    # Cross-project: used in 3+ projects
+    cross_project = sorted([s for s in skills if s.projects >= 3], key=lambda s: -s.projects)
+
+    return SkillAudit(
+        most_used=most_used,
+        rising=rising,
+        declining=declining,
+        stale=stale,
+        one_off=one_off,
+        cross_project=cross_project,
+    )
+
+
+# ── Rich Rendering ──────────────────────────────────────────────────────────
+
+
+def render_report(report: dict, limit: int = 50, show_unused: bool = False) -> None:
+    src_label = ", ".join(report["sources"]) or "none"
+
+    header = Text()
+    header.append("  Sources:   ", style="dim")
+    header.append(f"{src_label}\n", style="bold cyan")
+    header.append("  Window:    ", style="dim")
+    header.append(f"{report['window']}\n", style="bold")
+    header.append("  Sessions:  ", style="dim")
+    header.append(f"{report['total_sessions']}\n", style="bold")
+    header.append("  Skills:    ", style="dim")
+    header.append(f"{report['installed']}", style="bold")
+    header.append(" installed, ", style="dim")
+    header.append(f"{report['used']}", style="bold green")
+    header.append(" used, ", style="dim")
+    header.append(f"{report['unused']}", style="bold yellow")
+    header.append(" unused\n", style="dim")
+    header.append("  Events:    ", style="dim")
+    header.append(f"{report['total_events']}", style="bold magenta")
+    header.append(" total skill loads", style="dim")
+
+    console.print()
+    console.print(Panel(header, title="[bold]📊 Skill Usage Report[/bold]", border_style="blue", padding=(0, 1)))
+
+    all_skills = report["skills"]
+    used_skills = [s for s in all_skills if s["load_count"] > 0][:limit]
+    unused_skills = [s for s in all_skills if s["load_count"] == 0]
+
+    if not used_skills:
+        console.print("\n[yellow]  No skill records found.[/yellow]")
+        return
+
+    _render_skill_table(used_skills, title="Skill Breakdown")
+
+    # ── Audit ──
+    calls = report.get("calls", [])
+    if used_skills:
+        audit = audit_skills(calls, report["skills"])
+        render_audit(audit)
+
+    # ── Unused skills ──
+    if unused_skills and show_unused:
+        _render_unused_list(unused_skills)
+    elif unused_skills and not show_unused:
+        console.print(f"\n  [dim]{len(unused_skills)} unused skills hidden.[/dim]")
+
+    console.print()
+
+
+def _render_skill_table(skills: list[dict], title: str = "Skill Breakdown") -> None:
+    """Render the skill usage table (only for skills with loads > 0)."""
+    table = Table(
+        box=box.ROUNDED, show_header=True, header_style="bold white",
+        border_style="bright_black", row_styles=["", "dim"],
+        padding=(0, 1), title=f"[bold]{title}[/bold]", title_style="bold",
+    )
+    table.add_column("#", style="dim", width=3, justify="right")
+    table.add_column("Skill", style="cyan", min_width=18)
+    table.add_column("Loads", justify="right", style="bold")
+    table.add_column("Sessions", justify="right")
+    table.add_column("Projects", justify="right")
+    table.add_column("Source", min_width=10)
+    table.add_column("First", justify="center")
+    table.add_column("Last", justify="center")
+    table.add_column("", width=10)
+
+    max_loads = max((s["load_count"] for s in skills), default=1) or 1
+    for i, skill in enumerate(skills, 1):
+        loads = skill["load_count"]
+        bar_w = int((loads / max_loads) * 8) if loads > 0 else 0
+        bar = "█" * bar_w + "░" * (8 - bar_w)
+
+        if loads >= 5:
+            ls, bs, ns = "bold green", "green", "bold cyan"
+        elif loads >= 2:
+            ls, bs, ns = "bold yellow", "yellow", "cyan"
+        else:
+            ls, bs, ns = "white", "blue", "cyan"
+
+        src = ", ".join(skill["sources"]) if skill["sources"] else "—"
+        table.add_row(
+            str(i),
+            Text(skill["skill_name"], style=ns),
+            Text(str(loads), style=ls),
+            Text(str(skill["session_count"]), style="white"),
+            Text(str(skill["project_count"]), style="white"),
+            Text(src, style="dim cyan"),
+            Text(_fmt_date(skill["first_seen"]), style="white"),
+            Text(_fmt_date(skill["last_seen"]), style="white"),
+            Text(bar, style=bs),
+        )
+
+    console.print()
+    console.print(table)
+
+
+def _render_unused_list(unused_skills: list[dict]) -> None:
+    """Render a compact list of unused (0-load) skills."""
+    cols = 4
+    names = [s["skill_name"] for s in unused_skills]
+    t = Text()
+    for i, name in enumerate(names):
+        t.append(f"  {name:<26}", style="dim")
+        if (i + 1) % cols == 0:
+            t.append("\n")
+    console.print()
+    console.print(Panel(
+        t,
+        title=f"[bold yellow]💤 Unused Skills ({len(names)})[/bold yellow]",
+        border_style="yellow",
+        padding=(0, 1),
+    ))
+
+
+def _fit(s: str, n: int) -> str:
+    return (s[:n - 1] + "…") if len(s) > n else s.ljust(n)
+
+
+def render_audit(audit: SkillAudit) -> None:
+    """Render the skill audit analysis."""
+    sections: list[Text] = []
+
+    # ⭐ Most Used
+    if audit.most_used:
+        t = Text()
+        t.append("  ⭐ MOST USED ", style="bold white")
+        t.append("— last 4 weeks\n", style="dim")
+        for skill, share in audit.most_used:
+            pct = f"{share * 100:.0f}%".rjust(4)
+            t.append(f"     {_fit(skill.name, 22)} {pct}  ", style="cyan")
+            t.append(f"{skill.count} calls  {skill.projects} proj\n", style="dim")
+        sections.append(t)
+
+    # ▲ Rising
+    if audit.rising:
+        t = Text()
+        t.append("  ▲ RISING ", style="bold green")
+        t.append("— 50%+ growth last 4w\n", style="dim")
+        for entry in audit.rising:
+            t.append(f"     {_fit(entry.skill.name, 22)} ", style="green")
+            t.append(f"now: {entry.recent:3d}  was: {entry.prior:3d}  ", style="dim")
+            t.append(f"↑{entry.pct}%\n", style="bold green")
+        sections.append(t)
+
+    # ▼ Declining
+    if audit.declining:
+        t = Text()
+        t.append("  ▼ DECLINING ", style="bold red")
+        t.append("— 50%+ drop last 4w\n", style="dim")
+        for entry in audit.declining:
+            t.append(f"     {_fit(entry.skill.name, 22)} ", style="red")
+            t.append(f"now: {entry.recent:3d}  was: {entry.prior:3d}  ", style="dim")
+            t.append(f"↓{entry.pct}%\n", style="bold red")
+        sections.append(t)
+
+    # ⚠ Stale
+    if audit.stale:
+        t = Text()
+        t.append("  ⚠ STALE ", style="bold yellow")
+        t.append(f"— unused 28+ days ({len(audit.stale)})\n", style="dim")
+        for s in audit.stale[:8]:
+            last = _fmt_date(s.last_used)
+            t.append(f"     {_fit(s.name, 22)} last: {last}  {s.count} calls\n", style="yellow")
+        if len(audit.stale) > 8:
+            t.append(f"     … and {len(audit.stale) - 8} more\n", style="dim")
+        sections.append(t)
+
+    # ◈ Cross-project
+    if audit.cross_project:
+        t = Text()
+        t.append("  ◈ CROSS-PROJECT ", style="bold cyan")
+        t.append(f"— used in 3+ projects ({len(audit.cross_project)})\n", style="dim")
+        for s in audit.cross_project[:8]:
+            t.append(f"     {_fit(s.name, 22)} {s.projects} projects  {s.count} calls\n", style="cyan")
+        sections.append(t)
+
+    # ◇ One-off
+    if audit.one_off:
+        t = Text()
+        t.append("  ◇ ONE-OFF ", style="dim bold")
+        t.append(f"— used once ({len(audit.one_off)})\n", style="dim")
+        for s in audit.one_off[:6]:
+            t.append(f"     {_fit(s.name, 22)} {_fmt_date(s.last_used)}\n", style="dim")
+        if len(audit.one_off) > 6:
+            t.append(f"     … and {len(audit.one_off) - 6} more\n", style="dim")
+        sections.append(t)
+
+    if not sections:
+        return
+
+    combined = Text()
+    for i, sec in enumerate(sections):
+        if i > 0:
+            combined.append("\n")
+        combined.append_text(sec)
+
+    console.print()
+    console.print(Panel(
+        combined,
+        title="[bold]🔍 Skill Audit[/bold]",
+        border_style="magenta",
+        padding=(0, 1),
+    ))
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Skill Usage Stats — scan agent sessions for skill usage.")
+    p.add_argument("--source", nargs="*", help="Filter by source (copilot, claude, codex, opencode, grok, droid)")
+    p.add_argument("--days", type=int, default=None, help="Look back N days (0 or omit = all)")
+    p.add_argument("--all", action="store_true", help="Scan all time")
+    p.add_argument("--limit", type=int, default=50, help="Max rows (default: 50)")
+    p.add_argument("--json", action="store_true", help="Output JSON")
+    return p.parse_args()
+
+
+SOURCE_KEY_MAP = {
+    "copilot": "GitHub Copilot",
+    "claude": "Claude Code",
+    "codex": "Codex CLI",
+    "opencode": "OpenCode",
+    "grok": "Grok CLI",
+    "droid": "Droid CLI",
+}
+
+
+def main() -> int:
+    args = parse_args()
+
+    console.print()
+    console.print("[bold blue]⚡ Skill Usage Stats[/bold blue]")
+    console.print("[dim]   Scan your agent sessions and discover skill usage patterns[/dim]")
+
+    # 1. Detect available providers
+    available = [p for p in ALL_PROVIDERS if p.available()]
+    if not available:
+        console.print("\n[bold red]✗ No supported agent data found on this machine.[/bold red]")
+        return 1
+
+    # 2. Determine if interactive
+    is_interactive = args.source is None and not args.json
+
+    # 3. Select sources
+    if args.source is not None:
+        selected_names = {SOURCE_KEY_MAP.get(s.lower(), s) for s in args.source}
+        providers = [p for p in available if p.name in selected_names]
+    elif len(available) == 1:
+        providers = available
+    else:
+        console.print()
+        choices = [{"name": f"{p.name}", "value": p.name} for p in available]
+        choices.insert(0, {"name": "All detected sources", "value": "__all__"})
+        selected = inquirer.select(
+            message="Which source(s)?",
+            choices=choices,
+            default="__all__",
+            style=PROMPT_STYLE,
+        ).execute()
+        providers = available if selected == "__all__" else [p for p in available if p.name == selected]
+
+    # 4. Time window
+    if args.all:
+        days = None
+    elif args.days is not None:
+        days = args.days if args.days > 0 else None
+    elif args.source is None:
+        console.print()
+        window = inquirer.select(
+            message="Time window?",
+            choices=[
+                {"name": "All time", "value": 0},
+                {"name": "Last 7 days", "value": 7},
+                {"name": "Last 14 days", "value": 14},
+                {"name": "Last 30 days", "value": 30},
+                {"name": "Last 90 days", "value": 90},
+            ],
+            default=0,
+            style=PROMPT_STYLE,
+        ).execute()
+        days = window if window > 0 else None
+    else:
+        days = None
+
+    # 4. Discover skills + health check
+    with console.status("[bold cyan]Discovering installed skills...", spinner="dots"):
+        installed_skills = discover_installed_skills()
+    console.print(f"  [green]✓[/green] Found [bold]{len(installed_skills)}[/bold] installed skills")
+
+    with console.status("[bold cyan]Running health check...", spinner="dots"):
+        health_results = check_skill_health(installed_skills)
+    render_health_check(health_results)
+
+    # 4b. Ask whether to show unused skills (interactive only)
+    show_unused = False
+    if is_interactive:
+        console.print()
+        show_unused = inquirer.confirm(
+            message="Include never-used skills in the report?",
+            default=False,
+            style=PROMPT_STYLE,
+        ).execute()
+
+    # 5. Collect calls
+    all_calls: list[SkillCall] = []
+    source_names: list[str] = []
+    for p in providers:
+        with console.status(f"[bold cyan]Scanning {p.name}...", spinner="dots"):
+            calls = p.collect()
+        console.print(f"  [green]✓[/green] {p.name}: [bold]{len(calls)}[/bold] skill events")
+        all_calls.extend(calls)
+        source_names.append(p.name)
+
+    # 6. Build & render report
+    report = build_report(all_calls, installed_skills, source_names, days)
+
+    if args.json:
+        console.print()
+        json_report = {k: v for k, v in report.items() if k != "calls"}
+        console.print_json(json.dumps(json_report, ensure_ascii=False))
+    else:
+        render_report(report, args.limit, show_unused=show_unused)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())