Agent skills

A skill file that teaches any agent to route through the rail and read receipts.

What the skill does

Route model calls through the TokenSpend rail.
Read receipts for tokens, list-price cost, and route proof.
Check spend and pick a model by list price and context.

Install

Copy the tokenspend folder so the agent loads SKILL.md.

Claude Code

~/.claude/skills/tokenspend/SKILL.md
.claude/skills/tokenspend/SKILL.md

Codex

skills/tokenspend/SKILL.md

OpenCode

OpenCode skills directory/tokenspend/SKILL.md

Hermes

Hermes skills directory/tokenspend/SKILL.md

The file

Canonical copy: skills/tokenspend/SKILL.md

---
name: tokenspend
description: Use when routing model calls through the TokenSpend rail, reading receipts, or checking spend.
---

# TokenSpend

## 1. Rail

Base URL: `https://api.tokenspend.dev/v1`

Auth: `TOKENSPEND_API_KEY` (`tsr_` rail key) as `Authorization: Bearer` or `x-api-key`. Never write the key to files.

## 2. Route a request

Canonical ids are `provider/model` (example: `anthropic/claude-sonnet-5`).

```bash
curl https://api.tokenspend.dev/v1/chat/completions \
  -H "Authorization: Bearer $TOKENSPEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-5","messages":[{"role":"user","content":"hello"}]}'
```

```python
import os
from tokenspend import Client

client = Client(api_key=os.environ["TOKENSPEND_API_KEY"])
print(client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "hello"}],
))
```

## 3. Receipt

Read `x-tokenspend-request-id` from the response headers. Open that receipt for tokens, list-price cost, and route proof. Headers also carry canonical model, revision, and registry version. The serving host is never part of the proof.

## 4. Pick a model

`GET /v1/models` for price and context. Choose by list price and context window.

## 5. Rules

- Prefer the same model id across retries. Send an idempotency key. Reuse a key only for the same request within 24 hours.
- Never send `reasoning_effort` or `stream_options` to Grok models.
- Keep output under about 6K tokens per request on long generations.