shelf Docs

shelf insights

Shows how many tokens of skill descriptions each project loads at every session start, and which skills agents actually used in the last 30 days. Inside a project it shows that project; outside, or with --all, every project and library skill.

On this page 
shelf insights [options]
OptionTypeDefaultDescription
--allbooleanEvery project and skill, even inside a project

Also takes the global options --json and --actor (CLI overview).

What it does

Reads, never changes: it doesn't sync or expire anything.

  • Session cost of a skill is its name plus description (characters / 4, rounded up), from the revision the project actually holds.
  • On use cost is the whole SKILL.md.
  • Loaded everywhere are the valid skills in every harness's user-level skill directory (~/.claude/skills, ~/.agents/skills, ~/.copilot/skills and the others in Harnesses), counted once each. They load in every project.
  • Active days count the UTC days in the last 30 on which a use was recorded (by the hooks or shelf used).

Projects whose directory no longer exists are left out.

Examples

Inside a project:

terminal
shelf insights
billing-api: ~226 tokens of skill descriptions load at every session start
  ~136 from skills loaded everywhere (shelf, frontend-design, web-research)
  ~90 from 4 borrowed skills; the full SKILL.md loads only when used

SKILL           SESSION  ON USE  ACTIVE DAYS (30D)  LAST USED
api-design      ~25      ~127    10                 today
sql-migrations  ~25      ~127    3                  2d ago
release-notes   ~21      ~114    1                  9d ago
git-hygiene     ~19      ~129    0                  never

Every project and library skill: shelf insights --all

Everywhere:

terminal
shelf insights --all
Context at session start (skill names and descriptions; tokens estimated as chars / 4)
PROJECT      TOTAL  BORROWED  EVERYWHERE  SKILLS
storefront   ~244   ~108      ~136        4
billing-api  ~226   ~90       ~136        4
mobile-app   ~194   ~58       ~136        2
docs-site    ~179   ~43       ~136        2

Library skills, last 30 days
SKILL                 ACTIVE DAYS  LAST USED  PROJECTS  SESSION  ON USE  
react-best-practices  12           today      2         ~37      ~195    
api-design            10           today      1         ~25      ~127    
playwright-testing    3            1d ago     1         ~27      ~143    
release-notes         3            today      3         ~21      ~114    
sql-migrations        3            2d ago     1         ~25      ~127    
accessibility-audit   2            18d ago    1         ~25      ~122    
commit-messages       0            never      0         ~20      ~48     never used
git-hygiene           0            never      2         ~19      ~129    never used
pdf-tools             0            34d ago    1         ~22      ~116    unused 30d

Loaded everywhere (every session, every project): shelf ~66, frontend-design ~50, web-research ~20

never used: no use was ever recorded. unused 30d: none in the last 30 days.

JSON output

The JSON is the same with or without --all. Trimmed to one item per array, and daily to its last value:

json
{"schemaVersion":1,"ok":true,"data":{"globalSkills":[{"name":"shelf","harnessDirs":[".agents/skills",".claude/skills"],"descriptionTokens":66,"bodyTokens":255,"bundled":true}],"invalidGlobalSkills":0,"projects":[{"id":"271949f0-7dc1-437e-93b2-ccb03cfec021","name":"billing-api","path":"/home/me/code/billing-api","skills":[{"skill":"api-design","descriptionTokens":33,"bodyTokens":83,"lastUsedAt":null,"activeDays30":0}],"sessionTokens":68,"globalTokens":66}],"skills":[{"name":"api-design","descriptionTokens":33,"bodyTokens":83,"borrowers":2,"activeDays30":0,"lastUsedAt":null,"neverUsed":true,"daily":[0]}],"usage":{"days":["2026-10-07"],"active":[2]},"currentProject":null}}
FieldMeaning
globalSkills[]User-level skills: name, harnessDirs (relative to home), descriptionTokens, bodyTokens, bundled (shelf's own skill).
invalidGlobalSkillsUser-level skill directories with an invalid SKILL.md, left out.
projects[]id, name, path, skills[] (skill, descriptionTokens, bodyTokens, lastUsedAt, activeDays30), sessionTokens (borrowed), globalTokens (loaded everywhere).
skills[]Every library skill: name, descriptionTokens, bodyTokens, borrowers, activeDays30, lastUsedAt, neverUsed, daily (projects using it on each of the 30 days, oldest first).
usage.daysThe 30 UTC dates, oldest first; the last is today.
usage.activeDistinct skills used on each day.
currentProjectThe project containing the working directory (same shape as projects[]), or null.

Errors

None specific to this command.