skilldrop-cli 0.2.0

package/skills/ai-usage-report/scripts/build_report.py

@@ -0,0 +1,436 @@
+#!/usr/bin/env python3
+"""Build an AI usage report from a usage-event log.
+
+Reads a CSV or JSONL file of usage events and writes a markdown report.
+See ../templates/usage-event-schema.md for the input schema.
+
+Usage:
+    python3 build_report.py events.csv --view per-user --period week -o report.md
+    python3 build_report.py events.jsonl --view team-rollup --from 2026-05-01 --to 2026-05-31 -o report.md
+    python3 build_report.py events.csv --view effectiveness --period week -o report.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from statistics import median
+
+VIEWS = ("per-user", "team-rollup", "effectiveness")
+MIN_USERS_FOR_ROLLUP = 5
+
+
+def load_events(path: Path) -> list[dict]:
+    suffix = path.suffix.lower()
+    if suffix == ".csv":
+        with path.open(newline="") as f:
+            return list(csv.DictReader(f))
+    if suffix in (".jsonl", ".ndjson"):
+        events = []
+        with path.open() as f:
+            for line in f:
+                s = line.strip()
+                if s:
+                    events.append(json.loads(s))
+        return events
+    raise SystemExit(f"error: unsupported file type {suffix!r} (use .csv or .jsonl)")
+
+
+def parse_ts(s) -> datetime | None:
+    if not s:
+        return None
+    if isinstance(s, datetime):
+        return s if s.tzinfo else s.replace(tzinfo=timezone.utc)
+    s = str(s).strip()
+    if not s:
+        return None
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(s)
+    except ValueError:
+        # Try date-only
+        try:
+            dt = datetime.fromisoformat(s + "T00:00:00+00:00")
+        except ValueError:
+            return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def parse_bool(v):
+    if v is None or v == "":
+        return None
+    if isinstance(v, bool):
+        return v
+    s = str(v).strip().lower()
+    if s in ("1", "true", "yes", "y", "t"):
+        return True
+    if s in ("0", "false", "no", "n", "f"):
+        return False
+    return None
+
+
+def resolve_period(period: str, from_arg: str | None, to_arg: str | None):
+    if from_arg or to_arg:
+        if not (from_arg and to_arg):
+            raise SystemExit("error: --from and --to must be used together")
+        start = parse_ts(from_arg)
+        end = parse_ts(to_arg)
+        if start is None or end is None:
+            raise SystemExit(f"error: could not parse --from / --to dates")
+        # If user passed date-only for --to, push to end of day
+        if len(to_arg) <= 10:
+            end = end + timedelta(days=1, seconds=-1)
+        return start, end
+    now = datetime.now(timezone.utc)
+    if period == "week":
+        return now - timedelta(days=7), now
+    if period == "month":
+        return now - timedelta(days=30), now
+    raise SystemExit(f"error: unknown --period {period!r} (use week, month, or --from/--to)")
+
+
+def detect_signals(events: list[dict]) -> dict:
+    """Which optional fields are populated in the input."""
+    keys_present = set()
+    for e in events[:1000]:  # sample
+        for k, v in e.items():
+            if v not in (None, ""):
+                keys_present.add(k)
+    return {
+        "session_id": "session_id" in keys_present,
+        "output_consumed": "output_consumed" in keys_present,
+        "consumed_at": "consumed_at" in keys_present,
+        "outcome": "outcome" in keys_present,
+    }
+
+
+def filter_to_period(events: list[dict], start: datetime, end: datetime) -> list[dict]:
+    out = []
+    for e in events:
+        ts = parse_ts(e.get("timestamp"))
+        if ts and start <= ts <= end:
+            out.append({**e, "_ts": ts})
+    return out
+
+
+def aggregate(events: list[dict], signals: dict):
+    per_user = defaultdict(lambda: {
+        "invocations": 0,
+        "sessions": set(),
+        "tools": set(),
+        "session_counts": defaultdict(int),
+        "consumed_known": 0,
+        "consumed_yes": 0,
+    })
+    tool_counter: Counter = Counter()
+
+    for e in events:
+        u = e.get("user")
+        if not u:
+            continue
+        d = per_user[u]
+        d["invocations"] += 1
+        tool = e.get("tool") or "(unknown)"
+        d["tools"].add(tool)
+        tool_counter[tool] += 1
+
+        if signals["session_id"]:
+            sid = e.get("session_id")
+            if sid:
+                d["sessions"].add(sid)
+                d["session_counts"][sid] += 1
+
+        if signals["output_consumed"]:
+            b = parse_bool(e.get("output_consumed"))
+            if b is not None:
+                d["consumed_known"] += 1
+                if b:
+                    d["consumed_yes"] += 1
+
+    return per_user, tool_counter
+
+
+def fmt_pct(num, denom) -> str:
+    if not denom:
+        return "—"
+    return f"{100 * num / denom:.0f}%"
+
+
+def per_user_metrics(d: dict, signals: dict) -> dict:
+    n_sessions = len(d["sessions"]) if signals["session_id"] else None
+    avg_per_session = (d["invocations"] / n_sessions) if n_sessions else None
+    single_shot = sum(1 for c in d["session_counts"].values() if c == 1) if n_sessions else None
+    eff_rate_pct = (
+        100 * d["consumed_yes"] / d["consumed_known"]
+        if signals["output_consumed"] and d["consumed_known"]
+        else None
+    )
+    single_rate_pct = (100 * single_shot / n_sessions) if (n_sessions and single_shot is not None) else None
+    return {
+        "invocations": d["invocations"],
+        "sessions": n_sessions,
+        "avg_per_session": avg_per_session,
+        "distinct_tools": len(d["tools"]),
+        "effectiveness_rate_pct": eff_rate_pct,
+        "single_shot_rate_pct": single_rate_pct,
+    }
+
+
+def build_data_caveats_line(signals: dict) -> str:
+    missing = [k for k, v in signals.items() if not v]
+    if not missing:
+        return "**Data signals available:** all optional fields present — full report."
+    return (
+        "**Data caveats:** input is missing "
+        + ", ".join(f"`{m}`" for m in missing)
+        + " — affected metrics shown as `—`."
+    )
+
+
+def build_missing_signals_section(signals: dict) -> str:
+    lines = []
+    if not signals["session_id"]:
+        lines.append("- `session_id` absent → **session count, avg/session, and single-shot rate** could not be computed.")
+    if not signals["output_consumed"]:
+        lines.append("- `output_consumed` absent → **effectiveness rate** could not be computed.")
+    if not signals["consumed_at"]:
+        lines.append("- `consumed_at` absent → **output-to-shipped lag** could not be computed.")
+    if not signals["outcome"]:
+        lines.append("- `outcome` absent → cannot filter out errored invocations; raw counts include errors.")
+    if not lines:
+        return "All optional signals were present; the report contains all available columns."
+    return "\n".join(lines)
+
+
+def load_template(name: str, script_dir: Path) -> str:
+    p = script_dir.parent / "templates" / name
+    if not p.exists():
+        raise SystemExit(f"error: template not found: {p}")
+    return p.read_text()
+
+
+# --------------------------------------------------------------------- views
+
+
+def render_per_user(per_user, tool_counter, signals, ctx, sort_for_effectiveness=False):
+    template = load_template(
+        "report-per-user.md" if not sort_for_effectiveness else "report-per-user.md",
+        ctx["script_dir"],
+    )
+
+    metrics_by_user = {u: per_user_metrics(d, signals) for u, d in per_user.items()}
+
+    if sort_for_effectiveness:
+        # Highest single-shot rate first (most theatrical pattern); tie-break by lowest effectiveness
+        def key(u):
+            m = metrics_by_user[u]
+            ss = m["single_shot_rate_pct"] if m["single_shot_rate_pct"] is not None else -1
+            er = m["effectiveness_rate_pct"] if m["effectiveness_rate_pct"] is not None else 101
+            return (-ss, er)
+        users_sorted = sorted(metrics_by_user.keys(), key=key)
+    else:
+        users_sorted = sorted(metrics_by_user.keys())
+
+    rows = []
+    for u in users_sorted:
+        m = metrics_by_user[u]
+        sessions_str = str(m["sessions"]) if m["sessions"] is not None else "—"
+        avg_str = f"{m['avg_per_session']:.1f}" if m["avg_per_session"] is not None else "—"
+        eff_str = f"{m['effectiveness_rate_pct']:.0f}%" if m["effectiveness_rate_pct"] is not None else "—"
+        ss_str = f"{m['single_shot_rate_pct']:.0f}%" if m["single_shot_rate_pct"] is not None else "—"
+        rows.append(
+            f"| {u} | {m['invocations']} | {sessions_str} | {avg_str} | "
+            f"{m['distinct_tools']} | {eff_str} | {ss_str} |"
+        )
+
+    total_invocations = sum(tool_counter.values())
+    top_tools_rows = "\n".join(
+        f"| {t} | {c} | {100 * c / total_invocations:.0f}% |"
+        for t, c in tool_counter.most_common(10)
+    )
+
+    return template.format(
+        team_name=ctx["team_name"],
+        start_date=ctx["start"].date().isoformat(),
+        end_date=ctx["end"].date().isoformat(),
+        n_days=(ctx["end"] - ctx["start"]).days,
+        n_users=len(per_user),
+        n_invocations=total_invocations,
+        n_distinct_tools=len(tool_counter),
+        data_caveats_line=ctx["caveats_line"],
+        per_user_rows="\n".join(rows),
+        top_tools_rows=top_tools_rows,
+        missing_signals_section=ctx["missing_section"],
+        generated_at=ctx["generated_at"],
+        input_file=ctx["input_file"],
+    )
+
+
+def render_team_rollup(per_user, tool_counter, signals, ctx):
+    if len(per_user) < MIN_USERS_FOR_ROLLUP:
+        raise SystemExit(
+            f"error: team-rollup requires ≥{MIN_USERS_FOR_ROLLUP} users in scope; "
+            f"got {len(per_user)}. Aggregate views aren't anonymous at that size. "
+            f"Use --view per-user and treat the output as identifying."
+        )
+
+    template = load_template("report-team-rollup.md", ctx["script_dir"])
+    n_days = max(1, (ctx["end"] - ctx["start"]).days)
+
+    invocations_per_user_per_day = [
+        d["invocations"] / n_days for d in per_user.values()
+    ]
+    distinct_tools_per_user = [len(d["tools"]) for d in per_user.values()]
+
+    # Effectiveness (team avg, weighted by known events)
+    total_known = sum(d["consumed_known"] for d in per_user.values())
+    total_yes = sum(d["consumed_yes"] for d in per_user.values())
+    team_eff = (
+        f"{100 * total_yes / total_known:.0f}%"
+        if signals["output_consumed"] and total_known
+        else "—"
+    )
+
+    # Single-shot (team avg, weighted by sessions)
+    total_sessions = sum(len(d["sessions"]) for d in per_user.values())
+    total_single_shot = sum(
+        sum(1 for c in d["session_counts"].values() if c == 1)
+        for d in per_user.values()
+    )
+    team_ss = (
+        f"{100 * total_single_shot / total_sessions:.0f}%"
+        if signals["session_id"] and total_sessions
+        else "—"
+    )
+
+    # Engagement tiers (normalized to weekly thresholds)
+    week_scale = 7 / n_days
+    tiers = {"heavy": 0, "moderate": 0, "light": 0, "inactive": 0}
+    for d in per_user.values():
+        weekly = d["invocations"] * week_scale
+        if weekly == 0:
+            tiers["inactive"] += 1
+        elif weekly > 20:
+            tiers["heavy"] += 1
+        elif weekly >= 5:
+            tiers["moderate"] += 1
+        else:
+            tiers["light"] += 1
+
+    n_active = sum(1 for d in per_user.values() if d["invocations"] > 0)
+
+    if signals["output_consumed"] and total_known:
+        eff_block = (
+            f"Team-wide, **{100 * total_yes / total_known:.0f}%** of invocations "
+            f"with a known outcome had their output consumed in a shipped artifact "
+            f"({total_yes:,} of {total_known:,}). The remaining "
+            f"{total_known - total_yes:,} invocations produced output that was either "
+            f"discarded, never reviewed, or not yet tracked as consumed."
+        )
+    else:
+        eff_block = (
+            "**Effectiveness signal is unavailable** — the input lacks `output_consumed` "
+            "data. Volume and engagement-tier metrics above are still valid, but the "
+            "performative-vs-effective distinction cannot be computed from this input."
+        )
+
+    total_invocations = sum(tool_counter.values())
+    top_tools_rows = "\n".join(
+        f"| {t} | {c} | {100 * c / total_invocations:.0f}% |"
+        for t, c in tool_counter.most_common(10)
+    )
+
+    return template.format(
+        team_name=ctx["team_name"],
+        start_date=ctx["start"].date().isoformat(),
+        end_date=ctx["end"].date().isoformat(),
+        n_days=n_days,
+        n_users=len(per_user),
+        n_invocations=total_invocations,
+        data_caveats_line=ctx["caveats_line"],
+        median_invocations_per_user_per_day=f"{median(invocations_per_user_per_day):.1f}" if invocations_per_user_per_day else "0",
+        median_distinct_tools_per_user=f"{median(distinct_tools_per_user):.0f}" if distinct_tools_per_user else "0",
+        team_effectiveness_rate=team_eff,
+        team_single_shot_rate=team_ss,
+        n_active_users=n_active,
+        n_heavy=tiers["heavy"],
+        n_moderate=tiers["moderate"],
+        n_light=tiers["light"],
+        n_inactive=tiers["inactive"],
+        top_tools_rows=top_tools_rows,
+        effectiveness_block=eff_block,
+        missing_signals_section=ctx["missing_section"],
+        generated_at=ctx["generated_at"],
+        input_file=ctx["input_file"],
+    )
+
+
+# --------------------------------------------------------------------- driver
+
+
+def main(argv) -> int:
+    ap = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    ap.add_argument("input", help="Path to events file (.csv or .jsonl)")
+    ap.add_argument("--view", choices=VIEWS, default="per-user")
+    ap.add_argument("--period", choices=("week", "month"), default="week")
+    ap.add_argument("--from", dest="from_arg", default=None, help="ISO date — overrides --period")
+    ap.add_argument("--to", dest="to_arg", default=None, help="ISO date — overrides --period")
+    ap.add_argument("--team-name", default="Team")
+    ap.add_argument("-o", "--out", default=None, help="Output markdown path")
+    args = ap.parse_args(argv)
+
+    input_path = Path(args.input).expanduser().resolve()
+    if not input_path.exists():
+        sys.stderr.write(f"error: input file not found: {input_path}\n")
+        return 1
+
+    events = load_events(input_path)
+    if not events:
+        sys.stderr.write("error: input file has no events\n")
+        return 1
+
+    signals = detect_signals(events)
+    start, end = resolve_period(args.period, args.from_arg, args.to_arg)
+    events = filter_to_period(events, start, end)
+    if not events:
+        sys.stderr.write(f"error: no events fell within {start.isoformat()} → {end.isoformat()}\n")
+        return 1
+
+    per_user, tool_counter = aggregate(events, signals)
+
+    script_dir = Path(__file__).resolve().parent
+    ctx = {
+        "team_name": args.team_name,
+        "start": start,
+        "end": end,
+        "caveats_line": build_data_caveats_line(signals),
+        "missing_section": build_missing_signals_section(signals),
+        "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "input_file": str(input_path.name),
+        "script_dir": script_dir,
+    }
+
+    if args.view == "per-user":
+        out = render_per_user(per_user, tool_counter, signals, ctx)
+    elif args.view == "effectiveness":
+        out = render_per_user(per_user, tool_counter, signals, ctx, sort_for_effectiveness=True)
+    else:  # team-rollup
+        out = render_team_rollup(per_user, tool_counter, signals, ctx)
+
+    out_path = Path(args.out).expanduser().resolve() if args.out else input_path.with_suffix(".report.md")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(out)
+    print(f"wrote {out_path} ({len(events)} events, {len(per_user)} users, view={args.view})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/skills/ai-usage-report/templates/report-per-user.md

@@ -0,0 +1,42 @@
+# AI Usage Report — {team_name}
+
+**Period:** {start_date} → {end_date} ({n_days} days)
+**Users in scope:** {n_users}
+**Total invocations:** {n_invocations}
+**Distinct tools / skills observed:** {n_distinct_tools}
+
+> {data_caveats_line}
+
+## Per-user breakdown
+
+| User | Invocations | Sessions | Avg / session | Distinct tools | Effectiveness rate | Single-shot rate |
+|---|---:|---:|---:|---:|---:|---:|
+{per_user_rows}
+
+**Reading the table:**
+- *Effectiveness rate* — % of this user's invocations whose output was consumed in a shipped artifact. `—` means the input lacked the `output_consumed` field.
+- *Single-shot rate* — % of this user's sessions with exactly one invocation. `—` means the input lacked `session_id`.
+- *High single-shot + low effectiveness* is a starting place to ask about engagement — not a verdict.
+
+## Top tools / skills used (across team)
+
+| Tool | Invocations | % of total |
+|---|---:|---:|
+{top_tools_rows}
+
+## Where signals are missing
+
+{missing_signals_section}
+
+## How to read this report
+
+This report shows **patterns**, not verdicts. A user with a low effectiveness rate may be:
+
+- Exploring (high volume of throwaway prompts while learning a tool)
+- Solving in one shot (one prompt is enough — no follow-up needed)
+- Doing AI theater (invoking to be seen invoking)
+
+The data alone cannot distinguish these. Use the report to surface conversations, not to grade individuals.
+
+---
+*Generated by `ai-usage-report` on {generated_at}. Input file: `{input_file}`. View: `per-user`.*

package/skills/ai-usage-report/templates/report-team-rollup.md

@@ -0,0 +1,49 @@
+# AI Usage Rollup — {team_name}
+
+**Period:** {start_date} → {end_date} ({n_days} days)
+**Team size in scope:** {n_users} users
+**Total invocations:** {n_invocations}
+
+> {data_caveats_line}
+
+This is an **aggregate** view. No individuals are named. If you need a per-user breakdown for a 1:1 or coaching conversation, switch to the `per-user` view — but read the privacy note at the bottom first.
+
+## Headline metrics
+
+| Metric | Value |
+|---|---:|
+| Invocations / user / day (median) | {median_invocations_per_user_per_day} |
+| Distinct tools per user (median) | {median_distinct_tools_per_user} |
+| Effectiveness rate (team avg) | {team_effectiveness_rate} |
+| Single-shot session rate (team avg) | {team_single_shot_rate} |
+| Active users (≥1 invocation in period) | {n_active_users} of {n_users} |
+
+## Adoption distribution
+
+| Engagement tier | Users | What it means |
+|---|---:|---|
+| **Heavy** (>20 invocations/week) | {n_heavy} | Deep adopters; check whether their effectiveness rate is also high |
+| **Moderate** (5–20 / week) | {n_moderate} | The healthy middle |
+| **Light** (1–4 / week) | {n_light} | Sampling but not embedded; surface tool-fit conversations |
+| **Inactive** (0 / week) | {n_inactive} | No usage; check whether tool access is the blocker |
+
+## Top tools / skills (team-wide)
+
+| Tool | Invocations | % of total |
+|---|---:|---:|
+{top_tools_rows}
+
+## Effectiveness signal (if available)
+
+{effectiveness_block}
+
+## Where signals are missing
+
+{missing_signals_section}
+
+## Privacy posture
+
+This view is safe to share with audiences who should not see individual usage data (skip-level meetings, broad team reviews, exec rollups). The headline metrics and tier counts cannot be reverse-engineered to identify individuals **as long as `n_users` ≥ 5**. If your team has fewer than 5 users in scope, the script will refuse to generate this view — switch to `per-user` and treat it accordingly.
+
+---
+*Generated by `ai-usage-report` on {generated_at}. Input file: `{input_file}`. View: `team-rollup`.*

package/skills/ai-usage-report/templates/usage-event-schema.md

@@ -0,0 +1,76 @@
+# usage-event-schema
+
+Input to `ai-usage-report` is a CSV or JSONL file. Each row / each JSON object is one **usage event** — a single invocation of an AI tool or skill by a single user.
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `timestamp` | ISO 8601 datetime | e.g. `2026-05-21T14:32:11Z` |
+| `user` | string | Stable identifier — email, handle, or employee ID. Use the same value for the same person across events. |
+| `tool` | string | What was invoked — e.g. `claude-code`, `cursor`, `copilot`, or a specific skill name like `deck-builder` |
+
+If any of these three is missing, the script exits with an error. They are the minimum needed to compute a volume report.
+
+## Optional but recommended fields
+
+| Field | Type | Used for |
+|---|---|---|
+| `session_id` | string | Groups events into sessions. Needed for **session depth** and **single-shot rate**. |
+| `output_consumed` | bool / `0` / `1` / `true` / `false` | Whether the AI output ended up in a shipped artifact. Needed for **effectiveness rate**. |
+| `consumed_at` | ISO 8601 datetime | When the output landed in the shipped artifact. Needed for **output-to-shipped lag**. |
+| `output_size` | int | Tokens or characters of AI output |
+| `prompt_size` | int | Tokens or characters of the user prompt (do **not** include the prompt text itself — see privacy note below) |
+| `outcome` | enum: `success` / `error` / `cancelled` | Filter for errors that distort volume |
+
+## Fields the skill explicitly does NOT want
+
+- ❌ **The prompt text.** Prompts contain code, customer data, and personal context. The skill works from metadata only.
+- ❌ **The output text.** Same reason.
+- ❌ **Free-form user notes** about their session. Redact before passing to the skill.
+
+If your telemetry source captures these, drop them at export time — not after the report is generated.
+
+## Graceful degradation
+
+The script reads what's there and labels missing-signal columns explicitly. The signal-to-field mapping:
+
+| If your input has… | …the report can show |
+|---|---|
+| Just the 3 required fields | Volume + breadth |
+| `+ session_id` | …and session depth + single-shot rate |
+| `+ output_consumed` | …and effectiveness rate + AI-theater flag column |
+| `+ consumed_at` | …and output-to-shipped lag |
+| `+ outcome` | …and an error-filtered version of every metric |
+
+When a column is omitted, the report includes a *"Where signals are missing"* section listing exactly which optional fields were absent and which metrics consequently couldn't be computed. This is the contract: the report never lies about what it knows.
+
+## Example: CSV
+
+```csv
+timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
+2026-05-21T09:14:23Z,alice@acme.com,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
+2026-05-21T09:14:55Z,alice@acme.com,claude-code,sess-001,1,2026-05-21T11:02:00Z,success
+2026-05-21T09:18:02Z,alice@acme.com,deck-builder,sess-001,1,2026-05-21T14:30:00Z,success
+2026-05-21T10:01:11Z,bob@acme.com,cursor,sess-014,0,,success
+2026-05-21T10:01:30Z,bob@acme.com,cursor,sess-014,0,,success
+2026-05-21T14:22:08Z,carol@acme.com,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
+```
+
+## Example: JSONL
+
+```jsonl
+{"timestamp": "2026-05-21T09:14:23Z", "user": "alice@acme.com", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
+{"timestamp": "2026-05-21T09:14:55Z", "user": "alice@acme.com", "tool": "claude-code", "session_id": "sess-001", "output_consumed": true, "outcome": "success"}
+{"timestamp": "2026-05-21T10:01:11Z", "user": "bob@acme.com", "tool": "cursor", "session_id": "sess-014", "output_consumed": false, "outcome": "success"}
+```
+
+## A note on the `output_consumed` signal
+
+This is the field that matters most for the effective-vs-performative distinction. It's also the hardest one to populate accurately. Three common implementations, ranked by signal quality:
+
+1. **Diff-based attribution** (best): the telemetry source tracks whether AI output text appears (or fuzzy-matches) in a subsequent commit / PR / doc within N hours. High signal, hard to game.
+2. **Explicit accept/reject events** (good): the IDE emits "user accepted the suggestion" vs "user rejected it." Medium signal — accepting and then immediately deleting still counts as consumed.
+3. **Self-reported** (weakest): the user checks a box "did you use this?" Low signal — captures intent but easy to game and high reporting burden.
+
+If your telemetry source uses (3), don't pretend the resulting effectiveness rate is more reliable than it is. The report can still be useful for spotting outliers, but the numbers should be read with that grain of salt.

package/skills/api-contract-draft/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: api-contract-draft
+description: Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.
+---
+
+# api-contract-draft
+
+Produces the contract *before* the code — a valid OpenAPI 3.1 document two teams can argue about and then build against in parallel. The YAML is half the artifact; the other half is the **decisions log**, because reviewers should debate "cursor vs offset pagination", not line 240. Designs new contracts; documenting an existing API is `guide-builder`'s job.
+
+## How to respond
+
+1. **Extract the resources from the brief.** Nouns the API owns, their relationships, and their lifecycle (who creates, what mutates, is delete real or soft). Ask at most 2 questions, and spend them on consumer shape ("who calls this — our SPA, partners, both?") and write semantics ("can a refund be requested twice?") — the two answers that change the contract most. Everything else: pick the convention from [`reference.md`](reference.md) and tag the choice `[assumption]` in the decisions log.
+
+2. **Apply the house conventions** (full detail in [`reference.md`](reference.md)) — deviate only when the brief forces it, and log the deviation:
+   - **Paths**: plural-noun resources, no verbs — ✅ `POST /refunds` ❌ `POST /createRefund`; nesting one level max, then flatten with filters
+   - **Errors**: RFC 9457 `application/problem+json`, every 4xx the operation can return enumerated with a stable machine-readable `code`; no bare unexplained 500
+   - **Pagination**: cursor-based by default (`cursor` + `limit`, response carries `next_cursor`); offset only with a logged reason
+   - **Idempotency**: every unsafe POST takes `Idempotency-Key`; PUT/DELETE idempotent by construction
+   - **Versioning**: URL major version (`/v1/`), additive changes don't bump, breaking changes do — the policy sentence goes in the spec's `description`
+   - **Auth**: a `securityScheme` exists and every operation declares its requirement — including the explicitly-public ones
+
+3. **Type every field like a reviewer will reject sloppiness.** Formats (`uuid`, `date-time`, `int64`), constraints (`maxLength`, `minimum`, `enum`, `pattern` for codes), required vs optional explicit on every schema, money as integer minor units (never float), timestamps UTC ISO-8601. A schema that's all bare `type: string` is a draft of a draft.
+
+4. **Give every operation a realistic example** — request and the 2xx response, with values that look like production (`"cur_9f3k..."`, not `"string"`). Examples are where shape disagreements surface; they're the cheapest review tool in the document.
+
+5. **Emit three sections in one message**:
+   1. **Decisions log** — table of every contract decision (resource naming, pagination, error model, versioning, auth, the `[assumption]`s) with a one-line rationale each
+   2. **The OpenAPI 3.1 YAML** — complete and valid: `info` (with the versioning policy), `servers`, `components.securitySchemes`, `components.schemas` (including the `Problem` schema), paths with examples
+   3. **Open questions** — the unknowns that block freezing the contract, each with who can answer it
+   Start from [`templates/openapi-skeleton.yaml`](templates/openapi-skeleton.yaml).
+
+6. **For event/queue contracts** (the brief says "publish", "consume", "webhook out"): same discipline, AsyncAPI-shaped — channel name, payload schema with the same typing rigor, delivery semantics stated (at-least-once is the default; say it), and the consumer-retry/DLQ expectation in the channel description.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the house conventions: naming, errors, pagination, idempotency, versioning, field-typing rules
+- [`templates/openapi-skeleton.yaml`](templates/openapi-skeleton.yaml) — valid 3.1 starting point with `Problem` schema, security scheme, and one fully-worked resource
+
+## Quality bar
+
+- **The YAML validates.** OpenAPI 3.1, parseable, refs resolve. A contract that doesn't lint is a sketch.
+- **Every operation enumerates its 4xx set** with stable `code` values a client can switch on. "400: Bad Request" alone is an unwritten error contract.
+- **Every decision in the log has a rationale**, and every deviation from `reference.md` conventions is logged as a decision — silent deviation is how two services end up with three pagination styles.
+- **Examples look like production data.** `"id": "string"` in an example means nobody pictured a real call.
+- **No float money, no naked timestamps, no stringly-typed enums.** The three classic contract regrets, all preventable at draft time.
+- **Unsafe operations state their idempotency story.** A reviewer can answer "what happens on retry?" for every POST.
+
+## When to use this skill
+
+- ✅ Designing a new API or new resource before implementation
+- ✅ Frontend and backend (or two teams) need a contract to build against in parallel
+- ✅ A story from `user-story-splitter` whose slice is "expose X over the API"
+- ✅ Drafting the webhook/event contract a partner will consume
+
+## When NOT to use this skill
+
+- ❌ Documenting an API that already exists — that's `guide-builder` (reference archetype)
+- ❌ Choosing REST vs GraphQL vs gRPC — that's `tech-comparison-matrix`; this skill starts after
+- ❌ Reviewing a contract someone else drafted — `doc-critique` or `council-review`
+- ❌ Generating server/client code from the spec — hand the frozen contract to the codegen tool
+
+## Anti-patterns to avoid
+
+- ❌ **RPC verbs in paths** (`/getUser`, `/doRefund`). The resource model is the contract's spine; verbs mean it was never designed.
+- ❌ **The 200-with-error-body.** `200 {"success": false}` breaks every client's error handling; failures use failure status codes.
+- ❌ **Deferring pagination "until we need it".** Retrofitting pagination onto a shipped list endpoint is a breaking change; decide it at draft.
+- ❌ **One giant shared schema** reused for create-request, update-request, and response, with half the fields "ignored on input". Separate the shapes; optionality differs.
+- ❌ **YAML without the decisions log.** Reviewers nitpick property names and never see that offset pagination or float money slipped through.
+- ❌ **Contract churn after parallel build starts.** Once both sides build, every change is a versioned change — the open-questions section exists to drain *before* freezing, not after.