Skill Usage Report

Skill Usage Report

Runs and interprets cc-skill-usage (this repo's own CLI) to answer questions about Skill usage. Read README.md and EXAMPLES.md in this repo first if either is unfamiliar, they hold the full flag reference and the scenario-to-command mapping this skill draws from.

Picking the right command

Match the question to the scenario in EXAMPLES.md rather than improvising flags: a monthly recap is --since 30d --show-context, a single skill's health check is <skill-name> --show-context, a repo-versus-everything-else comparison needs two --json runs diffed by skill name, and so on. Default to --show-context whenever the user's question includes "why", "when", or "in what context": counts alone rarely answer that.

The one non-negotiable step: verify before reporting a surprising number

If a count is unexpectedly low, unexpectedly high, or contradicts the user's own memory of how much they used something, do not report it as-is. Cross- check it independently before presenting a verdict:

# raw mentions (expect this far higher, it includes prose, files, summaries)
grep -rl 'skill-name' ~/.claude/projects --include="*.jsonl" | wc -l

# real invocations, independent of cc-skill-usage's own parsing code
grep -rh '"name":"Skill"' ~/.claude/projects --include="*.jsonl" \
  | jq -r '.message.content[]? | select(.type=="tool_use" and .name=="Skill") | .input.skill' \
  | grep -c '^skill-name$'

If the independent pipeline matches cc-skill-usage's own count, the tool is right and the surprise is the invocation-vs-mention gap (measured at 212x on real data during this tool's own development, see README.md), not a bug. State that plainly, with both numbers, rather than either blindly trusting or blindly doubting the first result.

Known blind spots to disclose, not paper over

State these when relevant instead of letting a report imply more precision than the data supports:

• Typed slash-command invocations may be under-represented versus natural-language-triggered ones; the invocation signature this tool matches is a Skill tool call, and that path is well verified, but a purely-typed /skill-name path has fewer confirmed clean examples.
• --show-context occasionally reports "(no preceding user message found)" when the real preceding message was a large tool result, skipped by design to avoid an OOM failure mode. That gap affects the context line only, never the invocation count itself.
• Scanning a live session's own transcript while investigating a skill can make raw text-mention counts (never real invocation counts) pick up an echo of your own prior grep output.

Output shape

Lead with the verdict (the number, and whether it was cross-checked), then the supporting breakdown (by project, by day, sample context), matching the density expected for a factual/debug answer: direct, no hedging once verified, but never state a surprising number as fact without having run the verification step above.