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

add-provider

Skill416 starsChanged 31 days agoMITView on GitHub

Add a new inference provider to genai-prices, including provider data, matching, usage extractors, update automation, cassettes, agentic checks, generated artifacts, and Python/JavaScript/Go parity tests. Use for a new provider, not a new model on an existing provider.

18 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-tool, release-notes and 2 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    add-tool

    Add a new tool to PilotSwarm. Covers defining the tool with defineTool(), registering it on the worker (worker-level or per-session), referencing it from the client via toolNames, and adding an integration test.

    Also in 3 projects that use this

  • Microsoft AzureSkill

    release-notes

    Author and update release notes for Azure App Configuration libraries and providers. USE FOR: write release notes, add release note entry, update release notes, draft release notes, new version release notes, format release notes. DO NOT USE FOR: generating changelogs from git history, writing internal engineering notes.

    Also in 3 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. 0 are common, 9 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 11

    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. Distinctive:

    Add the provider as a complete, maintainable integration.

    line 8
  2. Distinctive:

    Use the provider's official pricing page and model catalog.

    line 12
  3. Very specific:

    Read prices/units.yml before mapping prices.

    line 14
  4. Very specific:

    Create prices/providers/<provider>.yml.

    line 23
  5. Very specific:

    use the exact API model ID as the canonical id

    line 36
  6. Distinctive:

    add precise aliases without creating matches against sibling models

    line 37
  7. Distinctive:

    Keep models sorted by ID. Use names and context windows from official documentation when available.

    line 44
  8. Distinctive:

    Add provider extractors for flavors that report usage.

    line 51
  9. Distinctive:

    If an API response does not report usage, leave that flavor unsupported and document the limitation instead of inventing a mapping.

    line 60
  10. Very specific:

    Every provider needs a way to update its prices automatically.

    line 65
  11. Very specific:

    Add prices/src/prices/source_<provider>.py, following source_novita.py (JSON) or source_cloudflare.py (Markdown):

    line 69
  12. Very specific:

    Test the real HTTP boundary with @pytest.mark.vcr, recorded with cassetter.

    line 85
  13. Distinctive:

    Use compact synthetic inputs only for pure parser and update-behavior tests.

    line 92
  14. Very specific:

    Add the YAML path to create-pull-request.allowed-files in both .github/workflows/agentic-price-check.md and …

    line 103
  15. Very specific:

    Update the hard-coded provider count in .github/workflows/agentic-price-check.md and .github/workflows/AGENTIC_PRICE_CHECK.md.

    line 106
  16. Distinctive:

    Add focused Python, JavaScript and Go tests for:

    line 119
  17. Distinctive:

    every usage extractor flavor

    line 124
  18. Very specific:

    Put the Go tests in packages/go/api_test.go, which runs against the bundled provider data.

    line 127
  19. Very specific:

    Run make build after every provider-data edit.

    line 130
  20. Very specific:

    Never hand-edit those outputs or tests/dataset/usages.json.

    line 131

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “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 provider

Add the provider as a complete, maintainable integration. Read AGENTS.md before editing. Preserve unrelated worktree changes.

Establish the supported scope

Use the provider's official pricing page and model catalog. Record the exact source URLs.

Read prices/units.yml before mapping prices. Include only billing units represented by the current published contract. Do not add a unit to make a provider fit because that is a v3 contract change. Explain excluded model categories in the provider's price_comments.

Decide whether the official source is a complete catalog or only a pricing page. This determines whether missing models can be treated as potential removals.

Author the provider YAML

Create prices/providers/<provider>.yml. Never edit generated artifacts directly.

Cover these fields when they apply:

  • id, name, and official pricing_urls
  • api_pattern for the provider's actual API hosts and paths
  • provider_match for common provider identifiers
  • model_match only when the provider owns an unambiguous model-ID namespace
  • fallback_model_providers only when another provider's prices are intentionally inherited
  • price_comments for free allowances, unsupported units, regional differences, or other calculation boundaries

For each supported model:

  • use the exact API model ID as the canonical id
  • add precise aliases without creating matches against sibling models
  • map official rates to the correct units, such as _mtok, _kcount, or _mchars
  • include cache, reasoning, modality, request, and tool rates when represented by the unit registry
  • set prices_checked to the verification date
  • preserve historical price changes with dated conditional prices instead of overwriting old rates
  • mark officially deprecated models without inferring removal from an incomplete source

Keep models sorted by ID. Use names and context windows from official documentation when available.

