skillvitals 0.1.0__py3-none-any.whl

skillvitals/__init__.py

@@ -0,0 +1,3 @@
+"""skillvitals — skill observability for Claude Code."""
+
+__version__ = "0.1.0"

skillvitals/__main__.py

@@ -0,0 +1,4 @@
+from skillvitals.cli import main
+
+if __name__ == "__main__":
+    main()

skillvitals/analysis.py

@@ -0,0 +1,139 @@
+"""Analysis engine: join registry skills with fire history into SkillVitals.
+
+This is where the health model lives. Definitions (documented for honesty —
+these are heuristics, not ground truth):
+
+  never-fired : zero lifetime activations.
+  dormant     : has activated before, but not within the window.
+  misfiring   : activated in-window, explicitly invoked, but with low
+                follow-through (engagement_ratio < MISFIRE_THRESHOLD) — a proxy
+                for wrong-prompt activation (fired, then abandoned).
+  healthy     : activated in-window with adequate engagement.
+  orphan      : appears in logs but is not installed (uninstalled/renamed).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from .models import Fire, FireKind, Health, Skill, SkillVitals
+
+MISFIRE_THRESHOLD = 2.0  # attribution messages per invoke below this looks like a misfire
+
+
+def _classify(
+    *,
+    has_skill: bool,
+    total_activity: int,
+    window_activity: int,
+    invoke_count: int,
+    engagement_ratio: float,
+) -> Health:
+    if not has_skill:
+        return Health.ORPHAN
+    if total_activity == 0:
+        return Health.NEVER_FIRED
+    if window_activity == 0:
+        return Health.DORMANT
+    if invoke_count > 0 and engagement_ratio < MISFIRE_THRESHOLD:
+        return Health.MISFIRING
+    return Health.HEALTHY
+
+
+def _tz(fires: list[Fire]):
+    for f in fires:
+        if f.timestamp and f.timestamp.tzinfo:
+            return f.timestamp.tzinfo
+    return UTC
+
+
+def compute_vitals(
+    skills: list[Skill],
+    fires: list[Fire],
+    *,
+    window_days: int = 14,
+    now: datetime | None = None,
+) -> list[SkillVitals]:
+    now = now or datetime.now(tz=_tz(fires))
+    window_start = now - timedelta(days=window_days)
+
+    by_name: dict[str, list[Fire]] = {}
+    for f in fires:
+        by_name.setdefault(f.name, []).append(f)
+
+    skill_by_name = {s.name: s for s in skills}
+    names = set(skill_by_name) | set(by_name)
+
+    out: list[SkillVitals] = []
+    for name in sorted(names):
+        skill = skill_by_name.get(name)
+        group = by_name.get(name, [])
+
+        invokes = [f for f in group if f.kind == FireKind.INVOKE]
+        attrs = [f for f in group if f.kind == FireKind.ATTRIBUTION]
+        win = [f for f in group if f.timestamp and f.timestamp >= window_start]
+        win_invokes = [f for f in win if f.kind == FireKind.INVOKE]
+        win_attrs = [f for f in win if f.kind == FireKind.ATTRIBUTION]
+
+        stamps = [f.timestamp for f in group if f.timestamp]
+        last_fired = max(stamps) if stamps else None
+        first_fired = min(stamps) if stamps else None
+        days_dormant = (now - last_fired).days if last_fired else None
+
+        invoke_count = len(invokes)
+        attribution_count = len(attrs)
+        engagement_ratio = attribution_count / max(invoke_count, 1)
+
+        context_tokens = skill.context_tokens if skill else 0
+        health = _classify(
+            has_skill=skill is not None,
+            total_activity=len(group),
+            window_activity=len(win),
+            invoke_count=invoke_count,
+            engagement_ratio=engagement_ratio,
+        )
+
+        out.append(
+            SkillVitals(
+                name=name,
+                skill=skill,
+                invoke_count=invoke_count,
+                attribution_count=attribution_count,
+                window_invoke_count=len(win_invokes),
+                window_attribution_count=len(win_attrs),
+                last_fired=last_fired,
+                first_fired=first_fired,
+                days_dormant=days_dormant,
+                context_tokens=context_tokens,
+                tokens_per_fire=context_tokens,
+                engagement_ratio=engagement_ratio,
+                health=health,
+                sessions=len({f.session_id for f in group if f.session_id}),
+            )
+        )
+    return out
+
+
+def _is_dormant_for(v: SkillVitals, days: int, now: datetime) -> bool:
+    """True if the skill has not activated within `days` (never-fired counts)."""
+    if v.health == Health.ORPHAN:
+        return False
+    if v.last_fired is None:
+        return True
+    return (now - v.last_fired).days >= days
+
+
+def find_dormant(
+    vitals: list[SkillVitals], *, days: int = 14, now: datetime | None = None
+) -> list[SkillVitals]:
+    """Skills inactive for >= `days`, sorted by context cost (most expensive first)."""
+    now = now or datetime.now(UTC)
+    dead = [v for v in vitals if _is_dormant_for(v, days, now)]
+    return sorted(dead, key=lambda v: v.context_tokens, reverse=True)
+
+
+def dormant_token_cost(
+    vitals: list[SkillVitals], *, days: int = 14, now: datetime | None = None
+) -> int:
+    """Total context tokens loaded every session by dormant skills — the viral number."""
+    return sum(v.context_tokens for v in find_dormant(vitals, days=days, now=now))

skillvitals/cli.py

@@ -0,0 +1,283 @@
+"""skillvitals command-line interface.
+
+    skillvitals scan         # the headline: fires, ctx cost, health per skill
+    skillvitals report       # markdown report (shareable / save with --output)
+    skillvitals history      # per-skill activation history
+    skillvitals dormancy     # dead-weight skills + token cost
+    skillvitals prescribe    # suggested fixes (--rewrite for LLM rewrites)
+    skillvitals test         # synthetic activation test (--live to really run)
+    skillvitals dashboard    # write the self-contained HTML dashboard
+    skillvitals serve        # run as an MCP server (stdio)
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+
+console = Console()
+
+
+def _now(value: str | None) -> datetime:
+    if value:
+        return datetime.fromisoformat(value).replace(tzinfo=UTC)
+    return datetime.now(UTC)
+
+
+def _apply_home(claude_home: str | None) -> None:
+    if claude_home:
+        os.environ["SKILLVITALS_CLAUDE_HOME"] = claude_home
+
+
+def _collect(window_days: int, now: datetime, persist: bool = True):
+    from .pipeline import collect
+
+    return collect(window_days=window_days, now=now, persist=persist)
+
+
+now_opt = click.option("--now", default=None, help="Override 'now' (ISO date) — for testing.")
+home_opt = click.option("--claude-home", default=None, help="Path to the .claude dir.")
+days_opt = click.option("--days", default=14, show_default=True, help="Dormancy/activity window in days.")
+
+
+@click.group(help="Skill observability for Claude Code.")
+@click.version_option(__version__, prog_name="skillvitals")
+def main() -> None:
+    pass
+
+
+@main.command()
+@home_opt
+@days_opt
+@now_opt
+def scan(claude_home, days, now):
+    """Scan installed skills and report fires, context cost, and health."""
+    _apply_home(claude_home)
+    from .analysis import dormant_token_cost, find_dormant
+    from .hooks import detect_skill_hook
+    from .report import build_rich_table
+    from .tokens import humanize
+
+    n = _now(now)
+    snap = _collect(days, n)
+    console.print(build_rich_table(snap.vitals))
+
+    cost = dormant_token_cost(snap.vitals, days=days, now=n)
+    dead = find_dormant(snap.vitals, days=days, now=n)
+    if dead:
+        console.print(
+            f"\n[yellow]{len(dead)} dormant/never-fired skills are costing you "
+            f"[bold]{humanize(cost)}[/bold] tokens per session.[/yellow]"
+        )
+        console.print("Run [cyan]skillvitals prescribe[/cyan] for fixes.")
+
+    hook = detect_skill_hook(snap.config.home, snap.config.cwd)
+    status = "[green]detected[/green]" if hook["has_prompt_hook"] else "[dim]not detected[/dim]"
+    console.print(f"\nSkill-activation hook (UserPromptSubmit): {status}")
+    if snap.errors:
+        console.print(f"[dim]{len(snap.errors)} unparseable log line(s) skipped.[/dim]")
+
+
+@main.command()
+@home_opt
+@days_opt
+@now_opt
+@click.option("--output", "-o", default=None, help="Write markdown to a file instead of stdout.")
+def report(claude_home, days, now, output):
+    """Render the full markdown report."""
+    _apply_home(claude_home)
+    from .report import render_markdown
+
+    n = _now(now)
+    snap = _collect(days, n)
+    md = render_markdown(snap.vitals, now=n, dormant_days=days)
+    if output:
+        from pathlib import Path
+
+        Path(output).write_text(md, encoding="utf-8")
+        console.print(f"[green]Wrote[/green] {output}")
+    else:
+        click.echo(md)
+
+
+@main.command()
+@home_opt
+@days_opt
+@now_opt
+def history(claude_home, days, now):
+    """Show per-skill activation history."""
+    _apply_home(claude_home)
+    from .report import humanize_age
+
+    n = _now(now)
+    snap = _collect(days, n)
+    table = Table(title=f"skill activation history (last {days}d window)", header_style="bold cyan")
+    for col in ("skill", "invokes", "engaged", "sessions", "last seen", "first seen"):
+        table.add_column(col, justify="right" if col in {"invokes", "engaged", "sessions"} else "left")
+    for v in sorted(snap.vitals, key=lambda v: (-v.attribution_count, -v.invoke_count)):
+        first = v.first_fired.date().isoformat() if v.first_fired else "—"
+        table.add_row(v.name, str(v.invoke_count), str(v.attribution_count),
+                      str(v.sessions), humanize_age(v.days_dormant), first)
+    console.print(table)
+
+
+@main.command()
+@home_opt
+@days_opt
+@now_opt
+def dormancy(claude_home, days, now):
+    """List skills inactive for N days and their context cost."""
+    _apply_home(claude_home)
+    from .analysis import dormant_token_cost, find_dormant
+    from .tokens import humanize
+
+    n = _now(now)
+    snap = _collect(days, n)
+    dead = find_dormant(snap.vitals, days=days, now=n)
+    table = Table(title=f"dormant skills (inactive ≥ {days}d)", header_style="bold yellow")
+    table.add_column("skill")
+    table.add_column("ctx tokens", justify="right")
+    table.add_column("last seen")
+    for v in dead:
+        last = "never" if v.days_dormant is None else f"{v.days_dormant}d ago"
+        table.add_row(v.name, humanize(v.context_tokens), last)
+    console.print(table)
+    console.print(
+        f"\n[bold yellow]{humanize(dormant_token_cost(snap.vitals, days=days, now=n))}[/bold yellow]"
+        " tokens of dead weight loaded every session."
+    )
+
+
+def _make_client():
+    """Build an anthropic client if the extra is installed and a key is set."""
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        return None
+    try:
+        import anthropic
+
+        return anthropic.Anthropic()
+    except ImportError:
+        return None
+
+
+@main.command()
+@home_opt
+@days_opt
+@now_opt
+@click.option("--rewrite", is_flag=True, help="Use an LLM to rewrite weak descriptions (opt-in, uses your key).")
+def prescribe(claude_home, days, now, rewrite):
+    """Suggest fixes for dormant / low-activation / redundant skills."""
+    _apply_home(claude_home)
+    from .prescribe import prescribe as run_prescribe
+    from .prescribe import rewrite_description
+
+    n = _now(now)
+    snap = _collect(days, n)
+    rx = run_prescribe(snap.vitals, now=n)
+    if not rx:
+        console.print("[green]No prescriptions — your skills look healthy.[/green]")
+        return
+
+    sev_color = {"critical": "red", "warn": "yellow", "info": "dim"}
+    by_skill: dict[str, list] = {}
+    for p in rx:
+        by_skill.setdefault(p.skill_name, []).append(p)
+    for skill_name, items in by_skill.items():
+        console.print(f"\n[bold]{skill_name}[/bold]")
+        for p in items:
+            c = sev_color.get(p.severity.value, "white")
+            console.print(f"  [{c}]●[/{c}] [{c}]{p.rule}[/{c}]: {p.message}")
+
+    if rewrite:
+        client = _make_client()
+        if client is None:
+            console.print("\n[yellow]--rewrite needs the 'llm' extra and ANTHROPIC_API_KEY.[/yellow]")
+            return
+        console.print("\n[bold]Suggested description rewrites:[/bold]")
+        skills = {s.name: s for s in snap.skills}
+        targets = {p.skill_name for p in rx
+                   if p.rule in {"description-too-short", "no-trigger-words", "low-quality"}}
+        for name in targets:
+            if name in skills:
+                new = rewrite_description(skills[name], client=client)
+                if new:
+                    console.print(f"\n[bold]{name}[/bold]:\n  {new}")
+
+
+@main.command(name="test")
+@home_opt
+@click.option("--skill", required=True, help="Skill name to test.")
+@click.option("--n", default=10, show_default=True, help="Number of synthetic prompts.")
+@click.option("--live", is_flag=True, help="Actually run prompts through headless Claude Code.")
+def test_cmd(claude_home, skill, n, live):
+    """Generate (and optionally run) an activation test battery for a skill."""
+    _apply_home(claude_home)
+    from .config import load_config
+    from .registry import scan_skills
+    from .testharness import make_cli_runner, measure_activation, synth_prompts
+
+    config = load_config()
+    skills = {s.name: s for s in scan_skills(config.skill_roots())}
+    if skill not in skills:
+        raise click.ClickException(f"Skill '{skill}' not found. Run `skillvitals scan` to list skills.")
+
+    prompts = synth_prompts(skills[skill].description, n=n)
+    console.print(f"[bold]{skill}[/bold] — {len(prompts)} synthetic test prompts:")
+    for i, p in enumerate(prompts, 1):
+        console.print(f"  {i}. {p}")
+
+    if not live:
+        console.print("\n[dim]Dry run. Re-run with --live to measure real activation "
+                      "(spawns headless Claude Code, uses your plan).[/dim]")
+        return
+
+    console.print("\n[cyan]Running live activation test…[/cyan]")
+    runner = make_cli_runner(skill, claude_home=config.home, cwd=config.cwd)
+    res = measure_activation(skill, prompts, runner=runner)
+    color = {"green": "green", "yellow": "yellow", "red": "red"}[res.grade]
+    console.print(f"Activation rate: [{color}]{res.activation_rate:.0%}[/{color}] "
+                  f"({res.activations}/{res.prompts_run}) — [{color}]{res.grade}[/{color}]")
+
+
+@main.command()
+@home_opt
+@days_opt
+@now_opt
+@click.option("--output", "-o", default=None, help="Where to write the HTML (default ~/.skillvitals/dashboard.html).")
+@click.option("--open", "open_", is_flag=True, help="Open the dashboard in your browser.")
+def dashboard(claude_home, days, now, output, open_):
+    """Generate the self-contained HTML dashboard."""
+    _apply_home(claude_home)
+    from .dashboard import write_dashboard
+    from .prescribe import prescribe as run_prescribe
+
+    n = _now(now)
+    snap = _collect(days, n)
+    out = output or str(snap.config.dashboard_path)
+    rx = run_prescribe(snap.vitals, now=n)
+    path = write_dashboard(snap.vitals, out, now=n, dormant_days=days, prescriptions=rx)
+    console.print(f"[green]Dashboard written to[/green] {path}")
+    if open_:
+        import webbrowser
+
+        webbrowser.open(f"file://{path}")
+
+
+@main.command()
+@home_opt
+def serve(claude_home):
+    """Run skillvitals as an MCP server (stdio transport)."""
+    _apply_home(claude_home)
+    from .server import mcp
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

