majiayu000/spellbook / skills/skill-usage-stats
skill-usage-stats
Verified只读统计 Claude/Codex 的 Skill 使用证据并检查 agent 配置健康。仅用于明确的健康检查、配置诊断、使用排行或低使用候选请求;会识别 enabled 插件并单列批量审计读取。哪些 skill 坏了、互相抢触发、点名却没触发、占用列表预算,或要用历史请求检验改写后的描述,改用 skill-checkup。不要用于规范源、全局/项目/profile/冷存储、投影或退役治理,改用 skill-ecosystem-doctor。忽略引用日志和相邻任务。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| scripts/agent_health.py | script | 10.6 KB |
| scripts/agent_health_claude.py | script | 19.7 KB |
| scripts/agent_health_codex.py | script | 22.9 KB |
| scripts/agent_health_core.py | script | 9.8 KB |
| scripts/skill_usage_report.py | script | 31.5 KB |
scripts/skill_usage_report.py
View on GitHub#!/usr/bin/env python3
"""Skill usage report for the local machine.
Scans Claude Code and Codex session logs and reports skill **usage evidence**,
not an authoritative call count. Claude numbers are exact (structured Skill
tool_use). Codex numbers are implicit evidence only (sed/cat reads of SKILL.md):
on most machines `$skill` mentions and skill-script runs are ~0, and Codex's
authoritative skill_invocation analytics are POSTed to a backend, never stored
locally. So "no local evidence" means exactly that — not "never used".
Outputs a terminal table and a Markdown report (CSV/JSON optional).
Data sources (read-only):
* Claude Code — ~/.claude/projects/*/*.jsonl (structured tool_use, 100%).
* Codex — ~/.codex/sessions/**/rollout-*.jsonl (path regex on
skills/<name>/SKILL.md inside function_call lines, ~95%).
Performance: ripgrep (rg --json) pre-filters the multi-gigabyte Codex corpus;
a pure-Python glob+scan fallback runs when rg is unavailable.
Output language: --lang (zh default, en available).
"""
from __future__ import annotations
import argparse
import csv
import io
import json
import re
import shutil
import subprocess
import sys
from collections import Counter, defaultdict
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Iterator
CLAUDE_DIR_DEFAULT = Path.home() / ".claude"
CODEX_DIR_DEFAULT = Path.home() / ".codex"
CLAUDE_INSTALLED_DIR_DEFAULT = Path.home() / ".claude" / "skills"
CODEX_INSTALLED_DIR_DEFAULTS = [
Path.home() / ".agents" / "skills",
Path.home() / ".codex" / "skills",
]
INSTALLED_DIRS_DEFAULT = [
CLAUDE_INSTALLED_DIR_DEFAULT,
*CODEX_INSTALLED_DIR_DEFAULTS,
]
CLAUDE_PRE_GREP = '"name":"Skill"'
CODEX_GREP_PATTERN = r"skills/[a-z0-9_-]+/SKILL\.md"
CODEX_SKILL_RE = re.compile(r"skills/([a-z0-9_-]+)/SKILL\.md")
CODEX_FUNC_MARKER = '"type":"function_call"'
CODEX_READ_COMMANDS = {"cat", "head", "less", "more", "nl", "sed", "tail"}
CODEX_FNAME_UUID_RE = re.compile(
r"rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-"
r"([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$",
re.I,
)
TOP_DEFAULT = 20
SAMPLE_LIMIT = 5
SAMPLE_WIDTH = 200
ZOMBIE_TABLE_LIMIT = 50
# Terminal table headers stay English (fixed-width alignment). Titles and the
# Markdown report are localized. "zombie" wording is avoided: a skill with no
# local trace is "no_local_evidence", not "never used".
LABELS: dict[str, dict[str, str]] = {
"en": {
"table_top": "Top skills by total evidence:",
"table_zombie": "Installed skills with no local evidence — {n} total:",
"table_zombie_more": "...and {n} more (see Markdown report for the full list).",
"report_title": "# Skill Usage Evidence Report",
"generated_range": "Generated: {gen} | Range: {rng}",
"sources": "Sources: Claude ({cdir}, {cf} files) + Codex ({xdir}, {xf} files)",
"summary": "Installed: {inst} | With evidence: {used} | No local evidence: {none}",
"codex_mode_line": "Codex counting: {mode} | Parse failures: {fail}",
"overview": "## Overview",
"metric": "Metric", "skill_calls": "Skill evidence",
"distinct": "Distinct skills", "files_scanned": "Files scanned",
"top": "## Top Skills by Total Evidence",
"md_th": "| Skill | Claude | Codex (implicit) | Total | Last seen | Projects | Runtime |",
"zombie_h": "## Skills with No Local Evidence — {n}",
"zombie_none": "_None — every installed skill has local evidence._",
"trend": "## Monthly Trend",
"trend_th": "| Month | Evidence | Distinct skills |",
"projects": "## Top Projects",
"projects_th": "| Project | Evidence |",
"caveats": "## Caveats",
"caveat_codex": "- Codex detection is a path-regex heuristic (~95% precision). Non-skill "
"`sed`/`cat` calls that read `SKILL.md` are counted; any true native Codex "
"skill calls are invisible. Claude numbers are exact (structured tool_use).",
"caveat_evidence": "- Codex counts are **implicit evidence only** (sed/cat reads of `SKILL.md`). "
"On this machine `$skill` mentions and skill-script runs are ~0, so they are "
"not a separate column. This is NOT an authoritative call count — Codex's "
"`skill_invocation` analytics are POSTed to a backend and never stored locally.",
"caveat_mode_call": "- Codex numbers reflect SKILL.md reads. In `call` mode each read counts; "
"a skill re-read many times in one session inflates the count.",
"caveat_mode_session": "- Codex numbers reflect SKILL.md reads. In `session` mode each "
"(skill, session) pair counts once, so a skill loaded repeatedly in one "
"session is not inflated.",
"caveat_installed": "- Installed skill set defaults to the enabled runtime dirs: "
"`~/.claude/skills` for Claude, and `~/.agents/skills` "
"(current Codex) plus `~/.codex/skills` (legacy Codex) for Codex.",
"caveat_readonly": "- 'No local evidence' means no local trace, NOT 'never used'. This tool is "
"read-only and never modifies logs, skills, or config.",
"parse_failures_h": "## Parse Failures (samples)",
},
"zh": {
"table_top": "按总证据数排序的 skill:",
"table_zombie": "无本地证据的 skill(已安装但本机日志无调用证据)— 共 {n} 个:",
"table_zombie_more": "……还有 {n} 个(完整列表见 Markdown 报告)。",
"report_title": "# Skill 使用证据报告",
"generated_range": "生成时间:{gen} | 范围:{rng}",
"sources": "数据来源:Claude({cdir},{cf} 个文件)+ Codex({xdir},{xf} 个文件)",
"summary": "已安装:{inst} | 有证据:{used} | 无本地证据:{none}",
"codex_mode_line": "Codex 口径:{mode} | 解析失败:{fail}",
"overview": "## 概览",
"metric": "指标", "skill_calls": "skill 证据数",
"distinct": "不同 skill 数", "files_scanned": "扫描文件数",
"top": "## 按总证据数排序的 skill",
"md_th": "| Skill | Claude | Codex(implicit) | 合计 | 最近出现 | 项目数 | Runtime |",
"zombie_h": "## 无本地证据的 skill — {n}",
"zombie_none": "_无 —— 所有已安装 skill 本机都有调用证据。_",
"trend": "## 月度趋势",
"trend_th": "| 月份 | 证据数 | 不同 skill 数 |",
"projects": "## 项目分布(Top 10)",
"projects_th": "| 项目 | 证据数 |",
"caveats": "## 注意事项",
"caveat_codex": "- Codex 识别是路径正则启发式(约 95% 精度)。非 skill 的 "
"`sed`/`cat` 读取 `SKILL.md` 也会被计入;Codex 原生 skill 调用(若存在)不可见。"
"Claude 数字精确(结构化 tool_use)。",
"caveat_evidence": "- Codex 计数**只是 implicit 证据**(sed/cat 读 `SKILL.md`)。本机上 "
"`$skill` mention 和 skill 脚本运行约为 0,故未单列。这**不是权威调用计数**"
"——Codex 的 `skill_invocation` analytics 直接 POST 到后端,不存本机。",
"caveat_mode_call": "- Codex 数字反映 SKILL.md 的读取。`call` 口径下每次读取都计数,"
"同一会话内反复读取会抬高计数。",
"caveat_mode_session": "- Codex 数字反映 SKILL.md 的读取。`session` 口径下每个 "
"(skill, 会话) 只计一次,同一会话内反复加载不重复计数。",
"caveat_installed": "- 已安装 skill 集合默认取已启用 runtime 的安装目录:Claude 使用 "
"`~/.claude/skills`;Codex 使用 `~/.agents/skills`(当前 Codex)"
"与 `~/.codex/skills`(旧 Codex)。",
"caveat_readonly": "- “无本地证据”只表示本机没有痕迹,**不等同“从未使用”**。本工具只读,"
"绝不修改日志、skill 或配置。",
"parse_failures_h": "## 解析失败(样本)",
},
}
@dataclass(frozen=True)
class ClaudeHit:
skill: str
ts: str
cwd: str
session_id: str
@dataclass(frozen=True)
class CodexHit:
skill: str
ts: str
cwd: str
session_id: str
@dataclass
class SkillStat:
name: str
claude_calls: int = 0
codex_calls: int = 0
first_used: str | None = None
last_used: str | None = None
last_runtime: str | None = None
projects: Counter = field(default_factory=Counter)
runtimes: set[str] = field(default_factory=set)
@property
def total(self) -> int:
return self.claude_calls + self.codex_calls
@dataclass
class AggResult:
stats: dict[str, SkillStat]
installed: set[str]
generated_at: str
claude_files_scanned: int
codex_files_scanned: int
parse_failures: int
parse_failure_samples: list[str]
codex_mode: str
earliest: str | None
latest: str | None
by_month: Counter
by_month_skill: dict[str, Counter]
def _record_sample(samples: list[str], text: str) -> None:
if len(samples) >= SAMPLE_LIMIT:
return
samples.append(text[:SAMPLE_WIDTH])
def _is_func_call_line(text: str) -> bool:
return CODEX_FUNC_MARKER in text
def _parse_claude_line(text: str) -> list[ClaudeHit]:
try:
d = json.loads(text)
except (json.JSONDecodeError, ValueError):
return []
if not isinstance(d, dict):
return []
msg = d.get("message")
if not isinstance(msg, dict):
return []
content = msg.get("content")
if not isinstance(content, list):
return []
ts = d.get("timestamp") or ""
cwd = d.get("cwd") or ""
session_id = d.get("sessionId") or ""
hits: list[ClaudeHit] = []
for item in content:
if not isinstance(item, dict):
continue
if item.get("type") != "tool_use" or item.get("name") != "Skill":
continue
raw_input = item.get("input")
if not isinstance(raw_input, dict):
continue
skill = raw_input.get("skill")
if isinstance(skill, str) and skill.strip():
hits.append(ClaudeHit(skill=skill.strip(), ts=ts, cwd=cwd, session_id=session_id))
return hits
def _codex_args(payload: dict) -> dict | None:
args_raw = payload.get("arguments")
if isinstance(args_raw, str):
try:
parsed = json.loads(args_raw)
except (json.JSONDecodeError, ValueError):
return None
return parsed if isinstance(parsed, dict) else None
return None
def _codex_read_command(payload: dict) -> str:
if payload.get("name") != "exec_command":
return ""
args = _codex_args(payload)
if not isinstance(args, dict) or not isinstance(args.get("cmd"), str):
return ""
cmd = args["cmd"].strip()
if not cmd:
return ""
first_token = cmd.split(maxsplit=1)[0]
if Path(first_token).name == "cat" and re.search(r"(^|\s)(>>?|<<)", cmd):
return ""
if Path(first_token).name not in CODEX_READ_COMMANDS:
return ""
return cmd
def _codex_workdir(payload: dict, meta_fallback: dict | None) -> str:
args = _codex_args(payload)
if isinstance(args, dict) and isinstance(args.get("workdir"), str):
return args["workdir"]
if isinstance(meta_fallback, dict) and isinstance(meta_fallback.get("cwd"), str):
return meta_fallback["cwd"]
return ""
def _codex_session_id(payload: dict, meta_fallback: dict | None, file_path: Path) -> str:
if isinstance(meta_fallback, dict) and isinstance(meta_fallback.get("id"), str):
return meta_fallback["id"]
match = CODEX_FNAME_UUID_RE.search(file_path.name)
return match.group(1) if match else ""
def _parse_codex_hits(text: str, file_path: Path, meta_fallback: dict | None = None) -> list[CodexHit]:
if not _is_func_call_line(text):
return []
try:
d = json.loads(text)
except (json.JSONDecodeError, ValueError):
return []
if not isinstance(d, dict):
return []
payload = d.get("payload")
if not isinstance(payload, dict) or payload.get("type") != "function_call":
return []
cmd = _codex_read_command(payload)
if not cmd:
return []
cwd = _codex_workdir(payload, meta_fallback)
session_id = _codex_session_id(payload, meta_fallback, file_path)
ts = d.get("timestamp") or ""
return [
CodexHit(skill=match.group(1), ts=ts, cwd=cwd, session_id=session_id)
for match in CODEX_SKILL_RE.finditer(cmd)
]
def _parse_codex_line(text: str, file_path: Path, meta_fallback: dict | None = None) -> CodexHit | None:
hits = _parse_codex_hits(text, file_path, meta_fallback)
return hits[0] if hits else None
def _python_fallback(pattern: str, root: Path) -> Iterator[tuple[Path, str]]:
regex = re.compile(pattern)
for path in root.rglob("*.jsonl"):
try:
with path.open("r", encoding="utf-8", errors="replace") as handle:
for line in handle:
if regex.search(line):
yield path, line.rstrip("\n")
except OSError:
continue
def _run_rg(pattern: str, root: Path, *, no_rg: bool = False) -> Iterator[tuple[Path, str]]:
if no_rg or shutil.which("rg") is None:
yield from _python_fallback(pattern, root)
return
cmd = ["rg", "--json", "--no-heading", "-n", "--", pattern, str(root)]
try:
proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
except OSError:
yield from _python_fallback(pattern, root)
return
if proc.returncode not in (0, 1):
sys.stderr.write(f"[warn] rg failed (rc={proc.returncode}); using Python scan\n")
yield from _python_fallback(pattern, root)
return
for raw in proc.stdout.splitlines():
try:
event = json.loads(raw)
except (json.JSONDecodeError, ValueError):
continue
if event.get("type") != "match":
continue
data = event.get("data") or {}
path_text = (data.get("path") or {}).get("text")
line_text = (data.get("lines") or {}).get("text")
if path_text and line_text is not None:
yield Path(path_text), line_text.rstrip("\n")
def _count_scanned_files(root: Path) -> int:
if not root.exists():
return 0
return sum(1 for _ in root.rglob("*.jsonl"))
def _load_codex_session_meta(path: Path) -> dict | None:
try:
with path.open("r", encoding="utf-8", errors="replace") as handle:
for line in handle:
if '"type":"session_meta"' not in line and '"session_meta"' not in line:
continue
try:
event = json.loads(line)
except (json.JSONDecodeError, ValueError):
continue
if not isinstance(event, dict) or event.get("type") != "session_meta":
continue
payload = event.get("payload")
return payload if isinstance(payload, dict) else None
except OSError:
return None
return None
def default_installed_dirs(include_claude: bool = True, include_codex: bool = True) -> list[Path]:
return ([CLAUDE_INSTALLED_DIR_DEFAULT] if include_claude else []) + (CODEX_INSTALLED_DIR_DEFAULTS if include_codex else [])
def discover_installed_skills(dirs: list[Path]) -> set[str]:
names: set[str] = set()
for directory in dirs:
if not directory.is_dir():
continue
for child in directory.iterdir():
if child.is_dir() and not child.name.startswith(".") and (child / "SKILL.md").is_file():
names.add(child.name)
return names
def collect_claude(
claude_dir: Path, *, since: str | None = None, no_rg: bool = False
) -> tuple[list[ClaudeHit], int, list[str]]:
projects = claude_dir / "projects"
hits: list[ClaudeHit] = []
failures = 0
samples: list[str] = []
if not projects.is_dir():
return hits, failures, samples
for _path, text in _run_rg(CLAUDE_PRE_GREP, projects, no_rg=no_rg):
if CLAUDE_PRE_GREP not in text:
continue
parsed = _parse_claude_line(text)
if not parsed:
failures += 1
_record_sample(samples, text)
continue
for hit in parsed:
if since and hit.ts[:7] < since:
continue
hits.append(hit)
return hits, failures, samples
def _codex_roots_for_since(sessions: Path, since: str | None) -> list[Path]:
return [sessions]
def collect_codex(
codex_dir: Path,
*,
since: str | None = None,
dedup_mode: str = "session",
no_rg: bool = False,
) -> tuple[list[CodexHit], int, list[str]]:
sessions = codex_dir / "sessions"
hits: list[CodexHit] = []
failures = 0
samples: list[str] = []
if not sessions.is_dir():
return hits, failures, samples
seen: set[tuple[str, str]] = set()
session_meta_by_path: dict[Path, dict | None] = {}
for root in _codex_roots_for_since(sessions, since):
for path, text in _run_rg(CODEX_GREP_PATTERN, root, no_rg=no_rg):
if path not in session_meta_by_path:
session_meta_by_path[path] = _load_codex_session_meta(path)
parsed_hits = _parse_codex_hits(text, path, session_meta_by_path[path])
if parsed_hits:
for hit in parsed_hits:
if since and hit.ts[:7] < since: continue
if dedup_mode == "session":
key = (hit.skill, hit.session_id or str(path))
if key in seen:
continue
seen.add(key)
hits.append(hit)
elif _is_func_call_line(text):
failures += 1
_record_sample(samples, "[redacted codex function_call parse failure]")
return hits, failures, samples
def _bump(stat: SkillStat, runtime: str, ts: str, cwd: str, calls: int) -> None:
if runtime == "claude":
stat.claude_calls += calls
else:
stat.codex_calls += calls
stat.runtimes.add(runtime)
if ts:
if stat.first_used is None or ts < stat.first_used:
stat.first_used = ts
if stat.last_used is None or ts > stat.last_used:
stat.last_used = ts
stat.last_runtime = runtime
if cwd:
stat.projects[cwd] += calls
def aggregate(
claude_hits: list[ClaudeHit],
codex_hits: list[CodexHit],
installed: set[str],
*,
claude_files_scanned: int = 0,
codex_files_scanned: int = 0,
parse_failures: int = 0,
parse_failure_samples: list[str] | None = None,
codex_mode: str = "session",
) -> AggResult:
stats: dict[str, SkillStat] = {}
by_month: Counter = Counter()
by_month_skill: dict[str, Counter] = defaultdict(Counter)
def record(hit: CodexHit | ClaudeHit, runtime: str) -> None:
stat = stats.setdefault(hit.skill, SkillStat(name=hit.skill))
_bump(stat, runtime, hit.ts, hit.cwd, 1)
month = hit.ts[:7]
if len(month) == 7:
by_month[month] += 1
by_month_skill[month][hit.skill] += 1
for hit in claude_hits:
record(hit, "claude")
for hit in codex_hits:
record(hit, "codex")
timestamps = [h.ts for h in claude_hits + codex_hits if h.ts]
return AggResult(
stats=stats,
installed=installed,
generated_at=datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
claude_files_scanned=claude_files_scanned,
codex_files_scanned=codex_files_scanned,
parse_failures=parse_failures,
parse_failure_samples=parse_failure_samples or [],
codex_mode=codex_mode,
earliest=min(timestamps) if timestamps else None,
latest=max(timestamps) if timestamps else None,
by_month=by_month,
by_month_skill=by_month_skill,
)
def _runtime_label(runtimes: set[str]) -> str:
if {"claude", "codex"} <= runtimes:
return "both"
if "codex" in runtimes:
return "codex"
if "claude" in runtimes:
return "claude"
return "-"
def _format_table(headers: list[str], rows: list[list[str]], widths: list[int]) -> str:
sep = " "
header_line = sep.join(h.ljust(widths[i]) for i, h in enumerate(headers))
divider = sep.join("-" * widths[i] for i in range(len(headers)))
body_lines = [
sep.join(str(c[i]).ljust(widths[i])[: widths[i]] for i in range(len(c))) for c in rows
]
return "\n".join([header_line, divider, *body_lines])
def render_table(agg: AggResult, top: int, lang: str = "zh") -> str:
L = LABELS[lang]
ranked = sorted(agg.stats.values(), key=lambda s: s.total, reverse=True)
headers = ["SKILL", "CLAUDE", "CODEX", "TOTAL", "LAST", "PROJECTS", "RUNTIME"]
widths = [30, 7, 7, 7, 12, 9, 8]
rows = [
[
s.name, str(s.claude_calls), str(s.codex_calls), str(s.total),
(s.last_used or "")[:10], str(len(s.projects)), _runtime_label(s.runtimes),
]
for s in ranked[:top]
]
out = [L["table_top"], _format_table(headers, rows, widths)]
no_evidence = sorted(agg.installed - set(agg.stats))
if no_evidence:
shown = no_evidence[:ZOMBIE_TABLE_LIMIT]
more = len(no_evidence) - len(shown)
z_rows = [[z, "-", "-", "0", "-", "0", "-"] for z in shown]
out.append("")
out.append(L["table_zombie"].format(n=len(no_evidence)))
out.append(_format_table(headers, z_rows, [40, 7, 7, 7, 12, 9, 8]))
if more > 0:
out.append(L["table_zombie_more"].format(n=more))
return "\n".join(out)
def _range_str(agg: AggResult) -> str:
if not agg.earliest:
return "n/a"
return f"{agg.earliest[:10]} → {agg.latest[:10]}" if agg.latest else agg.earliest[:10]
def render_markdown(agg: AggResult, top: int, lang: str = "zh") -> str:
L = LABELS[lang]
distinct = len(agg.stats)
installed_with_evidence = len(agg.installed & set(agg.stats))
no_evidence = sorted(agg.installed - set(agg.stats))
total_claude = sum(s.claude_calls for s in agg.stats.values())
total_codex = sum(s.codex_calls for s in agg.stats.values())
distinct_claude = sum(1 for s in agg.stats.values() if s.claude_calls)
distinct_codex = sum(1 for s in agg.stats.values() if s.codex_calls)
lines = [
L["report_title"], "",
L["generated_range"].format(gen=agg.generated_at, rng=_range_str(agg)),
L["sources"].format(cdir=CLAUDE_DIR_DEFAULT, cf=agg.claude_files_scanned,
xdir=CODEX_DIR_DEFAULT, xf=agg.codex_files_scanned),
L["summary"].format(inst=len(agg.installed), used=installed_with_evidence, none=len(no_evidence)),
L["codex_mode_line"].format(mode=agg.codex_mode, fail=agg.parse_failures),
"",
L["overview"], "",
f"| {L['metric']} | Claude | Codex | Total |",
"|---|---|---|---|",
f"| {L['skill_calls']} | {total_claude} | {total_codex} | {total_claude + total_codex} |",
f"| {L['distinct']} | {distinct_claude} | {distinct_codex} | {distinct} |",
f"| {L['files_scanned']} | {agg.claude_files_scanned} | {agg.codex_files_scanned} | "
f"{agg.claude_files_scanned + agg.codex_files_scanned} |",
"",
L["top"], "",
L["md_th"],
"|---|---|---|---|---|---|---|",
]
for s in sorted(agg.stats.values(), key=lambda x: x.total, reverse=True)[:top]:
lines.append(
f"| `{s.name}` | {s.claude_calls} | {s.codex_calls} | {s.total} | "
f"{(s.last_used or '')[:10]} | {len(s.projects)} | {_runtime_label(s.runtimes)} |"
)
lines += ["", L["zombie_h"].format(n=len(no_evidence)), ""]
if no_evidence:
for z in no_evidence:
lines.append(f"- `{z}`")
else:
lines.append(L["zombie_none"])
lines += ["", L["trend"], "", L["trend_th"], "|---|---|---|"]
for month in sorted(agg.by_month):
lines.append(f"| {month} | {agg.by_month[month]} | {len(agg.by_month_skill[month])} |")
project_counter: Counter = Counter()
for stat in agg.stats.values():
project_counter.update(stat.projects)
lines += ["", L["projects"], "", L["projects_th"], "|---|---|"]
for project, count in project_counter.most_common(10):
label = Path(project).name or project
lines.append(f"| `{label}` ({project}) | {count} |")
lines += ["", L["caveats"], "",
L["caveat_codex"],
L["caveat_evidence"],
L["caveat_mode_call"] if agg.codex_mode == "call" else L["caveat_mode_session"],
L["caveat_installed"],
L["caveat_readonly"]]
if agg.parse_failure_samples:
lines += ["", L["parse_failures_h"], ""]
for sample in agg.parse_failure_samples:
lines.append(f"- `{sample}`")
return "\n".join(lines) + "\n"
def _stat_to_dict(stat: SkillStat) -> dict:
return {
"name": stat.name,
"claude_calls": stat.claude_calls,
"codex_calls": stat.codex_calls,
"total": stat.total,
"first_used": stat.first_used,
"last_used": stat.last_used,
"last_runtime": stat.last_runtime,
"projects": dict(stat.projects),
"runtimes": sorted(stat.runtimes),
}
def render_json(agg: AggResult) -> str:
payload = {
"generated_at": agg.generated_at,
"range": {"earliest": agg.earliest, "latest": agg.latest},
"installed_count": len(agg.installed),
"installed": sorted(agg.installed),
"total_claude_calls": sum(s.claude_calls for s in agg.stats.values()),
"total_codex_calls": sum(s.codex_calls for s in agg.stats.values()),
"codex_mode": agg.codex_mode,
"parse_failures": agg.parse_failures,
"claude_files_scanned": agg.claude_files_scanned,
"codex_files_scanned": agg.codex_files_scanned,
"by_month": dict(sorted(agg.by_month.items())),
"stats": [_stat_to_dict(s) for s in sorted(agg.stats.values(), key=lambda x: x.total, reverse=True)],
}
return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
def render_csv(agg: AggResult) -> str:
"""Per-skill CSV. Column names stay English (stable data interface).
status: used (installed + has local evidence), no_local_evidence (installed,
no local trace — NOT 'never used'), uninstalled (evidence in logs but not in
the installed set).
"""
buf = io.StringIO()
writer = csv.writer(buf)
writer.writerow(
["skill", "claude_calls", "codex_calls", "total", "first_used",
"last_used", "last_runtime", "projects", "runtimes", "status"]
)
for name in sorted(set(agg.stats) | agg.installed):
stat = agg.stats.get(name)
if stat is None:
writer.writerow([name, 0, 0, 0, "", "", "", 0, "-", "no_local_evidence"])
continue
status = "used" if name in agg.installed else "uninstalled"
writer.writerow(
[name, stat.claude_calls, stat.codex_calls, stat.total,
stat.first_used or "", stat.last_used or "", stat.last_runtime or "",
len(stat.projects), _runtime_label(stat.runtimes), status]
)
return buf.getvalue()
def _eprint(msg: str, quiet: bool) -> None:
if not quiet:
sys.stderr.write(msg + "\n")
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--claude-dir", type=Path, default=CLAUDE_DIR_DEFAULT)
parser.add_argument("--codex-dir", type=Path, default=CODEX_DIR_DEFAULT)
parser.add_argument("--top", type=int, default=TOP_DEFAULT)
parser.add_argument("--since", help="Only count calls in YYYY-MM or later")
parser.add_argument("--out", help="Markdown output path (- for stdout)")
parser.add_argument("--json", dest="json_path", help="Also write aggregate JSON to this path")
parser.add_argument("--csv", dest="csv_path", help="Also write a per-skill CSV to this path")
parser.add_argument("--no-claude", action="store_true")
parser.add_argument("--no-codex", action="store_true")
parser.add_argument("--codex-mode", choices=["call", "session"], default="session")
parser.add_argument("--installed-dirs", nargs="+", type=Path)
parser.add_argument("--lang", choices=["zh", "en"], default="zh", help="Output language for the report")
parser.add_argument("--no-rg", action="store_true")
parser.add_argument("--quiet", action="store_true")
args = parser.parse_args(argv)
installed_dirs = args.installed_dirs or default_installed_dirs(not args.no_claude, not args.no_codex)
installed = discover_installed_skills(installed_dirs)
claude_hits: list[ClaudeHit] = []
codex_hits: list[CodexHit] = []
failures = 0
samples: list[str] = []
claude_files = 0
codex_files = 0
if not args.no_claude:
claude_projects = args.claude_dir / "projects"
if claude_projects.is_dir():
_eprint(f"[info] scanning Claude logs in {claude_projects} ...", args.quiet)
claude_hits, c_fail, c_samples = collect_claude(
args.claude_dir, since=args.since, no_rg=args.no_rg
)
claude_files = _count_scanned_files(claude_projects)
failures += c_fail
samples += c_samples
_eprint(f"[info] Claude: {len(claude_hits)} calls in {claude_files} files", args.quiet)
else:
_eprint(f"[info] Claude dir missing: {claude_projects}, skipping", args.quiet)
if not args.no_codex:
codex_sessions = args.codex_dir / "sessions"
if codex_sessions.is_dir():
_eprint(f"[info] scanning Codex logs in {codex_sessions} ...", args.quiet)
codex_hits, x_fail, x_samples = collect_codex(
args.codex_dir, since=args.since, dedup_mode=args.codex_mode, no_rg=args.no_rg
)
codex_files = _count_scanned_files(codex_sessions)
failures += x_fail
samples += x_samples
_eprint(f"[info] Codex: {len(codex_hits)} implicit-evidence hits ({args.codex_mode} mode)", args.quiet)
else:
_eprint(f"[info] Codex dir missing: {codex_sessions}, skipping", args.quiet)
agg = aggregate(
claude_hits,
codex_hits,
installed,
claude_files_scanned=claude_files,
codex_files_scanned=codex_files,
parse_failures=failures,
parse_failure_samples=samples,
codex_mode=args.codex_mode,
)
table = render_table(agg, args.top, args.lang)
markdown = render_markdown(agg, args.top, args.lang)
out_to_stdout = args.out == "-"
if out_to_stdout:
sys.stdout.write(markdown)
else:
table_dest = sys.stderr if args.out else sys.stdout
table_dest.write(table + "\n")
out_path = Path(args.out) if args.out else Path.home() / f"skill-usage-report-{datetime.now().strftime('%Y%m%d')}.md"
out_path.write_text(markdown, encoding="utf-8")
_eprint(f"[info] Markdown report written to {out_path}", args.quiet)
if args.json_path:
Path(args.json_path).write_text(render_json(agg), encoding="utf-8")
_eprint(f"[info] JSON written to {args.json_path}", args.quiet)
if args.csv_path:
Path(args.csv_path).write_text(render_csv(agg), encoding="utf-8")
_eprint(f"[info] CSV written to {args.csv_path}", args.quiet)
return 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |