Claude Code skill usage counts: where they live

Run /skill-doctor for the built-in usage report on supported Claude Code versions. If you are inspecting the underlying file, Claude Code 2.1.233 stored skillUsage in ~/.claude.json, with usageCount and lastUsedAt per recorded skill. That internal data is useful for diagnosis, but it is not a stable API or proof of successful work.

By Miguel Silva · Updated 2026-09-12

See the report before inspecting internal files

On Claude Code v2.1.252 or later, /skill-doctor opens the Stats tab in the plugin manager. It reports skill usage and context cost. It requires feature-flag fetching and is unavailable through Remote Control; run it in the terminal on the host machine. Bundled and enterprise skills are excluded.

Read the recorded counters

The following shape was observed on Claude Code 2.1.233. lastUsedAt is an epoch timestamp in milliseconds. These totals reflect the state retained in this file, not an immutable lifetime record. Resetting or replacing the file can lose them.

"skillUsage": {
  "code-review": { "usageCount": 12, "lastUsedAt": 1786975028876 }
}

jq -r '(.skillUsage // {}) | to_entries | sort_by(-(.value.usageCount // 0))[] | [(.value.usageCount // 0), .key] | @tsv' ~/.claude.json

Do not share the whole configuration file when asking for help: other fields can contain server credentials and project paths.

A missing entry is not a deletion recommendation

In the version inspected, unused skills were not seeded with a zero row. A missing name can also reflect a renamed skill, a qualified plugin name or missing history. Comparing folder names to counter keys produces candidates to investigate, not a reliable list of skills that have never run.

Use the cleanup guide to review candidates and turn them off reversibly.

Counts and history answer different questions

A count says an invocation was recorded. It does not prove the result was correct or that the skill is still useful. The latest timestamp gives recency, while retained session logs can provide examples to inspect. History retention and copied or renamed configurations limit both sources.

Loadout shows recorded skill usage alongside its inventory and editor. Do not interpret an unsupported history format as a zero-use result. The Claude directory guide explains what history can be removed automatically.

Questions

Where does Claude Code store skill usage counts?

Claude Code 2.1.233 stored them under skillUsage in ~/.claude.json. Treat the file format as internal; use /skill-doctor for the current supported report.

Is usageCount a lifetime total?

It is cumulative within the retained state observed in that file, not a guarantee of all-time usage across resets, machines or renamed skills.

Can I see skill usage counts inside Claude Code?

Yes. /skill-doctor is available from v2.1.252 with feature-flag fetching. In an interactive terminal it opens the plugin manager Stats tab.