skillvitals/config.py

@@ -0,0 +1,73 @@
+"""Path resolution and configuration.
+
+Everything reads from the user's Claude Code data under ``~/.claude``. All
+locations are overridable via environment variables so tests (and curious
+users) can point skillvitals at a fixture tree:
+
+  SKILLVITALS_CLAUDE_HOME   -> the .claude dir (default ~/.claude)
+  CLAUDE_CONFIG_DIR         -> respected as a fallback (Claude Code's own var)
+  SKILLVITALS_HOME          -> where the db + dashboard live (default ~/.skillvitals)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .registry import ScanRoot
+
+DORMANT_DAYS_DEFAULT = 14
+HISTORY_DAYS_DEFAULT = 30
+
+
+def claude_home() -> Path:
+    env = os.environ.get("SKILLVITALS_CLAUDE_HOME") or os.environ.get("CLAUDE_CONFIG_DIR")
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".claude"
+
+
+def skillvitals_home() -> Path:
+    env = os.environ.get("SKILLVITALS_HOME")
+    base = Path(env).expanduser() if env else Path.home() / ".skillvitals"
+    return base
+
+
+@dataclass
+class Config:
+    home: Path  # the .claude dir
+    sv_home: Path  # ~/.skillvitals
+    cwd: Path
+
+    @property
+    def projects_dir(self) -> Path:
+        return self.home / "projects"
+
+    @property
+    def db_path(self) -> Path:
+        return self.sv_home / "db.sqlite"
+
+    @property
+    def dashboard_path(self) -> Path:
+        return self.sv_home / "dashboard.html"
+
+    def skill_roots(self) -> list[ScanRoot]:
+        """Roots to scan, in precedence order. Plugin-cache files self-tag as
+        'plugin' regardless of label (see registry._classify_path)."""
+        roots = [
+            ScanRoot(self.home / "skills", "user"),
+            ScanRoot(self.home / "plugins" / "cache", "plugin"),
+        ]
+        project_skills = self.cwd / ".claude" / "skills"
+        if project_skills.exists():
+            roots.insert(0, ScanRoot(project_skills, "project"))
+        return roots
+
+
+def load_config(cwd: Path | None = None) -> Config:
+    return Config(
+        home=claude_home(),
+        sv_home=skillvitals_home(),
+        cwd=Path(cwd) if cwd else Path.cwd(),
+    )

skillvitals/dashboard.py

@@ -0,0 +1,84 @@
+"""Self-contained HTML dashboard (single file, inline CSS + vanilla JS sort).
+
+No build step, no framework, no external resources — the file works offline and
+can be opened straight from disk. Jinja2-rendered from the bundled template.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from .analysis import dormant_token_cost, find_dormant
+from .models import Health, Prescription, SkillVitals
+from .prescribe import prescribe
+from .report import humanize_age
+from .tokens import humanize
+
+_STATUS_LABEL = {
+    Health.HEALTHY: "healthy", Health.DORMANT: "dormant", Health.MISFIRING: "misfiring",
+    Health.NEVER_FIRED: "never-fired", Health.ORPHAN: "orphan",
+}
+
+_env = Environment(
+    loader=PackageLoader("skillvitals", "templates"),
+    autoescape=select_autoescape(["html", "j2"]),
+)
+
+
+def _rows(vitals: list[SkillVitals]) -> list[dict]:
+    order = {Health.HEALTHY: 0, Health.MISFIRING: 1, Health.DORMANT: 2,
+             Health.NEVER_FIRED: 3, Health.ORPHAN: 4}
+    rows = []
+    for v in sorted(vitals, key=lambda v: (order[v.health], -v.attribution_count, -v.context_tokens)):
+        rows.append({
+            "name": v.name,
+            "fires": v.invoke_count,
+            "engaged": v.attribution_count,
+            "ctx": v.context_tokens,
+            "ctx_h": humanize(v.context_tokens),
+            "quality": v.skill.quality_score if v.skill else 0,
+            "last_seen": humanize_age(v.days_dormant),
+            "age_v": -1 if v.days_dormant is None else v.days_dormant,
+            "status_label": _STATUS_LABEL[v.health],
+            "status_class": v.health.value,
+        })
+    return rows
+
+
+def render_dashboard(
+    vitals: list[SkillVitals],
+    *,
+    now: datetime | None = None,
+    dormant_days: int = 14,
+    prescriptions: list[Prescription] | None = None,
+    generated_at: str | None = None,
+) -> str:
+    now = now or datetime.now(UTC)
+    if prescriptions is None:
+        prescriptions = prescribe(vitals, now=now)
+    dead = find_dormant(vitals, days=dormant_days, now=now)
+    template = _env.get_template("dashboard.html.j2")
+    return template.render(
+        rows=_rows(vitals),
+        prescriptions=[
+            {"skill_name": p.skill_name, "severity": p.severity.value, "message": p.message}
+            for p in prescriptions
+        ],
+        total=len(vitals),
+        healthy=sum(1 for v in vitals if v.health == Health.HEALTHY),
+        dormant_count=len(dead),
+        dormant_cost_h=humanize(dormant_token_cost(vitals, days=dormant_days, now=now)),
+        generated_at=generated_at or now.strftime("%Y-%m-%d %H:%M UTC"),
+    )
+
+
+def write_dashboard(vitals: list[SkillVitals], path, **kwargs) -> str:
+    from pathlib import Path
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    html = render_dashboard(vitals, **kwargs)
+    path.write_text(html, encoding="utf-8")
+    return str(path)

