agentleFS
PydanticKnown publisherpydantic/genai-prices/.claude/skills/add-price-model/SKILL.md

add-price-model

Skill416 starsChanged 32 days agoMITView on GitHub

Add a new LLM model (or provider) to genai-prices pricing data, or change the price of one that is already there. Use when asked to add/update pricing for a model — e.g. "add grok 4.5", "add the new Claude", "update openai o5 prices", "provider X cut its prices". Covers sourcing prices, probing OpenRouter for undocumented dated snapshot IDs, editing the provider YAML, preserving price history across a rate change, building, verifying resolution, and opening the PR.

  • Reads credentials
  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 6 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Never hand-edit generated data.

    line 13
  2. Distinctive:

    Never read a developer's home-directory credentials from the agent.

    line 69
  3. Distinctive:

    Do not defer verified provider prices because an undocumented alias could not be probed.

    line 71
  4. Very specific:

    Add a price_comments field when a value needs explanation/reference.

    line 102
  5. Very specific:

    Do not add a new unit to prices/units.yml to make a model fit.

    line 111
  6. Distinctive:

    When adding a new flagship, move the family-level alias off the previous flagship onto the new entry (add it here, delete it there).

    line 121
  7. Very specific:

    Add a dated entry instead.

    line 139
  8. Very specific:

    Put the entry with no constraint first.

    line 154
  9. Very specific:

    Check every price_variants rate card separately.

    line 161
  10. Distinctive:

    Verify both sides of the boundary:

    line 170
  11. Very specific:

    Use make build, not just make build-prices.

    line 190
  12. Very specific:

    Never force-push. PR body: pricing table, sources (provider docs + OpenRouter for cache rate), and scope notes (e.g.

    line 243
  13. Distinctive:

    After pushing, don't go idle — poll until CI is green and every reviewer comment (cubic included) is addressed or dismissed (see AGENTS.md).

    line 247
  14. Distinctive:

    Only when a reseller (Bedrock / Vertex) genuinely hasn't shipped yet do you defer _that_ provider — name it in the PR body and follow up in …

    line 254

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add a model to genai-prices

Never hand-edit generated data. Edit the provider YAML in prices/providers/<provider>.yml, then make build. The live published payload is prices/new_data/v2/data.json; prices/data.json and prices/data_slim.json are frozen v1 snapshots that no build step writes any more — leave them alone.

0. Scope: every provider that hosts this model, not just the one you were named

A model rarely lives on one provider. The big vendors' flagships are resold across clouds and aggregators, and each needs its own YAML entry — the same request "add the new Claude" means anthropic.yml and aws.yml (Bedrock) and google.yml (Vertex) and openrouter.yml. Adding only the direct-vendor entry is the most common miss (it's what happened for Opus 5 in #501, requiring the follow-up #502). Before editing, list every provider that hosts the model and cover them in one PR:

  • Direct vendor — anthropic.yml, openai.yml, google.yml (Gemini), x_ai.yml, etc.
  • Aggregators/gateways — openrouter.yml (usually day-one; often exposes -fast/:beta variants).
  • Cloud resellers — aws.yml (Bedrock: global.* + regional.* split, regional ~+10%), google.yml (Vertex Claude entries live here too, separate from Gemini), Azure (azure.yml is Azure OpenAI only — Claude on Foundry is out of scope there; note it, don't force it).

Confirm hosting from each provider's docs/model list; don't assume. If a reseller genuinely hasn't shipped it yet, that's the only reason to defer a provider — say which one and why in the PR, and follow up when it lands (see "Provider rollout timing" below). "I was only asked about provider X" is not a reason to skip the others.

1. Branch

In a GitHub agentic workflow, keep its supplied checkout and follow the workflow's publication procedure. The trusted safe-output handler creates the PR. Do not run this skill's fetch, push, or gh pr create commands there.

Contribute via a branch on origin (this repo is pydantic/genai-prices, no fork). Always base off freshly-fetched upstream:

git fetch origin && git checkout -b <slug> origin/main

2. Source the prices (cite everything)

Get input / cached-input / output per-Mtok and context window from the provider's own docs first (authoritative). Vendor docs often omit the cache-read rate — cross-check OpenRouter's endpoint API, which exposes it:

https://openrouter.ai/api/v1/models/<provider>/<model>/endpoints

pricing.input_cache_read is per-token — ×1,000,000 for the per-Mtok value. Record every number's source; put them in the PR body.

3. Probe OpenRouter for the dated snapshot ID (do this every time)

Providers ship dated snapshot IDs (e.g. grok-4.5-20260708) that aren't in their docs. A real minimal request returns the resolved dated ID in the response model field — capture it so the YAML match covers future dated snapshots.

In a GitHub agentic workflow, use only a probe tool or credential explicitly supplied by the workflow. Never read a developer's home-directory credentials from the agent. If no probe is available, verify published IDs from official catalogs, leave undocumented snapshot aliases unchanged, and record the missing snapshot verification. Do not defer verified provider prices because an undocumented alias could not be probed.

For a local session, the key lives in ~/ai-coding-tools/.env as OPENROUTER_API_KEY. Don't reference secret env vars in an inline command (a hook blocks it and env-run rejects it) — put the request in a script that consumes the var internally, then run it with env-run:

# scratchpad/or_probe.sh consumes $OPENROUTER_API_KEY internally
~/.claude/scripts/env-run ~/ai-coding-tools/.env -- bash scratchpad/or_probe.sh
curl -sS https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer ${OPENROUTER_API_KEY}" -H "Content-Type: application/json" \
  -d '{"model":"<provider>/<model>","messages":[{"role":"user","content":"hi"}]}' \
  | jq '{id, model, provider}'

The model field (e.g. x-ai/grok-4.5-20260708) reveals the snapshot. A regex: '^<model>-\d{8}$' clause (plus a <provider>/-prefixed variant) makes it resolve without a separate entry.

4. Add the YAML entry

Match a sibling model's shape in prices/providers/<provider>.yml (ordering, match/or style, fields). Include:

  • match.or: bare id, regex: '^<id>-\d{8}$', <provider>/-prefixed bare + dated, -latest
  • context_window
  • prices_checked: today's date (check the currentDate system reminder)
  • prices: input_mtok, cache_read_mtok (omit if the provider has none), output_mtok

Add a price_comments field when a value needs explanation/reference.

Those three keys cover the common case. The full vocabulary is derived from prices/units.yml — check it when the model bills for anything else (reasoning or citation tokens, per-modality rates, 1h cache writes, web searches, requests). Not every key is per-Mtok: _kcount is per 1,000, _mchars per 1M characters, _hours per 3,600s, _gpixels per 1e9, _kpages per 1,000. A per-Mtok figure under a _kcount key is valid YAML and wrong by 1000×. Prices must also cover their ancestors — a model with cache_write_1h_mtok needs cache_write_mtok too; make build will tell you which key is missing.

Do not add a new unit to prices/units.yml to make a model fit. That widens the published v2 schema and is a v3 change — see AGENTS.md § "Adding a unit". Open an issue instead.

Migrate family-level -latest aliases when the new model is the current flagship. Two kinds of -latest alias coexist, and they behave differently:

  • version-specific (<id>-latest, e.g. grok-4.3-latest) — always stays on its own entry.
  • family-level / bare (<provider>-latest, e.g. grok-latest) — means "the current flagship" and should point at whichever model is newest/best right now.

When adding a new flagship, move the family-level alias off the previous flagship onto the new entry (add it here, delete it there). First verify which model the vendor's alias actually resolves to — check the provider docs and, if you can, hit the API and read the response model field — then match that. Don't assume; the aliasing scheme is provider-specific (some vendors have no bare-family alias at all).

Google keeps one family alias per tier: gemini-flash-latest, gemini-flash-lite-latest and gemini-pro-latest. Each can point at a different generation, and Google's changelog does not record every move. Read the target from the modelVersion field of a Gemini API generateContent response (GOOGLE_API_KEY in ~/ai-coding-tools/.env) before you move one.

4b. Changing the price of a model that already exists

A provider changing its rates is not an edit to the existing prices: block. Overwriting those values re-prices every request the library ever priced for that model, so a request from before the change gets billed at the new rate. That is what happened to GPT-5.6 Luna and Terra in #531, and #535 had to undo it.

Add a dated entry instead. Convert prices: from a mapping to a list of conditional entries:

prices:
  - prices: # the rates that were already there, unchanged and unconstrained
      input_mtok: 1
      output_mtok: 6
  - constraint:
      # https://developers.openai.com/api/docs/changelog
      start_date: 2026-07-30
    prices: # the new rates
      input_mtok: 0.2
      output_mtok: 1.2
  • Put the entry with no constraint first. All three engines (Python, JS, Go) scan the list backwards and take the first entry whose constraint is active, so an unconstrained entry placed last would always win.
  • Set start_date to the date the provider's new price took effect, not to today. Cite the changelog or announcement that states that date, in a YAML comment beside start_date.
  • Set prices_checked to today. It records when you verified the rates, which is a different fact from when the rates changed.
  • Append one entry to a model that already uses a list. Leave the existing entries alone.
  • Check every price_variants rate card separately. Its listed rates are absolute; omitted keys inherit standard prices for that date. Preserve existing variants and prepend dated entries for changed tier rates, since the first matching value wins per price key. Cite a source for tiers whose rates stayed unchanged. Test each affected context on both sides of the date boundary in Python, JavaScript and Go.

Overwrite in place in exactly one case: the old value was wrong when it was written. A correction has no history worth preserving. State which of the two cases you are in, in the PR body.

Verify both sides of the boundary:

uv run python -c "
from datetime import datetime, timezone
from genai_prices import calc_price, Usage
u = Usage(input_tokens=1_000_000)
for day in [(2026, 7, 29), (2026, 7, 30)]:
    t = datetime(*day, tzinfo=timezone.utc)
    r = calc_price(u, '<id>', provider_id='<provider_id>', genai_request_timestamp=t)
    print(t.date(), '->', r.model_price.input_mtok, r.total_price)
"

Then pin both sides in tests/test_price_calc.py — one assertion the day before the change, one on the day of. A test that only covers the current rate passes just as well against an overwritten history, which is why #531 went green.

5. Build + verify resolution

Use make build, not just make build-prices. The installed genai_prices package (and the JS and Go packages) read their bundled data (packages/python/genai_prices/data.py, packages/js/src/data.ts, packages/go/internal/data/prices.json). make build-prices writes only prices/new_data/v2/* and prices/providers/.schema.json — it does not touch the bundled data, so a calc_price check run after it verifies stale package data and can silently show the wrong result. make build runs build-prices + package-data + inject-providers.

make build    # build-prices + package-data + inject-providers

Confirm the base id, the dated snapshot, the provider-prefixed dated id, and any -latest alias you touched all resolve to the intended entry (include the previous flagship to prove its version-specific -latest didn't move):

uv run python -c "
from genai_prices import calc_price, Usage
u = Usage(input_tokens=1000, output_tokens=1000)
for m in ['<id>', '<id>-<YYYYMMDD>', '<provider>/<id>-<YYYYMMDD>', '<provider>-latest', '<prev-id>-latest']:
    r = calc_price(u, m, provider_id='<provider_id>')
    print(m, '->', r.model.id, r.model.prices.input_mtok, r.model.prices.output_mtok)
"

6. Commit, push, PR

In a GitHub agentic workflow, follow its commit and safe-output procedure instead of the local commands below. Include this skill's price evidence, provider coverage, alias verification, and rollout findings in the PR body.

The pre-commit build hook regenerates twelve paths, so the first git commit will abort after it rewrites them; re-stage and commit again. Stage files explicitly — never git add -A (it leaks local/scratch files) — and never --no-verify, since that hook is what keeps the published data in sync with the YAML:

git add prices/providers/<provider>.yml \
        prices/providers/.schema.json \
        prices/new_data/v2/data.json prices/new_data/v2/data.schema.json \
        prices/new_data/v2/data_slim.json prices/new_data/v2/data_slim.schema.json \
        packages/python/genai_prices/data.py packages/python/genai_prices/data_units.py \
        packages/js/src/data.ts packages/js/src/dataUnits.ts \
        packages/go/internal/data/prices.json packages/go/data_units.go \
        README.md
git commit -m "Add <Provider> <Model> pricing"   # re-run once if hooks rewrite files
git push -u origin <slug>
gh pr create --base main --title "Add <Provider> <Model> pricing" --body "..."

A plain price addition usually only dirties a subset of these — git status after the aborted commit tells you which. The schema and *_units files change only when prices/units.yml does, which a price addition should not do.

Never force-push. PR body: pricing table, sources (provider docs + OpenRouter for cache rate), and scope notes (e.g. single variant / no cache-write / any -latest alias you moved, each with its one-line reason).

After pushing, don't go idle — poll until CI is green and every reviewer comment (cubic included) is addressed or dismissed (see AGENTS.md). Unresolved review threads mean the PR isn't mergeable.

Provider rollout timing

This is the escape hatch for step 0, not a reason to default to a single-provider PR. Cover every provider that already hosts the model in the same PR. OpenRouter usually lists new models day-one. Only when a reseller (Bedrock / Vertex) genuinely hasn't shipped yet do you defer that provider — name it in the PR body and follow up in a later PR once it lands, rather than blocking the rest.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.