skillcost 1.0.3

Estimates the token cost of agent skills and their linked resources

skillcost

Estimates the token cost of agent skills and their linked resources.

Given a target file (typically a SKILL.md), skillcost counts tokens and crawls all linked files and URLs to produce three cost figures:

Metric	Description
Resident	Tokens loaded on every prompt, just because the skill is installed.
Baseline	Tokens loaded when the skill is invoked — the skill file plus any @-includes.
Maximum	Tokens loaded if the agent follows every link in the skill file.

This also works on CLAUDE.md or any other plain-text UTF-8 file.

Installation

Requires Python 3.12+ and uv.

uv sync

Usage

uv run python -m main <path/to/file>

Output defaults to human-readable text. Pass --json or --yaml for machine-readable output.

uv run python -m main SKILL.md
uv run python -m main SKILL.md --json
uv run python -m main SKILL.md --yaml

Example output

Token Cost Report
=================
  Resident : 97
  Baseline : 1,940
  Maximum  : 18,390

Files (24)
  /path/to/reference/conventions.md                                       926
  /path/to/reference/utilities.md                                       1,751
  ...

Links
  @-directives : 0
  Local links  : 17
  HTTP links   : 0

How links are counted

skillcost recognizes two link syntaxes in Markdown files:

• @{relative/path} — an include directive; the file is always fetched when the skill is invoked, so it counts toward the baseline cost.
• [text](relative/path) — a standard Markdown link; followed recursively and counted toward the maximum cost only.

HTTP links (https://...) are fetched and counted toward the maximum cost only.

Contributing

See CONTRIBUTING.md.