01-usage — Claude Code skill: token usage, how to install
01-usage is a Claude Code skill that reports token use by period or task, split by day, model, agent or ticket, from a local aidd telemetry report.
MIT ★ 571 updated 2026-10-29
/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-telemetry@aidd-frameworkWhat 01-usage does
The skill turns a token-spend question into one aidd telemetry report --json call. First it probes aidd telemetry --help; if the CLI is missing, you get no numbers.
Then it picks a period and a single axis — a day, a model, an agent, a ticket, a session — and fixes the rest as filters. The report is read back as figures, with the gaps stated instead of filled in.
It never sums, averages or converts anything. Input, output, cache read and cache write stay apart, and the total comes from the report's own total field. Measurement itself is off-limits here: the skill only reads what was already recorded. Missing or outdated aidd means no figures at all, and @ai-driven-dev/cli is what you install or update.
What it helps with
- see how many tokens a week consumed, day by day
- find which model or agent burned the most
- check what a single ticket or session cost in tokens
- split one task across the tools and agents that ran it
- compare input and output against cache reads
Example prompts for the agent
- How many tokens did we spend last week, broken down by day?
- Which model used the most tokens this month?
- What did the last session cost in tokens?
How to install 01-usage
1Plugin marketplace
/plugin marketplace add ai-driven-dev/framework/plugin install aidd-telemetry@aidd-frameworkThis installs the whole aidd-telemetry plugin with all its skills
2Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 01-usage -a claude-code3Manually: put the files in place
~/.claude/skills/01-usage/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/01-usage/
1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 01-usage -a codex2Manually: put the files in place
.agents/skills/01-usage/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 01-usage -a cursor2Manually: put the files in place
.cursor/skills/01-usage/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ai-driven-dev/framework plugins/aidd-telemetry/skills/01-usage2Manually: put the files in place
.github/skills/01-usage/SKILL.md1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 01-usage -a gemini-cli2Platform CLI
gemini skills install https://github.com/ai-driven-dev/framework --path plugins/aidd-telemetry/skills/01-usageManually: put the files in place
.devin/skills/01-usage/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 01-usage -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about 01-usage
How do I install 01-usage in Claude Code?
Add the marketplace with /plugin marketplace add ai-driven-dev/framework, then run /plugin install aidd-telemetry@aidd-framework. The skill ships inside the aidd-telemetry plugin.
What does 01-usage do?
It answers token-usage questions from local telemetry: narrows the question to a period and one axis, runs aidd telemetry report --json, and reports the figures alongside whatever the report cannot show.
What does it need to work?
A working aidd from @ai-driven-dev/cli and telemetry that is already being recorded. The skill only reads the report; it does not start collection.
Source text
SKILL.md · MIT
---
name: 01-usage
description: Answer what a period or one piece of work consumed in tokens, per day, model, agent, tool, task, ticket, session, repository or person, from the local measurement. Use when the user asks how many tokens were spent, where the effort went, or what a task or ticket consumed. Not for turning measurement on or off.
argument-hint: question | period
---
# Usage
```mermaid
flowchart TD
question([question]) --> probe{"aidd answers telemetry?"}
probe -->|"no"| absent([say it is missing, answer nothing])
probe -->|"yes"| frame
frame -->|"no axis fits"| refuse([say what the report cannot split by])
frame --> answer
answer -->|"refused or unknown version"| stop([say so])
answer --> told([figures, with what is unknown])
```
## Actions
Run the flow above. Read only the next action file.
| Action | Does |
| --- | --- |
| frame | map the question to a period, one axis and the filters it fixes, and name the command |
| answer | run it, read the JSON, and state the figures with what is unknown |
## Transversal rules
- Probe first. Run `aidd telemetry --help` before any action. When `aidd` is not found, or the command exits non-zero, stop and say plainly that `aidd` is missing or too old to report, name `@ai-driven-dev/cli` as what to install or update, and state that no figure is available. Never answer from memory, from the session, or from anything but the report.
- Every figure comes from `aidd telemetry report --json`. Never add, subtract, average, convert or estimate a number, and never turn tokens into money: the report holds counts only.
- Keep input, output, cache read and cache write apart. A total is the report's own `total`, not a sum made here.
- An unknown is unknown, never zero. Say so whenever the report shows one.
- Read only. Nothing here declares a task, turns measurement on, or changes any file.
© AI-Driven Dev · MIT · ai-driven-dev/framework