Metadata-Version: 2.4
Name: skillcost
Version: 1.0.3
Summary: Estimates the token cost of agent skills and their linked resources
Requires-Python: >=3.12
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tiktoken>=0.12.0
Description-Content-Type: text/markdown

# 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](https://github.com/astral-sh/uv).

```sh
uv sync
```

## Usage

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

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

```sh
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](CONTRIBUTING.md).