Add usage extraction

Inspect recorded or documented response bodies for every supported API flavor. Do not assume that an OpenAI-compatible endpoint has the same response as the provider's native endpoint.

Add provider extractors for flavors that report usage. Extract the model when the response includes it. When the response omits the model, return the usage with a nullable model so callers can provide the request model during price calculation. Map cached tokens separately. Any extractor that maps completion_tokens must also map the provider's reasoning-token breakdown to output_reasoning_tokens. Test each flavor through the public Python, JavaScript and Go extraction APIs.

A caller that doesn't pass a flavor asks for default, so default, if the provider has one, reads its own API. Give every other API the provider serves, including another company's API it passes along, its own flavor name. See the api_flavor bullet in AGENTS.md for an example.

If an API response does not report usage, leave that flavor unsupported and document the limitation instead of inventing a mapping.

Add an automatic price update

Every provider needs a way to update its prices automatically. Look for an official source a script can read without credentials, in this order: a pricing API or /v1/models response with prices, a Markdown docs page (.md, llms.txt), then JSON embedded in the official pricing page. Treat an HTML fallback served for a .md URL as unreadable.

Add prices/src/prices/source_<provider>.py, following source_novita.py (JSON) or source_cloudflare.py (Markdown):

  • fetch with httpx2 and parse prices as Decimal
  • return ModelInfo entries from a public parse_* function and write them with ProviderYaml.upsert_models, which adds new models, appends changed rates as dated conditional prices, and keeps curated keys the source does not report
  • emit only the keys the source reports, and parse tiers when the source has them instead of flattening them
  • set a MIN_MODEL_COUNT so an empty or truncated response refuses to write
  • fail loudly when the source is unreadable or changes shape

Expose get_<provider>_prices through prices.__main__. Add <provider>-get to Makefile, include it in get-all-prices, and add <provider> to the matrix.importer list in .github/workflows/update-prices.yml, which runs every importer hourly and keeps one rolling PR.

Pin tests that assert the provider's current rates to an explicit timestamp. Otherwise the first hourly rate change breaks CI on the rolling PR.

Test the real HTTP boundary with @pytest.mark.vcr, recorded with cassetter. Record the official response, inspect the cassette, commit it, and prove replay with:

uv run pytest tests/test_source_<provider>.py --record-mode=none

Use compact synthetic inputs only for pure parser and update-behavior tests. Do not replace the external request with a hand-written HTTP mock.

A provider without an importer is the exception. If no source a script can read exists, list the URLs you checked in the PR and rely on agentic monitoring alone.

Add agentic monitoring

The weekly agentic check is the fallback for what an importer cannot see: announced future prices, promotions, and new units or tiers. Add the provider to .github/agentic-price-check-providers.yml with its YAML path, exact official sources, supported scope, and unit-mapping notes. Add every source domain to network.allowed in .github/workflows/shared/price-check-network.md. Add the YAML path to create-pull-request.allowed-files in both .github/workflows/agentic-price-check.md and .github/workflows/agentic-model-price-check.md, or targeted model checks cannot open a PR for the provider.

Update the hard-coded provider count in .github/workflows/agentic-price-check.md and .github/workflows/AGENTIC_PRICE_CHECK.md. Compile the lock files with gh-aw v0.91.1, the version pinned in them, so a different local compiler cannot rewrite them. Never hand-edit a lock file.

gh extension install github/gh-aw --pin v0.91.1 --force
gh aw compile agentic-price-check agentic-model-price-check --no-check-update

The agentic workflow opens at most one PR of verified price updates per run.

Verify every runtime

Add focused Python, JavaScript and Go tests for:

  • provider selection by explicit provider ID
  • provider selection by API URL and model namespace when supported
  • representative input, cached-input, and output price calculation
  • every usage extractor flavor
  • aliases and context-sensitive matching that could collide

Put the Go tests in packages/go/api_test.go, which runs against the bundled provider data. Test updater parsing, metadata preservation, write guards, and cassette replay in Python only: the updater lives in prices/src/prices/.

Run make build after every provider-data edit. This regenerates the v2 feed, package data, schemas, and provider inventory. Never hand-edit those outputs or tests/dataset/usages.json.

Before handoff, run:

make all
git diff --check

Inspect the provider YAML, cassette, and generated diff. Confirm that frozen v1 files are unchanged. Follow AGENTS.md for the commit, PR description, AI disclaimer, CI monitoring, and review resolution.

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.