cc-skill-usage CLAUDE.md

cc-skill-usage - Project Context

What this is

A single-file Python CLI. It reads Claude Code's own JSONL transcripts under ~/.claude/projects/ and reports Skill invocation analytics: counts, timing, project breakdown, and the message that triggered each call. Retroactive by design, it reads history already on disk instead of requiring a hook installed ahead of time.

Repository layout

cc-skill-usage    # the entire tool, one file, no package, no build step
README.md         # usage reference for humans
EXAMPLES.md       # goal-oriented scenarios mapped to the command that answers them
CHANGELOG.md      # every fix/feature with the bug it addressed and the verification
llms.txt          # compact index for LLM consumption (llmstxt.org format)
prompts/          # paste-into-a-session prompts. Two are about this tool (scenario
                  # smoke test, deep-dive report); project-reality-check.md is
                  # project-agnostic and works on any repo in any language
.claude/skills/   # skill-usage-report, a Skill that drives and interprets the CLI
LICENSE           # MIT

Adding a doc file means updating three indexes, not one: the README link list, llms.txt (its whole job is being the complete index), and the layout block above. All three drifted once already when EXAMPLES.md and prompts/ landed.

There is no src/, no test suite directory, no CI config. Keep it that way unless a real need forces otherwise: the entire value of this tool is that it is one file you can curl and run.

The one invariant that matters more than any feature

A Skill is invoked only when a transcript record's message.content[] contains a block with type == "tool_use" and name == "Skill". The skill name lives in input.skill. Nothing else counts, not a mention in prose, not a file path, not a human typing the skill's name in a sentence.

This was verified twice, independently, in the same session that built this tool: once by the Python parser, once by a from-scratch grep '"name":"Skill"' | jq '.message.content[]? | select(...) | .input.skill' pipeline. Both returned identical counts on the same data. If you touch the parsing logic in cc-skill-usage, re-run that same cross-check before trusting a new number. Do not assume a plausible-looking count is correct just because the code ran without error.