skillvitals/hooks.py

@@ -0,0 +1,49 @@
+"""Lightweight hook-coverage detection.
+
+The ecosystem's answer to low skill activation is a UserPromptSubmit hook that
+forces skill evaluation (skills-hook, claude-skills-supercharged, etc.).
+skillvitals doesn't generate hooks (explicit non-goal) — it just reports whether
+one is configured, so a dormant skill's diagnosis can say "no activation hook is
+helping it fire."
+
+We read ``settings.json`` / ``settings.local.json`` from the .claude dir and the
+project dir, and look for a UserPromptSubmit hook. This is a global signal, not
+per-skill — we deliberately don't claim more precision than we can defend.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _load_settings(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def detect_skill_hook(claude_home: Path, cwd: Path | None = None) -> dict:
+    """Return {'has_prompt_hook': bool, 'sources': [paths], 'mentions_skill': bool}."""
+    candidates = [
+        claude_home / "settings.json",
+        claude_home / "settings.local.json",
+    ]
+    if cwd:
+        candidates += [cwd / ".claude" / "settings.json", cwd / ".claude" / "settings.local.json"]
+
+    has_hook = False
+    mentions_skill = False
+    sources: list[str] = []
+    for path in candidates:
+        if not path.exists():
+            continue
+        data = _load_settings(path)
+        hooks = data.get("hooks") or {}
+        if "UserPromptSubmit" in hooks and hooks["UserPromptSubmit"]:
+            has_hook = True
+            sources.append(str(path))
+            if "skill" in json.dumps(hooks["UserPromptSubmit"]).lower():
+                mentions_skill = True
+    return {"has_prompt_hook": has_hook, "sources": sources, "mentions_skill": mentions_skill}